humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,47 @@
+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";
+/** What the scripted lab's bundle is built from. */
+interface ScriptedBundleArgs {
+    /** Lab provenance for the bundle\'s own `lab` field (#455). */
+    lab?: RunLabProvenance;
+    actorId: string;
+    appUrl: string;
+    createdAt: string;
+    desktopTemplate?: string;
+    dryRun: boolean;
+    hostDigest?: string;
+    journey: BrowserPersonaJourney;
+    labId: string;
+    labTitle?: string;
+    persona: ActorPersonaRef;
+    runId: string;
+    scenarioSource: string;
+    scenarioSourceDigest: string;
+    screenshotsBySurface: Map<string, string[]>;
+    sessionResults: ScriptedBrowserSessionResult[];
+    sessionError?: string;
+    source: RunBundle["source"];
+    subject?: RunSubjectProvenance;
+    /** The provisioned clone's desktop; absent when no sandbox was created. */
+    subjectDesktop?: {
+        durationMs: number | undefined;
+        observation: DesktopResourceObservation | undefined;
+        killed: boolean;
+    };
+    surfaces: readonly BrowserSurface[];
+    /** The run's verdict (judgeScripted). */
+    verdict: ReviewSummary["verdict"];
+}
+/**
+ * Project the scripted lab run into a humanish.run-bundle.v1 (no schema change — a new
+ * producer only). The load-bearing line is `stream.actor = result.trace`: the provider-neutral
+ * ActorTrace seam the Observer renders and verifyRun's engagement check reads. Exported for
+ * the bundle-builder tests.
+ */
+export declare function buildScriptedLabBundle(args: ScriptedBundleArgs): RunBundle;
+export declare function renderScriptedReviewMarkdown(bundle: RunBundle): string;
+export {};

package/dist/routes/scripted/bundle.js

@@ -0,0 +1,195 @@
+// Assemble the scripted-browser lab's run bundle from its sessions, and the review summary and
+// markdown that ship with it.
+import { redactText } from "../../evidence/redaction.js";
+import { buildRunCostSummary, desktopSpanToMinutes, spendFreeCostSummary, } from "../../run/cost-summary.js";
+import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
+import {} from "../../run/streams.js";
+import { participantEvent, recordIdOf } from "../../run/participant-records.js";
+import { scriptedSurfaceIds, scriptedSurfaceRecords } from "./surface-records.js";
+/**
+ * Project the scripted lab run into a humanish.run-bundle.v1 (no schema change — a new
+ * producer only). The load-bearing line is `stream.actor = result.trace`: the provider-neutral
+ * ActorTrace seam the Observer renders and verifyRun's engagement check reads. Exported for
+ * the bundle-builder tests.
+ */
+export function buildScriptedLabBundle(args) {
+    const resultBySurface = new Map(args.sessionResults.map((result) => [result.capture.surface.id, result]));
+    const records = args.surfaces.map((surface, index) => scriptedSurfaceRecords(args, 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,
+        }),
+        persona: {
+            id: args.persona.id,
+            name: `Scripted journey persona (${args.persona.id})`,
+            source: `lab:${args.labId}`,
+            sourceDigest: args.persona.promptDigest,
+        },
+        scenario: {
+            id: args.journey.scenarioId,
+            title: args.journey.scenarioTitle,
+            goal: redactText(args.journey.goal),
+            source: args.scenarioSource,
+            sourceDigest: args.scenarioSourceDigest,
+        },
+        lifecycle: [
+            {
+                at: args.createdAt,
+                event: "scripted-lab.run.created",
+                message: `Created scripted-browser lab run with ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"} (actor ${args.actorId}).`,
+            },
+        ],
+        simulations: records.map((record) => record.simulation),
+        streams: records.map((record) => record.stream),
+        events,
+        redaction: {
+            status: "passed",
+            notes: ranLive
+                ? "Scripted step URLs are sanitized to loopback origin+path (query/hash redacted) and step text passes text redaction. Screenshots are FULL-FIDELITY (raw), retained for local use in gitignored .humanish — NOT redacted for publishing; policies.redactScreenshots is not yet supported on this route."
+                : "Dry-run contract bundle: no browser ran and no screenshots were captured. The scenario contract is digest-pinned; live step text passes text redaction when a session runs.",
+        },
+        artifacts: bundleArtifacts(),
+        review,
+        feedbackCandidates: [],
+        ...(args.subject === undefined ? {} : { subject: args.subject }),
+        ...(args.desktopTemplate === undefined ? {} : { desktopTemplate: args.desktopTemplate }),
+        ...(cost === undefined ? {} : { cost }),
+    };
+}
+/** The created, subject and spend events, then one event per session or the run's outcome. */
+function scriptedEvents(args) {
+    const events = [
+        {
+            id: "event-000-created",
+            at: args.createdAt,
+            level: "info",
+            type: "scripted-lab.run.created",
+            message: `Created scripted-browser lab run for ${args.labId} (actor ${args.actorId}, ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"}).`,
+        },
+        {
+            id: "event-001-subject",
+            at: args.createdAt,
+            level: "info",
+            type: "scripted-lab.subject.declared",
+            // Invariant 5: provenance recorded or its absence DECLARED. The lab did not provision
+            // this subject on app-url routes; clone routes carry structured subject provenance below.
+            message: args.subject
+                ? `Provisioned synthetic subject: clone of ${args.subject.repo}${args.subject.commit ? `@${args.subject.commit}` : ""}, served + getHost-exposed in-sandbox; env names: ${args.subject.envNames?.join(", ") || "none"} (values never persisted); state provenance: ${args.subject.state.provenance}; evidence host digest: ${args.hostDigest ?? "dry-run"}.`
+                : `Subject app declared at ${args.appUrl}; the lab did not provision it — subject build/commit provenance is UNPINNED; evidence binds to the scenario digest ${args.scenarioSourceDigest}.`,
+        },
+        {
+            id: "event-002-spend",
+            at: args.createdAt,
+            level: "info",
+            type: "scripted-lab.spend",
+            message: args.subject
+                ? "Scripted participant steps make no model requests; post-run analysis has a separate budget unless disabled. Live provisioned runs may spend E2B sandbox minutes to clone/serve the synthetic subject."
+                : "Scripted participant steps make no model requests and use no sandbox on this route; post-run analysis has a separate budget unless disabled. scenario.mode: live gates real browser actuation against the declared app.",
+        },
+    ];
+    if (args.sessionResults.length > 0) {
+        for (const result of args.sessionResults) {
+            events.push(participantEvent(scriptedSurfaceIds(result.capture.surface.id), {
+                id: `event-${String(events.length).padStart(3, "0")}-session-${result.capture.surface.id}`,
+                at: result.capture.capturedAt,
+                level: result.status === "passed" ? "info" : "warn",
+                type: `scripted-lab.session.${result.completionReason}`,
+                message: `${result.capture.surface.id}: ${result.status} — ${result.reason}`,
+            }));
+        }
+    }
+    else if (args.sessionError !== undefined) {
+        events.push({
+            id: "event-003-session-error",
+            at: args.createdAt,
+            level: "error",
+            type: "scripted-lab.session.error",
+            message: args.sessionError,
+        });
+    }
+    else {
+        events.push({
+            id: "event-003-contract",
+            at: args.createdAt,
+            level: "info",
+            type: "scripted-lab.contract.ready",
+            message: `Dry-run contract bundle ready: scenario ${args.journey.scenarioId} @ ${args.scenarioSourceDigest} (${args.scenarioSource}, ${args.journey.steps.length} step${args.journey.steps.length === 1 ? "" : "s"}) parsed and digest-pinned; switch scenario.mode to live to actuate a real browser.`,
+        });
+    }
+    return events;
+}
+/** No model runs on this route; the only spend is a provisioned clone's desktop. */
+function scriptedCost(subjectDesktop) {
+    if (subjectDesktop === undefined)
+        return spendFreeCostSummary();
+    return buildRunCostSummary({
+        participants: [],
+        desktops: [
+            {
+                participantId: "subject",
+                minutes: desktopSpanToMinutes(subjectDesktop.durationMs),
+                observation: subjectDesktop.observation,
+                lifetimeComplete: subjectDesktop.killed,
+            },
+        ],
+    });
+}
+function buildScriptedReview(args) {
+    if (args.sessionError !== undefined) {
+        return {
+            schema: REVIEW_SCHEMA,
+            verdict: args.verdict,
+            summary: `Scripted lab failed before a terminal session verdict: ${args.sessionError}`,
+            gaps: [],
+        };
+    }
+    if (args.sessionResults.length === 0) {
+        return {
+            schema: REVIEW_SCHEMA,
+            verdict: args.verdict,
+            summary: `Dry-run contract for scenario ${args.journey.scenarioId} (${args.scenarioSource}, ${args.journey.steps.length} steps) against ${args.appUrl}: composition and scenario contract proven at $0; no browser ran.`,
+            gaps: ["Live scripted session not yet run (dry-run contract only)."],
+        };
+    }
+    const passed = args.sessionResults.filter((result) => result.status === "passed").length;
+    return {
+        schema: REVIEW_SCHEMA,
+        verdict: args.verdict,
+        summary: `Scripted-browser actor replayed ${args.journey.scenarioId} on ${args.sessionResults.length} surface${args.sessionResults.length === 1 ? "" : "s"} against ${args.appUrl}: ${passed}/${args.sessionResults.length} satisfied the scenario predicate.`,
+        gaps: args.sessionResults
+            .filter((result) => result.status !== "passed")
+            .map((result) => `${result.capture.surface.id}: ${result.reason}`),
+    };
+}
+export function renderScriptedReviewMarkdown(bundle) {
+    const subject = bundle.events.find((event) => event.type === "scripted-lab.subject.declared");
+    const spend = bundle.events.find((event) => event.type === "scripted-lab.spend");
+    const traces = bundle.streams
+        .map((stream) => ({ stream, trace: stream.actor }))
+        .filter((entry) => entry.trace !== undefined);
+    return [
+        `# ${bundle.scenario.title}`,
+        "",
+        `- run: ${bundle.runId}`,
+        `- mode: ${bundle.mode}`,
+        `- verdict: ${bundle.review.verdict}`,
+        `- summary: ${bundle.review.summary}`,
+        `- scenario: ${bundle.scenario.id} @ ${bundle.scenario.sourceDigest} (${bundle.scenario.source})`,
+        ...(subject ? [`- subject: ${subject.message}`] : []),
+        ...(spend ? [`- spend: ${spend.message}`] : []),
+        ...traces.map(({ stream, trace }) => `- ${recordIdOf(stream)}: ${trace.provider} (${trace.lane}/${trace.protocol}) ${trace.status} (${trace.completionReason}); ${trace.counts.actions ?? 0} step action(s), ${trace.counts.screenshots ?? 0} raw screenshot(s)`),
+        ...(bundle.review.gaps.length > 0
+            ? ["", "## Gaps", ...bundle.review.gaps.map((gap) => `- ${gap}`)]
+            : []),
+        "",
+    ].join("\n");
+}

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

@@ -0,0 +1,30 @@
+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"> {
+    /**
+     * Set on the receiving, analysis and tasks refusals. The route returns those before it opens its
+     * run scope, so their result has its own field order and no automatic-analysis record.
+     */
+    readonly beforeScope?: true;
+    /** The registered actor id and the app URL the evidence names, once the chain has them. */
+    readonly actor?: string;
+    readonly appUrl?: string;
+}
+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;
+/**
+ * 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;
+    };
+}): ScriptedPlanResult;

package/dist/routes/scripted/plan.js

@@ -0,0 +1,95 @@
+// The scripted route's plan: every configuration refusal the route makes before a run starts, in
+// its order and with its codes, then the plan the run uses. What stays in the route reads external
+// state: the scenario file, the E2B key, subject env values and the host browser.
+import { actorRegistry, isScriptedBrowserActorDescriptor } from "../../actors/registry.js";
+import { normalizeLocalAppUrl } from "../../actors/scripted-browser/steps.js";
+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;
+// `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;
+}
+/**
+ * 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 function planScriptedLab(config, input) {
+    const refuse = (code, message, extras = {}) => ({
+        ok: false,
+        refusal: { route: "scripted", code, message, ...extras },
+    });
+    const beforeScope = { beforeScope: true };
+    if (String(config.comms?.email?.kind) === "real")
+        return refuse("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", "Real email receiving is unsupported on the scripted route. Use a supported hosted computer-use browser lab.", beforeScope);
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    if (!analysis.ok)
+        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message, beforeScope);
+    const tasksReason = taskProtocolValidationReason(config, false);
+    if (tasksReason)
+        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason, beforeScope);
+    const mediaReason = desktopMediaValidationReason(config);
+    if (mediaReason)
+        return refuse("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", mediaReason);
+    const cloneTargetReason = cloneTargetValidationReason(config);
+    if (cloneTargetReason)
+        return refuse("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", cloneTargetReason);
+    const actorType = config.actors[0]?.type ?? "";
+    const descriptor = actorRegistry[actorType];
+    if (!descriptor || !isScriptedBrowserActorDescriptor(descriptor))
+        return refuse("HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered scripted-browser actor.`);
+    const actor = descriptor.id;
+    // The parser checks the loopback entry too; a library caller skips the parser. A clone's URL is
+    // minted by getHost during the run, and its evidence names only the placeholder.
+    let subject;
+    if (config.subject.source === "clone") {
+        const provisioned = provisionedSubject(config);
+        if (provisioned?.kind !== "clone" || !provisioned.repo)
+            return refuse("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", "clone scripted-browser labs require one subject repo plus subject.serve; parseLabConfig should have rejected this config.", { actor, appUrl: "[provisioned-subject]" });
+        subject = provisioned;
+    }
+    else {
+        const appUrl = normalizeLocalAppUrl(config.subject.appUrl ?? "");
+        if (!appUrl)
+            return refuse("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", "subject.appUrl must be a loopback http(s) URL (127.0.0.1 or localhost) on the scripted-browser route.", { actor });
+        subject = { kind: "loopback", appUrl };
+    }
+    // The steps are the actor, so there is no built-in journey to fall back on.
+    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" });
+        if (isNonEmpty(subject.env))
+            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)
+        requirements.push({ kind: "host-browser" });
+    const persona = config.actors[0]?.persona;
+    const timeoutMs = config.execution?.timeoutMs;
+    return {
+        ok: true,
+        plan: {
+            ...planBase(config, {
+                dryRun: input.dryRun,
+                ...(input.lab === undefined ? {} : { lab: input.lab }),
+                analysis,
+            }),
+            route: "scripted",
+            actor,
+            subject,
+            scenarioRef,
+            surfaces: browserSurfaces.slice(0, config.actors[0]?.count ?? DEFAULT_SURFACE_COUNT),
+            ...(persona === undefined ? {} : { personaId: persona }),
+            ...(timeoutMs === undefined ? {} : { sessionTimeoutMs: timeoutMs }),
+            requirements,
+        },
+    };
+}

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

@@ -0,0 +1,48 @@
+import type { ActorPersonaRef } from "../../actors/contract.js";
+import type { ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
+import type { BrowserPersonaJourney } from "../../actors/scripted-browser/types.js";
+import type { ScriptedPlan } from "../../lab/plan-types.js";
+import type { RunBundle } from "../../run/bundle.js";
+import type { RunScope } from "../../run/run.js";
+import { type ExecutionFailure } from "../../run/judge.js";
+import type { ObserverResult } from "../../observer/render.js";
+import type { ScriptedSubject } from "./subject.js";
+import { type ScriptedBrowserLabResult } from "./types.js";
+/** What the finish reads from the run. */
+export interface ScriptedFinishInputs {
+    plan: ScriptedPlan;
+    cwd: string;
+    evidenceAppUrl: string;
+    run: Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
+        ok: true;
+    }>["run"];
+    source: RunBundle["source"];
+    journey: BrowserPersonaJourney;
+    scenario: {
+        source: string;
+        sourceDigest: string;
+    };
+    persona: ActorPersonaRef;
+    surfaces: ScriptedPlan["surfaces"];
+    sessionResults: ScriptedBrowserSessionResult[];
+    sessionError: string | undefined;
+    warnings: string[];
+    clone: Extract<ScriptedPlan["subject"], {
+        readonly kind: "clone";
+    }> | undefined;
+    redactRepoLabel: boolean;
+    subjectEnvNames: string[];
+    scriptedSubject: ScriptedSubject | undefined;
+}
+/**
+ * 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.
+ */
+export declare function scriptedExecutionFailures(args: {
+    dryRun: boolean;
+    sessionError: string | undefined;
+    expected: number;
+    sessionResults: readonly Pick<ScriptedBrowserSessionResult, "completionReason" | "reason">[];
+    observer: Pick<ObserverResult, "ok" | "error">;
+}): ExecutionFailure[];
+export declare function finishScriptedRun(inputs: ScriptedFinishInputs): Promise<ScriptedBrowserLabResult>;

package/dist/routes/scripted/result.js

@@ -0,0 +1,176 @@
+import { judgeExecution, 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";
+import { existingScreenshots } from "./session-result.js";
+import { SCRIPTED_BROWSER_LAB_SCHEMA } from "./types.js";
+/** What judgeScripted reads from one surface's session. Scripted has no engagement or blocker rule. */
+function scriptedSurfaceFacts(result) {
+    return {
+        status: result.status,
+        completionReason: result.completionReason,
+        skipped: false,
+        noEngagement: false,
+        selfReportedBlocker: false,
+    };
+}
+/**
+ * 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.
+ */
+export function scriptedExecutionFailures(args) {
+    const { sessionError, sessionResults, observer } = args;
+    const harnessErrorSession = sessionResults.find((result) => result.completionReason === "harness_error");
+    return [
+        ...(sessionError === undefined ? [] : [{ kind: "harness", message: sessionError }]),
+        ...(harnessErrorSession === undefined
+            ? []
+            : [
+                {
+                    kind: "harness",
+                    message: `Scripted session ended with a harness error: ${harnessErrorSession.reason}`,
+                },
+            ]),
+        ...(!args.dryRun && sessionError === undefined && sessionResults.length !== args.expected
+            ? [
+                {
+                    kind: "harness",
+                    message: "Scripted lab did not produce terminal sessions for every surface.",
+                },
+            ]
+            : []),
+        ...(observer.ok
+            ? []
+            : [
+                {
+                    kind: "evidence",
+                    message: observer.error?.message ?? "Observer failed for the scripted lab run.",
+                },
+            ]),
+    ];
+}
+export async function finishScriptedRun(inputs) {
+    const { plan, cwd, evidenceAppUrl, run, source, journey, scenario, persona } = inputs;
+    const { surfaces, sessionResults, sessionError, warnings, clone, redactRepoLabel } = inputs;
+    const { subjectEnvNames, scriptedSubject } = inputs;
+    const { actor, dryRun } = plan;
+    const { runId, createdAt, paths: runPaths } = run;
+    const subjectCommit = scriptedSubject?.commit;
+    const subjectSandboxId = scriptedSubject?.sandboxId;
+    const subjectKilled = scriptedSubject?.killed ?? false;
+    const hostDigest = scriptedSubject?.hostDigest;
+    const stateStepRecords = scriptedSubject?.stateStepRecords ?? [];
+    const subjectDesktop = scriptedSubject?.desktopUsage();
+    const screenshotsBySurface = new Map();
+    for (const result of sessionResults) {
+        screenshotsBySurface.set(result.capture.surface.id, await existingScreenshots(runPaths, result));
+    }
+    const subject = clone
+        ? {
+            source: "clone",
+            repo: redactRepoLabel ? "repo-01" : clone.repo,
+            ...(subjectCommit === undefined ? {} : { commit: subjectCommit }),
+            envNames: subjectEnvNames,
+            state: resolveSubjectState({
+                declared: clone.state,
+                dryRun,
+                executed: stateStepRecords,
+            }),
+        }
+        : undefined;
+    // One judgment for the bundle's verdict and the result's ok.
+    const judgment = judgeScripted({
+        dryRun,
+        sessionError,
+        expected: surfaces.length,
+        surfaces: sessionResults.map(scriptedSurfaceFacts),
+    });
+    const bundle = buildScriptedLabBundle({
+        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        actorId: actor,
+        appUrl: evidenceAppUrl,
+        createdAt,
+        dryRun,
+        journey,
+        labId: plan.labId,
+        ...(plan.title ? { labTitle: plan.title } : {}),
+        persona,
+        runId,
+        scenarioSource: scenario.source,
+        scenarioSourceDigest: scenario.sourceDigest,
+        screenshotsBySurface,
+        sessionResults,
+        ...(sessionError === undefined ? {} : { sessionError }),
+        source,
+        surfaces,
+        verdict: judgment.verdict,
+        ...(subject === undefined ? {} : { subject }),
+        ...(subjectDesktop === undefined ? {} : { subjectDesktop }),
+        ...(plan.residual.execution?.desktop?.template === undefined
+            ? {}
+            : { desktopTemplate: plan.residual.execution.desktop.template }),
+        ...(hostDigest === undefined ? {} : { hostDigest }),
+    });
+    const finished = await run.finish(bundle);
+    // Surface the local-fidelity posture so the operator knows the bundle is not publish-safe as-is.
+    if (sessionResults.some((result) => result.trace.redaction.screenshots === "raw")) {
+        warnings.push("Screenshots are full-fidelity (raw) for local use — the bundle stays in gitignored .humanish and nothing scans these pixels; review them before sharing anywhere. policies.redactScreenshots is not yet supported on the scripted route.");
+    }
+    const observer = await finished.renderObserver();
+    await validatePreparedRunArtifactPaths(runPaths);
+    // A failing surface is captured evidence on this route: only the execution fails ok.
+    const policy = OUTCOME_POLICIES.scripted;
+    const execution = judgeExecution(scriptedExecutionFailures({
+        dryRun,
+        sessionError,
+        expected: surfaces.length,
+        sessionResults,
+        observer,
+    }), policy);
+    const ok = resultOk({ judgment, execution, scorerFailures: [], policy });
+    await finished.recordOutcome({ ok, execution });
+    const harnessErrorSession = sessionResults.find((result) => result.completionReason === "harness_error");
+    return {
+        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ok,
+        cwd,
+        labId: plan.labId,
+        actor,
+        appUrl: evidenceAppUrl,
+        dryRun,
+        runId,
+        ...(subject === undefined ? {} : { subject }),
+        ...(subjectSandboxId === undefined
+            ? {}
+            : { subjectSandbox: { sandboxId: subjectSandboxId, killed: subjectKilled } }),
+        ...(hostDigest === undefined ? {} : { hostDigest }),
+        scenario: {
+            id: journey.scenarioId,
+            source: scenario.source,
+            sourceDigest: scenario.sourceDigest,
+            steps: journey.steps.length,
+        },
+        sessions: sessionResults.map((result) => ({
+            surface: result.capture.surface.id,
+            status: result.status,
+            completionReason: result.completionReason,
+            reason: result.reason,
+            screenshots: screenshotsBySurface.get(result.capture.surface.id)?.length ?? 0,
+        })),
+        observer,
+        warnings: [...warnings, ...observer.warnings],
+        ...(ok
+            ? {}
+            : {
+                error: {
+                    code: "HUMANISH_SCRIPTED_LAB_FAILED",
+                    message: sessionError ??
+                        (observer.ok
+                            ? harnessErrorSession
+                                ? `Scripted session ended with a harness error: ${harnessErrorSession.reason}`
+                                : "Scripted lab did not produce terminal sessions for every surface."
+                            : (observer.error?.message ?? "Observer failed for the scripted lab run.")),
+                },
+            }),
+    };
+}

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

@@ -0,0 +1,28 @@
+import type { ScriptedPlan } from "../../lab/plan-types.js";
+import type { AdmittedPlan } from "../../run-lab.js";
+import { type ScriptedRefusal } from "./plan.js";
+import { type RunScriptedBrowserLabOptions, type ScriptedBrowserLabResult, type ScriptedRunInput } 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 declare function runScriptedBrowserLab(options: RunScriptedBrowserLabOptions): Promise<ScriptedBrowserLabResult>;
+/**
+ * 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 declare function scriptedLabRefusal(options: RunScriptedBrowserLabOptions, refusal: ScriptedRefusal): Promise<ScriptedBrowserLabResult>;
+/**
+ * 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 declare function admitScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): AdmittedPlan<"scripted">;
+/**
+ * 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 declare function runScriptedPlan(plan: ScriptedPlan, input: ScriptedRunInput): Promise<ScriptedBrowserLabResult>;