humanish 0.104.3 → 0.106.0

package/dist/actors/registry.js

@@ -0,0 +1,89 @@
+import { runCodexAppServerSession, } from "./codex/app-server.js";
+import { CODEX_APP_SERVER_CAPABILITIES, SCRIPTED_BROWSER_CAPABILITIES, TERMINAL_AGENT_CAPABILITIES, } from "./contract.js";
+import { codexResultToActorTrace } from "./codex/app-server-actor-trace.js";
+import { runCuaActorSession } from "./computer-use/actor.js";
+import { LOCAL_AGENT_CAPABILITIES } from "./local-agent/cli.js";
+import { OPENAI_RESPONSES_CU_CAPABILITIES } from "./computer-use/openai-provider.js";
+import { runScriptedBrowserSession, } from "./scripted-browser/actor.js";
+/**
+ * REGISTRY CONTRACT: an actor whose capabilities include the "computer-use" lane is a
+ * CuaActorDescriptor — its runSession takes CuaActorSessionOptions and returns a CuaLoopResult.
+ * Any future computer-use provider (e.g. stagehand-cua) must keep that session signature and add
+ * its id to CuaActorDescriptor["id"], so code narrowed by this guard can still tell the ids apart.
+ * This guard is what lets the lab dispatch on capabilities rather than on hardcoded actor ids.
+ */
+export function isCuaActorDescriptor(descriptor) {
+    return descriptor.capabilities.lanes.includes("computer-use");
+}
+/**
+ * REGISTRY CONTRACT (mirror of isCuaActorDescriptor): an actor whose capabilities include the
+ * "scripted-browser" lane IS a ScriptedBrowserActorDescriptor — runSession takes
+ * ScriptedBrowserSessionOptions and returns ScriptedBrowserSessionResult (trace fully formed,
+ * like the CUA shape — no separate toActorTrace). Any future scripted driver (e.g. a HAR
+ * replayer) must keep this signature; it is what lets the lab dispatch on capabilities, not ids.
+ */
+export function isScriptedBrowserActorDescriptor(descriptor) {
+    return descriptor.capabilities.lanes.includes("scripted-browser");
+}
+/**
+ * REGISTRY CONTRACT (mirror of isCuaActorDescriptor / isScriptedBrowserActorDescriptor): an actor
+ * whose capabilities include the "terminal" lane IS a TerminalActorDescriptor. This is the guard
+ * the terminal-product lab uses for route selection and capability enforcement. The current
+ * descriptor's direct runSession is intentionally unsupported; live execution is route-owned.
+ * Any future terminal actor must declare keyPlacement honestly and integrate with that lifecycle.
+ */
+export function isTerminalActorDescriptor(descriptor) {
+    return descriptor.capabilities.lanes.includes("terminal");
+}
+export const actorRegistry = {
+    "codex-app-server": {
+        id: "codex-app-server",
+        label: "Codex App-Server",
+        capabilities: CODEX_APP_SERVER_CAPABILITIES,
+        runSession: runCodexAppServerSession,
+        toActorTrace: codexResultToActorTrace,
+    },
+    // The ActorId names the actor slot (keeps the lane open for a future stagehand-cua provider);
+    // the trace's `provider` string stays "openai-responses-cu" (the concrete model adapter).
+    // The operator's own signed-in coding agent as the computer-use brain (Codex on a ChatGPT plan,
+    // Claude Code on a Max plan). Same lane, same loop, same evidence — the only difference is where
+    // the next action comes from, which is exactly why it is a provider swap and not a new lane.
+    // It exists so someone new can watch a persona drive a real desktop without first going to find
+    // an API key; the machine they are on very often already has one of these signed in.
+    "local-agent": {
+        id: "local-agent",
+        label: "Local coding agent (operator-authenticated)",
+        capabilities: LOCAL_AGENT_CAPABILITIES,
+        runSession: runCuaActorSession,
+    },
+    "openai-computer-use": {
+        id: "openai-computer-use",
+        label: "OpenAI Computer Use",
+        capabilities: OPENAI_RESPONSES_CU_CAPABILITIES,
+        runSession: runCuaActorSession,
+    },
+    // Same naming convention: the ActorId names the slot; the trace's `provider` stays the
+    // concrete driver name "browser-persona" (matching the native
+    // humanish.browser-persona-trace.v1 evidence it already emits).
+    "scripted-browser": {
+        id: "scripted-browser",
+        label: "Scripted Browser (deterministic Playwright steps)",
+        capabilities: SCRIPTED_BROWSER_CAPABILITIES,
+        runSession: runScriptedBrowserSession,
+    },
+    // The ActorId names the terminal-product dispatch slot; the live route records the concrete
+    // provider as "codex". keyPlacement "in-sandbox-command-scoped" is registry-declared and
+    // enforced by runTerminalProductLab before it creates a sandbox, which is where this actor runs.
+    "codex-exec": {
+        id: "codex-exec",
+        label: "Codex Exec (autonomous terminal agent, in-sandbox)",
+        capabilities: TERMINAL_AGENT_CAPABILITIES,
+    },
+};
+export function getActor(id) {
+    const actor = actorRegistry[id];
+    if (!actor) {
+        throw new Error(`Unknown actor: ${String(id)}`);
+    }
+    return actor;
+}

package/dist/actors/scripted-browser/actor.d.ts

@@ -0,0 +1,49 @@
+import { type PreparedOutputRoot } from "../../run/contained-output.js";
+import { type ActorPersonaRef, type ActorSessionResult } from "../contract.js";
+import { type BrowserPersonaJourney, type BrowserSurface, type BrowserSurfaceCapture, type ScriptedBrowserEvidenceUrlPolicy, type ScriptedBrowserLaunchArgs, type ScriptedBrowserLike } from "./types.js";
+export interface ScriptedBrowserSessionOptions {
+    /** Pre-normalized loopback URL, or a harness-minted provisioned subject URL. */
+    appUrl: string;
+    /** Stable redacted URL label persisted in public-safe evidence when appUrl is private. */
+    evidenceAppUrl?: string;
+    /** Defaults to loopback. Provisioned subjects drive a private URL but persist redacted labels. */
+    urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
+    /** Parsed + validated by the backend (scenario.ref is consumed there, fail-closed). */
+    journey: BrowserPersonaJourney;
+    /** ONE session per surface lane. */
+    surface: BrowserSurface;
+    /** id = actors[0].persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
+     *  (the step manifest IS the "prompt" — no model prompt exists on this lane). */
+    persona: ActorPersonaRef;
+    /** Journey wall-clock budget in ms; the lab route passes execution.timeoutMs or 300_000. */
+    timeoutMs: number;
+    /** Absolute; the session writes screenshots/ and traces/<surface>.json beneath it. */
+    artifactRoot: string;
+    /** Default resolveBrowserCommand(); recorded as "injected-browser" when launchBrowser is injected. */
+    browserCommand?: string;
+    /** DI seam; production default is launchPlaywrightChromium. */
+    launchBrowser?: (args: ScriptedBrowserLaunchArgs) => Promise<ScriptedBrowserLike>;
+    now?: () => number;
+}
+export interface ScriptedBrowserSessionResult extends ActorSessionResult {
+    /** Native evidence incl. tracePath (humanish.browser-persona-trace.v1, written to disk). */
+    capture: BrowserSurfaceCapture;
+}
+/**
+ * Run the scripted journey for ONE surface and return native capture + ActorTrace projection.
+ *
+ * Completion semantics (the contract the projection tests pin):
+ * - every step executed, every assertion passed, HTTP probe ok -> passed / goal_satisfied
+ *   (the scenario's expect blocks ARE the success predicate; a pass claims "the app still
+ *   affords this exact journey", nothing about user behavior);
+ * - a step's expectation evaluated false, a step target missing/unactionable, or an
+ *   unreachable subject -> failed / step_failed (the harness executed faithfully; the SUBJECT
+ *   did not satisfy the script — distinct from actor_error/harness_error);
+ * - journey exceeded timeoutMs -> timed_out / timed_out;
+ * - browser launch/import crash -> failed / harness_error;
+ * - gave_up / blocked_approval are UNREACHABLE from this actor (no persona patience, no
+ *   approvals exist on a deterministic replay) — asserted in tests.
+ */
+export declare function runScriptedBrowserSession(options: ScriptedBrowserSessionOptions): Promise<ScriptedBrowserSessionResult>;
+/** Internal lab seam: the run root is already prepared and must stay bound to that identity. */
+export declare function runScriptedBrowserSessionInPreparedRoot(options: ScriptedBrowserSessionOptions, preparedArtifactRoot: PreparedOutputRoot): Promise<ScriptedBrowserSessionResult>;

package/dist/actors/scripted-browser/actor.js

@@ -0,0 +1,428 @@
+// The registry-facing session of the deterministic scripted browser ("browser-persona"). It runs
+// the step executor, expectation evaluator, blocked-step builder and native trace writer against an
+// injected or playwright-launched browser, and projects the result into humanish.actor-trace.v1.
+// The parts live beside it: types.ts (seams and journey types), journey.ts (the scenario parser),
+// steps.ts (the step executor) and browser-command.ts (finding Chromium). actors/registry.ts (the
+// "scripted-browser" actor) depends on this module, and the registry is const-initialized, so no
+// module in this folder may import the registry.
+//
+// The step executor's `page` is typed as the narrow structural ScriptedPageLike instead of
+// playwright's Page (browserPersonaPageState already took { evaluate, url }; E2BDesktopLike is
+// the same seam pattern). playwright's real Page satisfies it; tests inject fakes and run
+// the REAL step executor at $0 with zero browser dependence. playwright-core stays the lazy
+// production default behind launchPlaywrightChromium.
+//
+// Spend posture: nothing in this module can spend provider money — no provider client is
+// importable from this code path. tokenUsage on every projected trace records zeros as an
+// affirmative $0 declaration that is TRUE by mechanism.
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS } from "../../evidence/browser-hygiene.js";
+import { redactText } from "../../evidence/redaction.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareContainedOutputDirectory, prepareContainedOutputFile, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { ACTOR_TRACE_SCHEMA, SCRIPTED_BROWSER_CAPABILITIES, } from "../contract.js";
+import { buildBlockedBrowserPersonaSteps, buildBrowserTrace, captureBlockedStepScreenshot, compactBrowserError, executeBrowserPersonaStep, probeAppUrl, sanitizeBrowserEvidenceUrl, screenshotPathForBrowserStep, surfaceScreenshotPath, tracePathForBrowserSurface, } from "./steps.js";
+import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
+/** Production default: lazy playwright-core import + chromium.launch, exactly as the driver
+ *  always did. Kept in ONE place so the optional peer is touched by exactly one code path. */
+async function launchPlaywrightChromium(args) {
+    const { chromium } = await import("playwright-core");
+    const browser = await chromium.launch({
+        executablePath: args.browserCommand,
+        headless: true,
+        args: [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, "--disable-gpu", "--disable-dev-shm-usage"],
+        timeout: args.timeoutMs,
+    });
+    return browser;
+}
+function assertScriptedSessionPathIds(options) {
+    assertSafeOutputPathSegment(options.surface.id, "Browser surface id");
+    for (const step of options.journey.steps) {
+        assertSafeOutputPathSegment(step.id, "Browser journey step id");
+    }
+}
+const SCRIPTED_BROWSER_PROVIDER = "browser-persona";
+/** Thrown between/around steps when the journey exceeds its wall-clock budget. */
+class ScriptedJourneyTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`journey exceeded its ${timeoutMs}ms wall-clock budget`);
+        this.name = "ScriptedJourneyTimeoutError";
+    }
+}
+/**
+ * Run the scripted journey for ONE surface and return native capture + ActorTrace projection.
+ *
+ * Completion semantics (the contract the projection tests pin):
+ * - every step executed, every assertion passed, HTTP probe ok -> passed / goal_satisfied
+ *   (the scenario's expect blocks ARE the success predicate; a pass claims "the app still
+ *   affords this exact journey", nothing about user behavior);
+ * - a step's expectation evaluated false, a step target missing/unactionable, or an
+ *   unreachable subject -> failed / step_failed (the harness executed faithfully; the SUBJECT
+ *   did not satisfy the script — distinct from actor_error/harness_error);
+ * - journey exceeded timeoutMs -> timed_out / timed_out;
+ * - browser launch/import crash -> failed / harness_error;
+ * - gave_up / blocked_approval are UNREACHABLE from this actor (no persona patience, no
+ *   approvals exist on a deterministic replay) — asserted in tests.
+ */
+export async function runScriptedBrowserSession(options) {
+    assertScriptedSessionPathIds(options);
+    const preparedArtifactRoot = await prepareSelectedOutputDirectory(process.cwd(), options.artifactRoot);
+    return runScriptedBrowserSessionInPreparedRoot(options, preparedArtifactRoot);
+}
+/** Internal lab seam: the run root is already prepared and must stay bound to that identity. */
+export async function runScriptedBrowserSessionInPreparedRoot(options, preparedArtifactRoot) {
+    assertScriptedSessionPathIds(options);
+    await prepareContainedOutputDirectory(preparedArtifactRoot, "screenshots");
+    await prepareContainedOutputDirectory(preparedArtifactRoot, "traces");
+    await prepareContainedOutputFile(preparedArtifactRoot, tracePathForBrowserSurface(options.surface));
+    await Promise.all(options.journey.steps.map((step) => prepareContainedOutputFile(preparedArtifactRoot, screenshotPathForBrowserStep(options.surface, step))));
+    await assertScriptedOutputRoot(preparedArtifactRoot);
+    const now = options.now ?? (() => Date.now());
+    const startedAtMs = now();
+    const startedAt = new Date(startedAtMs).toISOString();
+    const launch = options.launchBrowser ?? launchPlaywrightChromium;
+    const browserCommand = options.browserCommand ?? (options.launchBrowser ? "injected-browser" : "");
+    const evidenceAppUrl = options.evidenceAppUrl ?? options.appUrl;
+    const urlPolicy = options.urlPolicy ?? LOOPBACK_EVIDENCE_URL_POLICY;
+    const finish = async (args) => {
+        const completedAtMs = now();
+        const trace = await projectScriptedActorTrace({
+            artifactRoot: preparedArtifactRoot,
+            capture: args.capture,
+            completedAt: new Date(completedAtMs).toISOString(),
+            completionReason: args.completionReason,
+            durationMs: Math.max(0, completedAtMs - startedAtMs),
+            executedSteps: args.executedSteps,
+            journey: options.journey,
+            persona: options.persona,
+            reason: args.reason,
+            startedAt,
+            status: args.status,
+        });
+        return {
+            status: args.status,
+            completionReason: args.completionReason,
+            reason: args.reason,
+            capture: args.capture,
+            trace,
+        };
+    };
+    // Launch FIRST: a browser that cannot start is a harness failure, never subject evidence.
+    let browser;
+    try {
+        browser = await launch({ browserCommand, timeoutMs: options.timeoutMs });
+    }
+    catch (error) {
+        const reason = `Scripted browser launch failed: ${compactBrowserError(error)}`;
+        const capture = await persistScriptedFailureCapture({
+            appUrl: options.appUrl,
+            artifactRoot: preparedArtifactRoot,
+            browserCommand,
+            evidenceAppUrl,
+            journey: options.journey,
+            reason,
+            surface: options.surface,
+            urlPolicy,
+        });
+        return finish({
+            capture,
+            executedSteps: 0,
+            status: "failed",
+            completionReason: "harness_error",
+            reason,
+        });
+    }
+    try {
+        await assertScriptedOutputRoot(preparedArtifactRoot);
+    }
+    catch (error) {
+        await browser.close().catch(() => undefined);
+        throw error;
+    }
+    const journeyRun = await runScriptedJourney({
+        appUrl: options.appUrl,
+        artifactRoot: preparedArtifactRoot,
+        browser,
+        browserCommand,
+        evidenceAppUrl,
+        journey: options.journey,
+        surface: options.surface,
+        timeoutMs: options.timeoutMs,
+        urlPolicy,
+    });
+    if (journeyRun.timedOut) {
+        return finish({
+            capture: journeyRun.capture,
+            executedSteps: journeyRun.executedSteps,
+            status: "timed_out",
+            completionReason: "timed_out",
+            reason: `${options.surface.label} ${new ScriptedJourneyTimeoutError(options.timeoutMs).message}.`,
+        });
+    }
+    if (journeyRun.capture.ok) {
+        return finish({
+            capture: journeyRun.capture,
+            executedSteps: journeyRun.executedSteps,
+            status: "passed",
+            completionReason: "goal_satisfied",
+            reason: journeyRun.capture.reason,
+        });
+    }
+    const firstFailing = journeyRun.capture.steps.find((step) => step.status !== "passed");
+    return finish({
+        capture: journeyRun.capture,
+        executedSteps: journeyRun.executedSteps,
+        status: "failed",
+        completionReason: "step_failed",
+        reason: firstFailing ? `${firstFailing.id}: ${firstFailing.reason}` : journeyRun.capture.reason,
+    });
+}
+/** Drive the journey on an already-launched browser, mirroring the driver's capture
+ *  semantics (partial blocked steps on error, trace written exactly once, browser closed). */
+async function runScriptedJourney(args) {
+    const started = Date.now();
+    const deadline = started + args.timeoutMs;
+    const tracePath = tracePathForBrowserSurface(args.surface);
+    const httpProbe = await probeAppUrl(args.appUrl, Math.min(args.timeoutMs, 15_000));
+    let page = null;
+    const steps = [];
+    let executedSteps = 0;
+    let timedOut = false;
+    try {
+        const context = await args.browser.newContext({
+            deviceScaleFactor: args.surface.viewport.deviceScaleFactor,
+            isMobile: args.surface.viewport.isMobile,
+            viewport: {
+                width: args.surface.viewport.width,
+                height: args.surface.viewport.height,
+            },
+        });
+        page = await context.newPage();
+        for (const step of args.journey.steps) {
+            await assertScriptedOutputRoot(args.artifactRoot);
+            executedSteps += 1;
+            steps.push(await withJourneyDeadline(executeBrowserPersonaStep({
+                absoluteArtifactRoot: args.artifactRoot,
+                appUrl: args.appUrl,
+                browserJourney: args.journey,
+                page,
+                step,
+                surface: args.surface,
+                timeoutMs: args.timeoutMs,
+                urlPolicy: args.urlPolicy,
+            }), deadline, args.timeoutMs));
+        }
+    }
+    catch (error) {
+        await assertScriptedOutputRoot(args.artifactRoot);
+        timedOut = error instanceof ScriptedJourneyTimeoutError;
+        const now = new Date().toISOString();
+        const reason = compactBrowserError(error);
+        if (steps.length === 0) {
+            steps.push(...buildBlockedBrowserPersonaSteps({
+                browserJourney: args.journey,
+                currentUrl: args.appUrl,
+                reason,
+                surface: args.surface,
+                timestamp: now,
+                urlPolicy: args.urlPolicy,
+            }));
+        }
+        else if (steps.length < args.journey.steps.length) {
+            const nextStep = args.journey.steps[steps.length];
+            if (nextStep) {
+                const { screenshotPath, written: blockedShotWritten } = await captureBlockedStepScreenshot(page, args.artifactRoot, args.surface, nextStep);
+                steps.push({
+                    action: nextStep.action,
+                    completedAt: now,
+                    durationMs: Date.now() - started,
+                    id: nextStep.id,
+                    label: nextStep.label,
+                    reason,
+                    ...(blockedShotWritten ? { screenshotPath } : {}),
+                    status: "blocked",
+                    url: page ? sanitizeBrowserEvidenceUrl(page.url(), args.urlPolicy) : args.evidenceAppUrl,
+                });
+            }
+        }
+    }
+    finally {
+        await args.browser.close().catch(() => undefined);
+    }
+    const completedAt = new Date().toISOString();
+    const durationMs = Date.now() - started;
+    const ok = !timedOut &&
+        httpProbe.ok &&
+        steps.length === args.journey.steps.length &&
+        steps.every((step) => step.status === "passed");
+    const reason = ok
+        ? `${args.surface.label} completed ${steps.length}/${steps.length} scripted browser steps from ${args.evidenceAppUrl}${httpProbe.status === undefined ? "" : ` with HTTP ${httpProbe.status}`}.`
+        : `${args.surface.label} scripted browser journey blocked: ${steps.find((step) => step.status !== "passed")?.reason ?? httpProbe.reason}`;
+    const scriptedScreenshotPath = surfaceScreenshotPath(steps);
+    await writeContainedOutputFile(args.artifactRoot, tracePath, `${JSON.stringify(buildBrowserTrace({
+        appUrl: args.evidenceAppUrl,
+        browserCommand: path.basename(args.browserCommand || "injected-browser"),
+        browserJourney: args.journey,
+        capturedAt: completedAt,
+        durationMs,
+        ...(httpProbe.status === undefined ? {} : { httpStatus: httpProbe.status }),
+        ok,
+        reason,
+        ...(scriptedScreenshotPath === undefined ? {} : { screenshotPath: scriptedScreenshotPath }),
+        steps,
+        surface: args.surface,
+    }), null, 2)}\n`, "utf8");
+    return {
+        capture: {
+            capturedAt: completedAt,
+            durationMs,
+            ...(httpProbe.status === undefined ? {} : { httpStatus: httpProbe.status }),
+            ok,
+            reason,
+            ...(scriptedScreenshotPath === undefined ? {} : { screenshotPath: scriptedScreenshotPath }),
+            steps,
+            surface: args.surface,
+            tracePath,
+        },
+        executedSteps,
+        timedOut,
+    };
+}
+/** Race one step against the journey's remaining wall-clock budget. A hanging step rejects
+ *  with the timeout error; the journey's catch path then records honest blocked steps. */
+async function withJourneyDeadline(promise, deadline, timeoutMs) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        // Swallow the eventual settlement so an abandoned step can never surface an unhandled rejection.
+        promise.catch(() => undefined);
+        throw new ScriptedJourneyTimeoutError(timeoutMs);
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    promise.catch(() => undefined);
+                    reject(new ScriptedJourneyTimeoutError(timeoutMs));
+                }, remaining);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Persist the all-steps-blocked capture + native trace for failures that happen before any
+ *  journey actuation (browser launch crash). Mirrors the driver's failure shape. */
+async function persistScriptedFailureCapture(args) {
+    const capturedAt = new Date().toISOString();
+    const tracePath = tracePathForBrowserSurface(args.surface);
+    const blockedSteps = buildBlockedBrowserPersonaSteps({
+        browserJourney: args.journey,
+        currentUrl: args.appUrl,
+        reason: args.reason,
+        surface: args.surface,
+        timestamp: capturedAt,
+        urlPolicy: args.urlPolicy,
+    });
+    // Pre-actuation failure: no screenshots were written, so the surface omits the
+    // screenshot reference and the failure itself stands as the evidence.
+    const screenshotPath = surfaceScreenshotPath(blockedSteps);
+    await writeContainedOutputFile(args.artifactRoot, tracePath, `${JSON.stringify(buildBrowserTrace({
+        appUrl: args.evidenceAppUrl,
+        browserCommand: path.basename(args.browserCommand || "injected-browser"),
+        browserJourney: args.journey,
+        capturedAt,
+        durationMs: 0,
+        ok: false,
+        reason: args.reason,
+        ...(screenshotPath === undefined ? {} : { screenshotPath }),
+        steps: blockedSteps,
+        surface: args.surface,
+    }), null, 2)}\n`, "utf8");
+    return {
+        capturedAt,
+        durationMs: 0,
+        ok: false,
+        reason: args.reason,
+        ...(screenshotPath === undefined ? {} : { screenshotPath }),
+        steps: blockedSteps,
+        surface: args.surface,
+        tracePath,
+    };
+}
+/** Project one surface capture into humanish.actor-trace.v1. screenshotRefs are attached only
+ *  for frames that actually exist on disk (honest counts; blocked-not-executed steps name a
+ *  path that was never written). */
+async function projectScriptedActorTrace(args) {
+    const writtenScreenshots = new Set();
+    for (const step of args.capture.steps) {
+        if (!step.screenshotPath) {
+            continue;
+        }
+        const screenshotFile = await prepareContainedOutputFile(args.artifactRoot, step.screenshotPath).catch(() => null);
+        const stats = screenshotFile ? await stat(screenshotFile).catch(() => null) : null;
+        if (stats?.isFile() && stats.size > 0) {
+            writtenScreenshots.add(step.screenshotPath);
+        }
+    }
+    let assertionCount = 0;
+    const items = args.capture.steps.map((step) => {
+        const assertions = step.assertions ?? [];
+        assertionCount += assertions.length;
+        const assertionLines = assertions.map((assertion) => `${assertion.id}: ${assertion.status} — ${assertion.reason}`);
+        return {
+            id: step.id,
+            kind: "ui_action",
+            lifecycle: "completed",
+            status: step.status,
+            title: redactText(`${step.action}: ${step.label}`).slice(0, 120),
+            ...(step.screenshotPath && writtenScreenshots.has(step.screenshotPath)
+                ? { screenshotRef: { path: step.screenshotPath, redaction: "none" } }
+                : {}),
+            text: redactText([step.reason, ...assertionLines].join("\n")),
+        };
+    });
+    return {
+        schema: ACTOR_TRACE_SCHEMA,
+        provider: SCRIPTED_BROWSER_PROVIDER,
+        protocol: "scripted-steps",
+        lane: "scripted-browser",
+        persona: args.persona,
+        redaction: {
+            status: "passed",
+            screenshots: writtenScreenshots.size > 0 ? "raw" : "n/a",
+            notes: "Deterministic scripted steps. Step URLs sanitized to loopback origin+path (query/hash redacted); fill values are committed-scenario constants passed through redactText; screenshots are full-fidelity raw in gitignored .humanish.",
+        },
+        startedAt: args.startedAt,
+        completedAt: args.completedAt,
+        durationMs: args.durationMs,
+        status: args.status,
+        completionReason: args.completionReason,
+        reason: redactText(args.reason),
+        // No session/model ids exist on a deterministic replay — absence declared by omission.
+        ids: {},
+        counts: {
+            steps: args.journey.steps.length,
+            // `actions` mirrors the engagement-check contract (verifyRun counts it as engagement).
+            actions: args.executedSteps,
+            assertions: assertionCount,
+            blocked: args.capture.steps.filter((step) => step.status !== "passed").length,
+            screenshots: writtenScreenshots.size,
+        },
+        items,
+        // Affirmative $0 declaration, TRUE by mechanism: no provider client is importable from
+        // this code path, so zeros are a recorded fact, not an estimate.
+        tokenUsage: { input: 0, output: 0, total: 0, costUsd: 0 },
+        capabilities: SCRIPTED_BROWSER_CAPABILITIES,
+    };
+}
+async function assertScriptedOutputRoot(root) {
+    if ("physicalRunRoot" in root) {
+        await prepareContainedOutputDirectory(root, "");
+        return root.physicalRunRoot;
+    }
+    await assertPreparedSelectedOutputDirectory(root);
+    return root.physicalPath;
+}

package/dist/actors/scripted-browser/browser-command.d.ts

@@ -0,0 +1 @@
+export declare function resolveBrowserCommand(): Promise<string | null>;

package/dist/actors/scripted-browser/browser-command.js

@@ -0,0 +1,48 @@
+// Find a Chromium binary on the host for the scripted browser: HUMANISH_BROWSER_COMMAND first, then
+// the macOS Chrome path, then google-chrome, chromium and chromium-browser on PATH. A candidate
+// counts only if `--version` runs.
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { shellQuote } from "../../substrates/shell.js";
+const execFileAsync = promisify(execFile);
+export async function resolveBrowserCommand() {
+    const candidates = [
+        await resolveBrowserCandidate(process.env.HUMANISH_BROWSER_COMMAND),
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        await resolveExecutableFromPath("google-chrome"),
+        await resolveExecutableFromPath("chromium"),
+        await resolveExecutableFromPath("chromium-browser"),
+    ].filter((candidate) => Boolean(candidate?.trim()));
+    for (const candidate of candidates) {
+        try {
+            await execFileAsync(candidate, ["--version"], {
+                timeout: 5_000,
+                maxBuffer: 256 * 1024,
+            });
+            return candidate;
+        }
+        catch { }
+    }
+    return null;
+}
+async function resolveBrowserCandidate(value) {
+    const candidate = value?.trim();
+    if (!candidate) {
+        return null;
+    }
+    return path.isAbsolute(candidate) ? candidate : resolveExecutableFromPath(candidate);
+}
+async function resolveExecutableFromPath(command) {
+    try {
+        const { stdout } = await execFileAsync("sh", ["-lc", `command -v ${shellQuote(command)}`], {
+            timeout: 5_000,
+            maxBuffer: 256 * 1024,
+        });
+        const resolved = stdout.trim().split(/\r?\n/)[0]?.trim();
+        return resolved ? resolved : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/actors/scripted-browser/journey.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserPersonaJourney } from "./types.js";
+export declare function parseBrowserPersonaJourneyFromScenario(args: {
+    raw: unknown;
+    relativePath: string;
+    sourceDigest: string;
+}): {
+    failure?: string;
+    journey?: BrowserPersonaJourney;
+};