humanish 0.104.3 → 0.106.0

package/dist/routes/computer-use/setup.d.ts

@@ -0,0 +1,136 @@
+import { type RunScope } from "../../run/run.js";
+import { type LocalAgentId } from "../../actors/local-agent/cli.js";
+import type { CuaActorDescriptor } from "../../actors/registry.js";
+import type { LabCommsEmail, LabCommsExternal, LabConfig } from "../../lab/types.js";
+import { type RunRerunLineage } from "../../run/bundle.js";
+import { type LocalTreeArchive } from "../../subject/local-tree-archive.js";
+import { type ComputerUseRefusal, type CuaSubjectRoute } from "./plan.js";
+import type { ComputerUsePlan } from "../../lab/plan-types.js";
+import { trackRuntimeStreams, type LiveTraceFlush } from "./live-flush.js";
+import { type CuaRunBundleBase } from "./bundle.js";
+import { projectParticipantSubjects } from "./subject-projection.js";
+import { type CuaActorLabErrorCode, type CuaActorLabHooks, type CuaActorLabResult, type CuaParticipantDeps, type CuaParticipantPlan, type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ComputerUseRunInput, type RunCuaActorLabOptions } from "./types.js";
+/**
+ * The envelope of a refusal the plan left for after the cwd checks. The lane cap and in-process
+ * fan-out refusals come after the committed personas are read, so a persona-file error still wins.
+ */
+export declare function refuseCuaLab(options: RunCuaActorLabOptions, refusal: ComputerUseRefusal): Promise<CuaActorLabResult>;
+export type AdmittedCuaRun = Extract<Awaited<ReturnType<typeof admitCuaRun>>, {
+    ok: true;
+}>["admitted"];
+type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
+    ok: true;
+}>["run"];
+/** What runLabParticipants and finishCuaRun both read. */
+export interface CuaRunSetup {
+    plan: ComputerUsePlan;
+    input: ComputerUseRunInput;
+    /** Read for values the plan does not carry yet, and by the compatibility hooks, which take the
+     *  whole config. Participants come from the plan. */
+    config: LabConfig;
+    /** The physical project root. */
+    cwd: string;
+    descriptor: CuaActorDescriptor;
+    subjectRoute: CuaSubjectRoute;
+    run: StartedRun;
+    streams: ReturnType<typeof trackRuntimeStreams>;
+    participantRuns: DesktopParticipantRun[];
+    participantPlan: CuaParticipantPlan;
+    scrubKnownValues: (text: string) => string;
+    bundleBase: CuaRunBundleBase;
+}
+/** What only runLabParticipants reads. */
+export interface CuaParticipantsSetup {
+    env: Record<string, string | undefined>;
+    /** The array scrubKnownValues reads at each call. Email receiving appends the values it
+     *  provisions before the participants run. */
+    knownSecretValues: string[];
+    deps: Omit<CuaParticipantDeps, "signalProvisioned">;
+    /** Filled by runLabParticipants on a live run; deps.onTrace reads it. */
+    liveTrace: {
+        flush?: LiveTraceFlush["flush"];
+        stop?: LiveTraceFlush["stop"];
+    };
+    /** The operator-hosted inbox on the app-url route, when declared. */
+    externalComms: {
+        config: LabCommsExternal;
+        email: LabCommsEmail;
+    } | undefined;
+    /** The subjects of the in-progress bundle, written before any participant starts. */
+    inProgress: {
+        subjects: CuaSubjectProjection[];
+        aggregateSubject: CuaSubjectProjection;
+        provenance: CuaSubjectProvenanceArg | undefined;
+    };
+    /** The refusal envelope, for a run that stops before its bundle. */
+    fail: (code: CuaActorLabErrorCode, message: string, actorLabel?: string) => CuaActorLabResult;
+}
+/** What only finishCuaRun reads besides the participants' outcomes. */
+export interface CuaFinishFacts {
+    hooks: CuaActorLabHooks;
+    rerunLineage: RunRerunLineage | undefined;
+    publicRepo: string | undefined;
+    subjectArgs: Omit<Parameters<typeof projectParticipantSubjects>[0], "outcomes" | "dryRun">;
+}
+type PreparedCuaRun = {
+    ok: false;
+    result: CuaActorLabResult;
+} | {
+    ok: true;
+    setup: CuaRunSetup;
+    participants: CuaParticipantsSetup;
+    finish: CuaFinishFacts;
+};
+/**
+ * Everything before the run starts: the physical project, the route, the participant plan and
+ * preflight, the key and subject-env scrubber, the live checks that need no sandbox, and the
+ * local-tree archive. These read files, env and the network, which planLab does not. Returns the
+ * refusal, or what startCuaRun reads.
+ */
+export declare function admitCuaRun(plan: ComputerUsePlan, input: ComputerUseRunInput, config: LabConfig): Promise<{
+    ok: false;
+    result: CuaActorLabResult;
+} | {
+    ok: true;
+    admitted: {
+        config: LabConfig;
+        dryRun: boolean;
+        cwd: string;
+        hooks: CuaActorLabHooks;
+        streams: {
+            hooks: CuaActorLabHooks;
+            showIn: (observer: import("../../index.js").ObserverResult & {
+                ok: true;
+            }) => void;
+            attachFinal: (observer: import("../../index.js").ObserverResult) => void;
+        };
+        env: NodeJS.ProcessEnv;
+        subjectRoute: CuaSubjectRoute;
+        fail: (code: CuaActorLabErrorCode, message: string, actorLabel?: string) => CuaActorLabResult;
+        refuse: (code: CuaActorLabErrorCode, message: string, actorLabel?: string | undefined) => {
+            ok: false;
+            result: CuaActorLabResult;
+        };
+        descriptor: CuaActorDescriptor;
+        runSession: (options: import("../../actors/computer-use/actor.js").CuaActorSessionOptions) => Promise<import("../../index.js").CuaLoopResult>;
+        externalCommsConfig: LabCommsExternal | undefined;
+        externalCommsEmail: LabCommsEmail | undefined;
+        participantRuns: DesktopParticipantRun[];
+        participantPlan: CuaParticipantPlan;
+        rerunLineage: RunRerunLineage | undefined;
+        participantCount: number;
+        openaiApiKey: string;
+        e2bApiKey: string;
+        knownSecretValues: string[];
+        scrubKnownValues: (text: string) => string;
+        publicRepo: string | undefined;
+        hasGithubToken: boolean;
+        localAgentRoute: boolean;
+        preferredLocalAgent: LocalAgentId;
+        localTreeArchive: LocalTreeArchive | undefined;
+        localTreeArchiveBuffer: ArrayBuffer | undefined;
+    };
+}>;
+/** Starts the run and builds what the participants and the finish read: the deps and the bundle base. */
+export declare function startCuaRun(plan: ComputerUsePlan, input: ComputerUseRunInput, admitted: AdmittedCuaRun, scope: RunScope): Promise<PreparedCuaRun>;
+export {};

package/dist/routes/computer-use/setup.js

@@ -0,0 +1,371 @@
+// The computer-use run's setup: resolve the project and route, plan the lanes, make the live
+// checks that need no sandbox, pack a local tree, then start the run and build the lane deps and
+// bundle base that the lanes and the finish share.
+import { randomBytes } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import {} from "../../run/run.js";
+import { externalInboxUrl } from "../../comms/sandbox-catch.js";
+import {} from "../../actors/local-agent/cli.js";
+import { redactText, scrubLiterals, toErrorMessage } from "../../evidence/redaction.js";
+import { buildRunSource } from "../../run/bundle.js";
+import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectory, prepareSelectedOutputDirectory, } from "../../run/contained-output.js";
+import {} from "../../subject/local-tree-archive.js";
+import { renderCuaReviewMarkdown } from "./bundle.js";
+import { emitPreflightPlan, compileParticipantPersonas, loadCuaParticipants, sanitizeParticipantRuns, } from "./participant-runs.js";
+import { makeCuaRunBudget } from "./participant-model.js";
+import { e2bRequestTimeoutMs } from "../../substrates/e2b/lifetime.js";
+import { liveCuaRejection } from "./preflight.js";
+import { cuaDescriptorOf, cuaSubjectRoute, cuaSubjectRouteOf, } from "./plan.js";
+import { trackRuntimeStreams } from "./live-flush.js";
+import {} from "./bundle.js";
+import { packRunLocalTree } from "./local-tree-pack.js";
+import { projectParticipantSubjects, subjectProvenanceArg } from "./subject-projection.js";
+import { CUA_ACTOR_LAB_SCHEMA, } from "./types.js";
+import { labPersonaIds } from "../../lab/persona-resolve.js";
+import { participantDesktopOf } from "./participant-desktop.js";
+/** The physical project, bound before any caller hook runs. */
+async function bindProject(cwd) {
+    // Capture the physical project before reading or invoking any caller hook. A supported
+    // symlink cwd remains valid, but retargeting that alias from a hook cannot redirect source
+    // reads, local-tree packing, managed run storage, or Observer output into another project.
+    const physicalCwd = await realpath(path.resolve(cwd));
+    return prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
+}
+/**
+ * The envelope of a refusal the plan left for after the cwd checks. The lane cap and in-process
+ * fan-out refusals come after the committed personas are read, so a persona-file error still wins.
+ */
+export async function refuseCuaLab(options, refusal) {
+    const { config, dryRun } = options;
+    const projectRoot = await bindProject(options.cwd);
+    const hooks = options.hooks ?? {};
+    // The committed personas are read before the refusal returns, so a persona-file error wins.
+    if (refusal.stage === "after-personas")
+        await compileParticipantPersonas(projectRoot, labPersonaIds(config));
+    return {
+        schema: CUA_ACTOR_LAB_SCHEMA,
+        ok: false,
+        cwd: projectRoot.physicalPath,
+        labId: config.id,
+        actor: refusal.actor ?? config.actors[0]?.type ?? "",
+        appUrl: cuaSubjectRoute(config, hooks).appUrl,
+        dryRun,
+        runId: options.runId ?? "not-created",
+        lanes: [],
+        warnings: [],
+        error: { code: refusal.code, message: refusal.message },
+    };
+}
+/**
+ * Everything before the run starts: the physical project, the route, the participant plan and
+ * preflight, the key and subject-env scrubber, the live checks that need no sandbox, and the
+ * local-tree archive. These read files, env and the network, which planLab does not. Returns the
+ * refusal, or what startCuaRun reads.
+ */
+export async function admitCuaRun(plan, input, config) {
+    const { dryRun } = plan;
+    const projectRoot = await bindProject(input.cwd);
+    const cwd = projectRoot.physicalPath;
+    const hooks = input.hooks ?? {};
+    const streams = trackRuntimeStreams(hooks);
+    const env = hooks.env ?? process.env;
+    const subjectRoute = cuaSubjectRouteOf(plan);
+    const { cloneRoute, localTreeRoute, inProcessRoute, appUrl, subjectRepo, subjectEnvNames } = subjectRoute;
+    const fail = (code, message, actorLabel) => ({
+        schema: CUA_ACTOR_LAB_SCHEMA,
+        ok: false,
+        cwd,
+        labId: plan.labId,
+        actor: actorLabel ?? plan.actor,
+        appUrl,
+        dryRun,
+        runId: input.runId ?? "not-created",
+        lanes: [],
+        warnings: [],
+        error: { code, message },
+    });
+    const refuse = (...args) => ({
+        ok: false,
+        result: fail(...args),
+    });
+    const descriptor = cuaDescriptorOf(plan.actor);
+    const runSession = hooks.runSession ?? descriptor.runSession;
+    // Adopter-hosted comms plane on the app-url route (#380): humanish provisions no subject here,
+    // so it cannot host a catch — the OPERATOR runs one, and humanish still does every other part
+    // of the funnel: tells each persona its address and inbox URL, drains the catch over HTTP after
+    // the lanes, and writes the same digest-only evidence. Declaring `external` previously did
+    // nothing on this route (and, per #387, on every other) while its docs said otherwise.
+    const comms = plan.residual.comms;
+    const externalCommsConfig = !cloneRoute && !localTreeRoute && !inProcessRoute ? comms?.email?.external : undefined;
+    const externalCommsEmail = externalCommsConfig ? comms?.email : undefined;
+    const participants = await loadCuaParticipants({ plan, cwd, projectRoot, env });
+    if (!participants.ok) {
+        return refuse(participants.code, participants.message, descriptor.id);
+    }
+    const { participantRuns, participantPlan, rerunLineage } = participants;
+    const participantCount = participantRuns.length;
+    // Pre-flight plan: BEFORE any sandbox or provider call (dry-run AND live). The hook fires for
+    // every N (observable + testable); the stderr table prints for fan-out (N>1) so single-lane
+    // runs stay as quiet as they always were.
+    if (participantCount > 1) {
+        emitPreflightPlan(participantPlan, plan.labId);
+    }
+    hooks.onPreflight?.(participantPlan);
+    await assertPreparedSelectedOutputDirectory(projectRoot);
+    // Read keys once into locals (names only; values never logged or persisted).
+    const openaiApiKey = env.OPENAI_API_KEY?.trim() ?? "";
+    const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
+    // Literal scrubber for every known provisioned value (no secret "shape" to pattern-match).
+    const knownSecretValues = [
+        openaiApiKey,
+        e2bApiKey,
+        ...subjectEnvNames.map((name) => env[name] ?? ""),
+    ].filter((value) => value.length >= 4);
+    const scrubKnownValues = scrubLiterals(knownSecretValues);
+    sanitizeParticipantRuns(participantRuns, scrubKnownValues);
+    const redactRepoLabel = plan.residual.policies?.redactRepos ?? subjectEnvNames.includes("GITHUB_TOKEN");
+    const publicRepo = cloneRoute && subjectRepo ? (redactRepoLabel ? "repo-01" : subjectRepo) : undefined;
+    const hasGithubToken = subjectEnvNames.includes("GITHUB_TOKEN");
+    // The operator's own signed-in coding agent is the brain, so there is no provider key to ask
+    // for — the entire point of the actor. E2B is still required: the persona needs a machine.
+    const localAgentRoute = descriptor.id === "local-agent";
+    // Which local CLI, from its OWN field: `model` means the model, so that "Claude Code running
+    // Opus" is sayable. Preflight below refuses when the chosen one is missing or signed out — that
+    // news is worthless after a sandbox is paid for.
+    const preferredLocalAgent = config.actors[0]?.localAgent ?? "codex";
+    // Key-gating is route-aware: the in-process route uses the caller's OWN model + executor, and
+    // the local-agent route uses a CLI the operator has already signed in to.
+    if (!dryRun && !inProcessRoute) {
+        const rejection = await liveCuaRejection({
+            caps: plan.caps,
+            model: config.actors[0]?.model,
+            hooks,
+            env,
+            openaiApiKey,
+            e2bApiKey,
+            localAgentRoute,
+            preferredLocalAgent,
+            subjectEnvNames,
+            externalCommsConfig,
+        });
+        if (rejection)
+            return refuse(rejection.code, rejection.message, descriptor.id);
+    }
+    // Pack the working tree ONCE per run, on the host, BEFORE any sandbox or provider call: every
+    // fan-out lane below uploads this SAME archive, so one archiveSha256 describes every lane's
+    // digest. Dry-run packs nothing (no fs side effects; the contract bundle carries no
+    // archiveSha256). A packing failure fails the run closed here, before any sandbox is
+    // created and before the run directory exists.
+    let localTreeArchive;
+    let localTreeArchiveBuffer;
+    if (localTreeRoute && !dryRun) {
+        try {
+            const packed = await packRunLocalTree(hooks, plan.residual, cwd);
+            localTreeArchive = packed.archive;
+            localTreeArchiveBuffer = packed.buffer;
+        }
+        catch (error) {
+            return refuse("HUMANISH_CUA_LAB_SUBJECT_INVALID", `local-tree packing failed: ${redactText(scrubKnownValues(toErrorMessage(error)))}`, descriptor.id);
+        }
+    }
+    return {
+        ok: true,
+        admitted: {
+            config,
+            dryRun,
+            cwd,
+            hooks,
+            streams,
+            env,
+            subjectRoute,
+            fail,
+            refuse,
+            descriptor,
+            runSession,
+            externalCommsConfig,
+            externalCommsEmail,
+            participantRuns,
+            participantPlan,
+            rerunLineage,
+            participantCount,
+            openaiApiKey,
+            e2bApiKey,
+            knownSecretValues,
+            scrubKnownValues,
+            publicRepo,
+            hasGithubToken,
+            localAgentRoute,
+            preferredLocalAgent,
+            localTreeArchive,
+            localTreeArchiveBuffer,
+        },
+    };
+}
+/** Starts the run and builds what the participants and the finish read: the deps and the bundle base. */
+export async function startCuaRun(plan, input, admitted, scope) {
+    const { config, dryRun, cwd, hooks, descriptor, participantRuns, participantPlan, publicRepo } = admitted;
+    const { appUrl, inProcessRoute, localAppSubject, cloneRoute, localTreeRoute, subjectEnvNames } = admitted.subjectRoute;
+    // The run's status record exists from here on, so anything watching the runs directory can
+    // tell which lab this is and that it is alive. The fail-closed returns below leave it finished
+    // with no outcome when the scope closes; a crash leaves it stale, which reads as interrupted.
+    const started = await scope.startRun({
+        cwd,
+        runId: input.runId,
+        mintRunId: makeCuaRunId,
+        mode: dryRun ? "dry-run" : "live",
+        lab: plan.lab,
+        renderReview: renderCuaReviewMarkdown,
+        observer: { open: input.open === true, render: hooks.renderObserverFn },
+    });
+    if (!started.ok)
+        return admitted.refuse(started.code, started.message, descriptor.id);
+    const { run } = started;
+    const { runId, createdAt, paths: runPaths } = run;
+    const redactScreenshots = plan.residual.policies?.redactScreenshots === true;
+    await prepareContainedOutputDirectory(runPaths, "screenshots");
+    const source = await buildRunSource({
+        capturedAt: createdAt,
+        cwd,
+        humanishSource: "present",
+        packageName: "humanish",
+    });
+    // Live-trace flush seam (#441): runLabParticipants fills it when a live run has an in-progress bundle
+    // to grow; lanes call it through deps.onTrace. It exists before deps so deps can reference it as
+    // a stable indirection.
+    const liveTrace = {};
+    const deps = cuaParticipantDeps(plan, input, admitted, {
+        runPaths,
+        redactScreenshots,
+        liveTrace,
+    });
+    const subjectArgs = {
+        plan,
+        subjectRoute: admitted.subjectRoute,
+        ...(publicRepo === undefined ? {} : { publicRepo }),
+        ...(admitted.localTreeArchive === undefined
+            ? {}
+            : { localTreeArchive: admitted.localTreeArchive }),
+        runs: participantRuns,
+    };
+    const inProgressSubjects = projectParticipantSubjects({
+        ...subjectArgs,
+        outcomes: undefined,
+        dryRun: false,
+    });
+    const inProgressAggregateSubject = inProgressSubjects[0];
+    const inProgressProvenance = subjectProvenanceArg(inProgressAggregateSubject, publicRepo, subjectEnvNames);
+    const bundleBase = {
+        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        participantRuns,
+        descriptor,
+        appUrl,
+        createdAt,
+        plan,
+        runId,
+        source,
+        participantPlan,
+        ...(admitted.rerunLineage === undefined ? {} : { rerun: admitted.rerunLineage }),
+        redactScreenshots,
+        inProcessRoute,
+        localAppSubject,
+        cloneRoute,
+        localTreeRoute,
+        ...(publicRepo === undefined ? {} : { publicRepo }),
+        subjectEnvNames,
+    };
+    const { externalCommsConfig, externalCommsEmail } = admitted;
+    return {
+        ok: true,
+        setup: {
+            plan,
+            input,
+            config,
+            cwd,
+            descriptor,
+            subjectRoute: admitted.subjectRoute,
+            run,
+            streams: admitted.streams,
+            participantRuns,
+            participantPlan,
+            scrubKnownValues: admitted.scrubKnownValues,
+            bundleBase,
+        },
+        participants: {
+            env: admitted.env,
+            knownSecretValues: admitted.knownSecretValues,
+            deps,
+            liveTrace,
+            externalComms: externalCommsConfig === undefined || externalCommsEmail === undefined
+                ? undefined
+                : { config: externalCommsConfig, email: externalCommsEmail },
+            inProgress: {
+                subjects: inProgressSubjects,
+                aggregateSubject: inProgressAggregateSubject,
+                provenance: inProgressProvenance,
+            },
+            fail: admitted.fail,
+        },
+        finish: { hooks, rerunLineage: admitted.rerunLineage, publicRepo, subjectArgs },
+    };
+}
+/** The lane deps every lane reads: the route, keys, timeouts, scrubber, budget and hooks. */
+function cuaParticipantDeps(plan, input, admitted, run) {
+    const { config, dryRun, hooks, streams, env, descriptor, runSession, participantCount } = admitted;
+    const { localAgentRoute, preferredLocalAgent, hasGithubToken, localTreeArchiveBuffer } = admitted;
+    const { openaiApiKey, e2bApiKey, scrubKnownValues } = admitted;
+    const { externalCommsConfig, externalCommsEmail } = admitted;
+    const { appUrl, cloneRoute, desktopCliRoute, localTreeRoute, serve, subjectRepo } = admitted.subjectRoute;
+    const { subjectEnvNames } = admitted.subjectRoute;
+    const { runPaths, redactScreenshots, liveTrace } = run;
+    const createDesktop = participantDesktopOf(hooks);
+    const timeoutMs = plan.sessionBudgetMs;
+    const requestTimeoutMs = e2bRequestTimeoutMs(env);
+    return {
+        ...(createDesktop === undefined ? {} : { createDesktop }),
+        onTrace: (participantId, items, usage, metadata) => liveTrace.flush?.(participantId, items, usage, metadata),
+        config,
+        descriptor,
+        appUrl,
+        ...(localAgentRoute ? { localAgent: preferredLocalAgent } : {}),
+        cloneRoute,
+        desktopCliRoute,
+        localTreeRoute,
+        ...(serve === undefined ? {} : { serve }),
+        ...(subjectRepo === undefined ? {} : { subjectRepo }),
+        subjectEnvNames,
+        hasGithubToken,
+        ...(localTreeArchiveBuffer === undefined ? {} : { localTreeArchiveBuffer }),
+        env,
+        openaiApiKey,
+        e2bApiKey,
+        requestTimeoutMs,
+        sandboxMs: plan.sandboxMs,
+        timeoutMs,
+        participantCount,
+        artifactRoot: runPaths,
+        labCwd: input.cwd,
+        redactScreenshots,
+        scrubKnownValues,
+        runSession,
+        // The study-level ledger exists once per RUN, shared by every lane (#299). Dry runs never
+        // spend, so they carry none.
+        ...(dryRun || plan.caps.maxTotalUsd === undefined
+            ? {}
+            : { runBudget: makeCuaRunBudget(plan.caps.maxTotalUsd) }),
+        ...(externalCommsConfig === undefined || externalCommsEmail === undefined
+            ? {}
+            : {
+                externalComms: {
+                    email: externalCommsEmail,
+                    inboxUrl: externalInboxUrl(externalCommsConfig),
+                },
+            }),
+        now: hooks.now ?? Date.now,
+        hooks: streams.hooks,
+    };
+}
+function makeCuaRunId() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `cua-${stamp}-${randomBytes(4).toString("hex")}`;
+}

package/dist/routes/computer-use/single-bundle.d.ts

@@ -0,0 +1,97 @@
+import type { RunDesktopRecording } from "../../evidence/desktop-recording-types.js";
+import type { SubjectPhaseEvent } from "../../subject/steps.js";
+import type { DesktopBrowserEvidence } from "../../substrates/e2b/desktop-browser.js";
+import type { ActorPersonaRef } from "../../actors/contract.js";
+import type { CuaLoopResult } from "../../actors/computer-use/loop.js";
+import { type RunLabProvenance } from "../../run/status.js";
+import { type RunBundle, type RunFeedbackCandidate, type RunProviderResource } from "../../run/bundle.js";
+import { type RunDesktopGeometry, type RunStream } from "../../run/streams.js";
+import { type Verdict } from "../../run/judge.js";
+import { type DesktopUsage } from "../../run/cost-summary.js";
+import type { CuaSubjectProvenanceArg } from "./types.js";
+/**
+ * The bundle of a single-participant run: one participant and no rerun. buildCuaRunBundle
+ * (bundle.ts) maps the run's base and state into these arguments.
+ */
+export declare function buildSingleParticipantBundle(args: {
+    /** The run's verdict, from the judge. */
+    verdict: Verdict;
+    realEmail?: boolean;
+    /** Lab provenance for the bundle's own `lab` field (#455). */
+    lab?: RunLabProvenance;
+    actorId: string;
+    appUrl: string;
+    /** The participant's plan id, saved as the stream's laneId ("lane-01" when absent). */
+    participantId?: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    createdAt: string;
+    dryRun: boolean;
+    labId: string;
+    labTitle?: string;
+    mission: string;
+    assignment?: RunStream["assignment"];
+    persona: ActorPersonaRef;
+    resolution: [number, number];
+    /** False only for the custom in-process route, which has no hosted screen/window to claim. */
+    desktopRoute?: boolean;
+    /** The participant's runner; see runnerSubstrate for the default. */
+    substrate?: RunFeedbackCandidate["substrate"];
+    /** Runtime screen/window/viewport evidence. `viewport` inside this object must be measured. */
+    desktopGeometry?: RunDesktopGeometry;
+    recording?: RunDesktopRecording;
+    /** Device-preset touch metadata echoed on the measured stream viewport (a prompt signal on
+     *  this route, never a rendered claim); the measured width/height/DPR stay authoritative. */
+    isMobile?: boolean;
+    runId: string;
+    screenshots: string[];
+    /** Relative run-dir path of the digest-only comms-thread evidence artifact (humanish.comms-thread.v1),
+     *  when a comms lab captured mail; registered as a "log" stream artifact. */
+    commsArtifactPath?: string;
+    /**
+     * Capture-time screenshot policy ("blurred" when policies.redactScreenshots, else "raw").
+     * When a session ran, its trace's `redaction.screenshots` is the evidence-of-record and
+     * wins; this fallback keeps labels honest for frames written before a mid-session failure
+     * (no trace exists to testify then). Defaults to "raw" — the engine default.
+     */
+    captureRedaction?: "raw" | "blurred";
+    session?: CuaLoopResult;
+    sessionError?: string;
+    /**
+     * The lane's own credibility read of a goal_satisfied session (#476). The actor's status is
+     * evidence of what it CLAIMED; whether the harness counts the claim is decided by the lane
+     * (zero engagement, a final message that describes a blocker). The review has to say the same
+     * thing the lane's exit code says, or the durable bundle reports a participant reaching the
+     * goal on a run the harness refused to count.
+     */
+    credibility?: {
+        noEngagement: boolean;
+        selfReportedBlocker: boolean;
+        reportedFriction: boolean;
+    };
+    source: RunBundle["source"];
+    /** Provisioned-route provenance (clone or local-tree): what the actor actually drove (names
+     * + digests only, never values or command text), including the subject's state story. */
+    subjectProvenance?: CuaSubjectProvenanceArg;
+    /**
+     * Entry kind for the non-clone subject.declared event (invariant 5 — declare what the subject
+     * WAS). "local-app": an already-running LOCAL dev server driven in-process, un-pinnable —
+     * declared honestly as caller-provisioned/unpinned with no E2B. Absent: a plain app-url entry.
+     */
+    entryKind?: "local-app";
+    /** The custom E2B desktop template (image) this lane launched on, when configured (provenance). */
+    desktopTemplate?: string;
+    /** The configured browser choice and the command that opened, when explicitly configured. */
+    desktopBrowser?: DesktopBrowserEvidence;
+    traceArtifactPath?: string;
+    providerResources?: RunProviderResource[];
+    inProgress?: boolean;
+    /** Completed subject-phase records (clone/upload/extract/install/build/ready/state groups)
+     *  to fold into bundle.events, so run.json carries real phase timing after the fact. */
+    phaseEvents?: SubjectPhaseEvent[];
+    /** Host-side E2B desktop billed span for this lane, in minutes (from ParticipantRunOutcome
+     *  desktopDurationMs). Absent when no sandbox ran (in-process/dry-run) → no desktop cost line. */
+    desktopMinutes?: number;
+    desktopUsage?: DesktopUsage;
+}): RunBundle;