humanish 0.107.0 → 0.108.0

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

@@ -10,7 +10,7 @@ import type { AutomaticAnalysisRefusal } from "../../analysis/job.js";
 import { type CuaDiagnostics } from "./diagnostics.js";
 import type { ActorCompletionReason, ActorStatus, ActorStopCause, ActorTokenUsage, ActorTraceItem } from "../../actors/contract.js";
 import { type CuaActorDescriptor } from "../../actors/registry.js";
-import type { LabDeps, PhaseParticipant } from "../../lab/lab-deps.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
 import type { LabEvent, ParticipantRef } from "../../lab/run-lab-events.js";
 import type { InProcessDriver, ProviderFactory, RunLabHomes } from "../../lab/run-lab-homes.js";
 import { type BrowserScorer } from "../../lab/adapter-extension.js";
@@ -26,7 +26,7 @@ import { type RunDesktopGeometry } from "../../run/streams.js";
 import { type PreparedOutputRoot } from "../../run/contained-output.js";
 import type { ComputerUseParticipant, SharedWorldParticipant } from "../../lab/plan-participants.js";
 import type { ResolvedParticipant } from "../../run/participant.js";
-export declare const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
+import { type StudyResultIdentity } from "../../run/study-result.js";
 export declare const CUA_FANOUT_STRATEGY: "per-lane-worlds";
 export declare const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 export declare const DEFAULT_APP_URL_SESSION_TIMEOUT_MS: number;
@@ -57,7 +57,7 @@ export interface RunCuaActorLabOptions {
     open?: boolean;
     runId?: string;
     /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `lanes`
-     *  roster is declared — a roster's length is authoritative). */
+     *  roster is declared; a roster's length is authoritative). */
     countOverride?: number;
     /** Explicitly create a new run containing failed or selected participants from a prior fan-out run. */
     rerun?: {
@@ -85,12 +85,12 @@ export interface RunCuaActorLabOptions {
     deps?: LabDeps;
     /** Scores the assembled evidence: `RunLabOptions.scorer`, or the scorer the CLI loads. */
     scorer?: BrowserScorer;
-    /** Present only when the scorer was CONFIG-DECLARED and loaded by the CLI (#316);
+    /** Present only when the scorer was config-declared and loaded by the CLI;
      *  core-stamped onto the bundle as evidence. Absent for library callers. */
     scorerProvenance?: RunScorerProvenance;
 }
 /** A participant's row in the pre-flight plan: identity + the device/persona it will drive. The prompt
- *  text never leaks — only a sha256-16 digest of the composed instructions. */
+ *  text never leaks: only a sha256-16 digest of the composed instructions. */
 export interface CuaParticipantPlanEntry {
     id: string;
     actorType?: string;
@@ -104,7 +104,7 @@ export interface CuaParticipantPlanEntry {
     resolution: [number, number];
     instructionDigest: string;
     /** The declared reasoning effort for this participant, when the lab declared one. The plan line is what
-     *  you read BEFORE spending money, so a declared per-participant difference has to be visible there. */
+     *  you read before spending money, so a declared per-participant difference has to be visible there. */
     reasoningEffort?: string;
     maxOutputTokens?: number;
     /** Present only when a participant overrides subject.appUrl; digest avoids leaking preview hosts in plan logs. */
@@ -115,23 +115,23 @@ export interface CuaParticipantPlanEntry {
 export interface CuaParticipantPlan {
     strategy: typeof CUA_FANOUT_STRATEGY;
     laneCount: number;
-    /** Effective in-flight bound (defaults to laneCount — all seats live; a declared
-     *  execution.concurrency is a cap; the env override may only LOWER it). */
+    /** Effective in-flight bound (defaults to laneCount, all participants live; a declared
+     *  execution.concurrency is a cap; the env override may only lower it). */
     concurrency: number;
-    /** Present when the env override lowered the bound below the config's value — recorded so the
+    /** Present when the env override lowered the bound below the config's value, recorded so the
      *  plan never silently disagrees with the manifest. */
     envLoweredConcurrencyFrom?: number;
     /** ceil(laneCount / concurrency). */
     waves: number;
     /** Per-participant session wall-clock budget (execution.timeoutMs); there is no run-level wall clock. */
     perLaneSessionBudgetMs: number;
-    /** Worst-case TOTAL sandbox-minutes across all participants (each one's full sandbox deadline). */
+    /** Worst-case total sandbox-minutes across all participants (each one's full sandbox deadline). */
     worstCaseSandboxMinutes: number;
     /** True for a dry-run plan (no spend); the same table appears live. */
     dryRun: boolean;
     lanes: CuaParticipantPlanEntry[];
 }
-/** One participant's outcome in the result projection. ALWAYS present in `result.lanes` (length
+/** One participant's outcome in the result projection. Always present in `result.lanes` (length
  *  1 at N=1). A `blocked` participant is one the pipeline-gate / fail-fast skipped before it ran. */
 export interface CuaParticipantResult {
     id: string;
@@ -183,8 +183,8 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorLabErrorCode = "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_CUA_LAB_FAILED" | "HUMANISH_CUA_LAB_KEYS_MISSING" | "HUMANISH_CUA_LAB_AGENT_MISSING" | "HUMANISH_CUA_LAB_AGENT_SIGNIN_REQUIRED" | "HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CUA_LAB_SUBJECT_INVALID" | "HUMANISH_CUA_LAB_SUBJECT_UNSAFE" | "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER" | "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_CUA_LAB_LOCAL_DESKTOP_MISSING" | "HUMANISH_CUA_LAB_FANOUT_INVALID" | "HUMANISH_CUA_LAB_RERUN_INVALID" | "HUMANISH_CUA_LAB_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_CUA_LAB_UNPRICED_CAP" | "HUMANISH_CUA_LAB_COMMS_CATCH_UNREACHABLE" | "HUMANISH_CUA_LAB_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
-/** Subject provenance projection (invariant 5): what the actor actually drove. */
+export type CuaActorLabErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+/** Subject provenance projection: what the actor actually drove. */
 export interface CuaSubjectProjection {
     source: "app-url" | "clone" | "local-tree";
     /** Clone-route only: the (possibly redacted) owner/repo slug. */
@@ -198,9 +198,9 @@ export interface CuaSubjectProjection {
     /** Local-tree-route only: host-side porcelain status at pack time (true when the working
      *  tree had uncommitted changes). Absent when the packed root was not a git work tree. */
     dirty?: boolean;
-    /** Declared env NAMES provisioned for the subject (values never surface anywhere). */
+    /** Declared env names provisioned for the subject (values never surface anywhere). */
     envNames?: string[];
-    /** The subject's state story (seeded digests / UNPINNED external / declared-not-run /
+    /** The subject's state story (seeded digests / unpinned external / declared-not-run /
      *  undeclared): the same block the run bundle records. */
     state: RunSubjectProvenance["state"];
 }
@@ -221,13 +221,11 @@ export type CuaSubjectProvenanceArg = {
     envNames: string[];
     state: RunSubjectProvenance["state"];
 };
-export interface CuaActorLabResult extends AutomaticAnalysisResult {
-    schema: typeof CUA_ACTOR_LAB_SCHEMA;
+export interface CuaActorLabResult extends AutomaticAnalysisResult, StudyResultIdentity<"computer-use"> {
     /** True when the Observer verified the bundle, all live participants passed credibility checks
      * (or this is a dry-run), and no declared adapter/scorer verdict failed. */
     ok: boolean;
     cwd: string;
-    labId: string;
     /** The registry-resolved actor id that ran (or would run) the session. */
     actor: string;
     appUrl: string;
@@ -244,16 +242,16 @@ export interface CuaActorLabResult extends AutomaticAnalysisResult {
     sandbox?: {
         sandboxId: string;
         killed: boolean;
-        /** The stream URL itself (carries an auth key) is runtime-only and is deliberately NOT
-         * surfaced on the result — the sandbox is already dead by the time the result exists. */
+        /** The stream URL itself (carries an auth key) is runtime-only and is deliberately not
+         * surfaced on the result; the sandbox is already dead by the time the result exists. */
         streamUrlPresent: boolean;
     };
-    /** Subject provenance (invariant 5): what the actor actually drove. At N>1 this is the
+    /** Subject provenance: what the actor actually drove. At N>1 this is the
      *  unanimity-gated aggregate (top-level `commit` only when every participant resolved the same one). */
     subject?: CuaSubjectProjection;
     /** The pre-flight participant plan (present once participants resolve; absent on early validation errors). */
     plan?: CuaParticipantPlan;
-    /** Per-participant results — ALWAYS present once participants resolve (length 1 at N=1). */
+    /** Per-participant results, always present once participants resolve (length 1 at N=1). */
     lanes?: CuaParticipantResult[];
     /** Aggregate participant counts. */
     laneSummary?: CuaParticipantSummary;
@@ -293,8 +291,8 @@ export interface ParticipantRunsAndPlan {
     participantPlan: CuaParticipantPlan;
 }
 /**
- * The STUDY's shared spend ledger (#299): one counter across every participant. Each one notes its
- * own latest running MODEL-spend estimate (monotone per participant — an estimate can only grow)
+ * The study's shared spend ledger: one counter across every participant. Each one notes its
+ * own latest running model-spend estimate (monotone per participant: an estimate can only grow)
  * and reads back the run total; the loop stops the participant the moment the total crosses the study budget.
  * Estimated model spend only: desktop-minutes ride the cost summary, not this ledger.
  */
@@ -308,8 +306,8 @@ export interface CuaRunBudget {
  * The subject as a participant's desktop meets it. A computer-use participant gets the plan's
  * subject: a clone or local tree is provisioned in its own sandbox with the declared env, a
  * desktop-cli product is set up there, and an app-url or local-app subject is only opened. A
- * shared-world seat gets `shared-app`: it opens the one app the plane serves, with no subject env
- * names forwarded, no GitHub token and no provisioning in its sandbox.
+ * shared-world participant gets `shared-app`: it opens the one app the plane serves, with no
+ * subject env names forwarded, no GitHub token and no provisioning in its sandbox.
  */
 export type ParticipantSubject = ComputerUseRunner["subject"] | {
     readonly kind: "shared-app";
@@ -341,14 +339,14 @@ export interface E2BDesktopDeps {
     labCwd: string;
     scrubKnownValues: (text: string) => string;
     receiving?: CommsReceivingRun;
-    /** Adopter-hosted comms plane (#380): present on the app-url route when comms.email.external is
+    /** Adopter-hosted comms plane: present on the app-url route when comms.email.external is
      *  declared. Carries the parsed comms block (recipients drive the per-participant inbox instruction)
      *  and the inbox URL the persona opens. The drain runs once at run level, not per participant. */
     externalComms?: {
         email: LabCommsEmail;
         inboxUrl: string;
     };
-    /** Injected clock (ms). Used to measure the host-side E2B desktop create->teardown span so the
+    /** Injected clock (ms). It measures the host-side E2B desktop create->teardown span so the
      *  desktop-minute cost estimate is deterministic in tests. Defaults to Date.now. */
     now: () => number;
     /** Loads the E2B SDK for the participant's desktop. Defaults to loadE2BDesktopModule. */
@@ -360,9 +358,9 @@ export interface E2BDesktopDeps {
     /** Receives each live stream's ready and ended: the Observer's tracker, then the caller's onStream. */
     onStream: NonNullable<RunLabHomes["onStream"]>;
     /** Reports a subject phase to the phase sink (stderr by default) and to onEvent. */
-    reportSubjectPhase: (event: SubjectPhaseEvent, participant: PhaseParticipant) => void;
+    reportSubjectPhase: (event: SubjectPhaseEvent, participant: ParticipantRef) => void;
     /**
-     * How a PARSEABLE requested-vs-verified screen mismatch is treated. Default ("fail-closed"):
+     * How a parseable requested-vs-verified screen mismatch is treated. Default ("fail-closed"):
      * the participant's device claim is falsified, so it fails with DEVICE_GEOMETRY (the
      * single-participant/fan-out contract). "record-evidence" (the concurrent shared-world route):
      * requested and verified stay recorded as separate facts plus an explicit warning, and the
@@ -386,22 +384,22 @@ export interface ParticipantModelDeps {
     redactScreenshots: boolean;
     scrubKnownValues: (text: string) => string;
     /** The study's shared spend ledger, present exactly when execution.caps.maxTotalUsd is set on a
-     *  live run (#299). Preflight already refused the cap on an unpriced model. */
+     *  live run. Preflight already refused the cap on an unpriced model. */
     runBudget?: CuaRunBudget;
     /**
-     * RUNTIME-ONLY observed-URL callback (#164 handoff crux): threaded into the participant's session so the
-     * orchestrator watches this seat's live location.href mid-run. Never persisted (see
-     * CuaLoopOptions.onObservedUrl). The concurrent shared-world barrier passes a host-seat latch here
+     * runtime-only observed-URL callback (the shared-world handoff): threaded into the participant's session so the
+     * orchestrator watches this participant's live location.href mid-run. Never persisted (see
+     * CuaLoopOptions.onObservedUrl). The concurrent shared-world barrier passes a host latch here
      * to extract a /lobby/CODE; on ordinary routes it is undefined (no-op).
      */
     onObservedUrl?: (url: string | undefined) => void;
-    /** RUNTIME-ONLY per-turn narration callback; see CuaLoopOptions.onMessage. The concurrent
-     * shared-world barrier passes a host-seat message scanner here to latch the lobby code. */
+    /** runtime-only per-turn narration callback; see CuaLoopOptions.onMessage. The concurrent
+     * shared-world barrier passes a host message scanner here to latch the lobby code. */
     onMessage?: (text: string) => void;
-    /** RUNTIME-ONLY per-turn raw-frame callback; see CuaLoopOptions.onScreenshot. The concurrent
-     * shared-world barrier passes a host-seat vision reader here to latch the lobby code off-screen. */
+    /** runtime-only per-turn raw-frame callback; see CuaLoopOptions.onScreenshot. The concurrent
+     * shared-world barrier passes a host vision reader here to latch the lobby code off-screen. */
     onScreenshot?: (frame: Buffer) => void;
-    /** Per-turn trace snapshot from a participant's loop (#441), keyed by participant. The live path
+    /** Per-turn trace snapshot from a participant's loop, keyed by participant. The live path
      * wires the incremental in-progress flush here so the attached Observer's timeline grows mid-run. */
     onTrace?: (participantId: string, items: readonly ActorTraceItem[], usage?: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
 }
@@ -438,8 +436,8 @@ export interface ParticipantRunOutcome {
      *  the session's evidence does not show. An execution failure, scrubbed, like the cleanup one. */
     providerPolicyError?: string;
     sandboxId?: string;
-    /** Host-side E2B desktop create->teardown span (ms). An APPROXIMATION of E2B's server-side
-     *  billed lifetime (server-side kill-on-timeout can extend it) — so the derived dollar figure is
+    /** Host-side E2B desktop create->teardown span (ms). An approximation of E2B's server-side
+     *  billed lifetime (server-side kill-on-timeout can extend it), so the derived dollar figure is
      *  doubly an estimate. Absent on the in-process route (no sandbox) and on dry-run. */
     desktopDurationMs?: number;
     desktopResources?: DesktopResourceObservation;
@@ -463,7 +461,7 @@ export interface ParticipantRunOutcome {
     skippedReason?: string;
     noEngagement: boolean;
     selfReportedBlocker: boolean;
-    /** The inclusive friction read (#453): blocker-shaped narration incl. self-resolved arcs.
+    /** The inclusive friction read: blocker-shaped narration incl. self-resolved arcs.
      *  Feeds the participants tally and feedback candidates; never the participant verdict. Optional so
      *  external outcome constructors (shared-world, test fakes) stay valid; absent counts as false. */
     reportedFriction?: boolean;

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

@@ -11,24 +11,24 @@ import {} from "../../observer/render.js";
 import {} from "../../run/bundle.js";
 import {} from "../../run/streams.js";
 import {} from "../../run/contained-output.js";
-export const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
-// The only fan-out topology this slice ships: N participants = N independent E2B desktop
-// sandboxes, each its own world (clone/serve + subject.state per participant). Shared-world is layer 7 (#164).
+import {} from "../../run/study-result.js";
+// The fan-out topology of this route: N participants = N independent E2B desktop sandboxes,
+// each its own world (clone/serve + subject.state per participant). Shared-world has its own route.
 export const CUA_FANOUT_STRATEGY = "per-lane-worlds";
-// Env override that may only LOWER the effective concurrency (never raise concurrent paid
-// desktops — invariant 3). Read names-only into a local; the value never persists.
+// Env override that may only lower the effective concurrency (never raise concurrent paid
+// desktops). Read names-only into a local; the value never persists.
 export const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
-// The DEFAULT session budget, sized so a study can FINISH (docs/principles/three-roles.md: a
-// session ends because the participant is done, not because a timer fired — the time-box is a
+// The default session budget, sized so a study can finish (docs/principles/three-roles.md: a
+// session ends because the participant is done, not because a timer fired; the time-box is a
 // session-level cap a researcher sets generously; spend protection is the dollar caps' job).
 // The old 300s default ended real signup studies mid-flow: observed studies run 16-40 turns at
-// ~5-6s per turn BEFORE any email wait, so five minutes was the biggest single source of
+// ~5-6s per turn before any email wait, so five minutes was the biggest single source of
 // budget_reached endings that read as participant failures.
 //
 // App-url and in-process routes default to 30 minutes. Provisioned routes (clone/local-tree)
 // default to whatever the 1-hour sandbox cap leaves after provisioning, declared state seeding,
-// and the teardown buffer — 20 minutes on a stateless clone — floored at the old five minutes so
-// a state-heavy lab still gets a session at all. An EXPLICIT execution.timeoutMs is never
+// and the teardown buffer (20 minutes on a stateless clone), floored at the old five minutes so
+// a state-heavy lab still gets a session at all. An explicit execution.timeoutMs is never
 // adjusted: when it cannot be provisioned, the plan-time cap refusal shows the arithmetic.
 export const DEFAULT_APP_URL_SESSION_TIMEOUT_MS = 30 * 60_000;
 export const MIN_DERIVED_SESSION_TIMEOUT_MS = 5 * 60_000;

package/dist/routes/preview.d.ts

@@ -1,13 +1,19 @@
 import type { AdmittedPlan, RunLabOptions } from "../run-lab.js";
 import type { LabPlan, PlanRefusal } from "../lab/plan-types.js";
 import type { RunResult } from "../run/results.js";
+import { type StudyResultIdentity } from "../run/study-result.js";
 type PreviewPlan = Extract<LabPlan, {
     readonly route: "preview";
 }>;
+/**
+ * The preview route's result when a study runs: the synthetic run's result, named as a study
+ * result. `humanish run` with no study returns the plain `RunResult`.
+ */
+export type PreviewStudyResult = Omit<RunResult, "schema"> & StudyResultIdentity<"preview">;
 /** A refused preview's result. */
-export declare function previewLabRefusal(cwd: string, refusal: Extract<PlanRefusal, {
+export declare function previewLabRefusal(cwd: string, studyId: string, refusal: Extract<PlanRefusal, {
     readonly route: "preview";
-}>): RunResult;
+}>): PreviewStudyResult;
 /** runLab's step for a preview plan: it has no local checks and takes no scorer, so it returns its run. */
 export declare function admitPreviewPlan(plan: PreviewPlan, input: Pick<RunLabOptions, "cwd" | "runId" | "open">): AdmittedPlan<"preview">;
 export {};

package/dist/routes/preview.js

@@ -1,11 +1,12 @@
 // The preview route: a lab whose subject is this repo runs the synthetic dry run. planLab decides
 // the sim count and refuses what a synthetic run would ignore; runPreviewPlan does the rest.
+import { studyResultIdentity } from "../run/study-result.js";
 import { runDryRun } from "../run/dry-run.js";
 import path from "node:path";
 /** A refused preview's result. */
-export function previewLabRefusal(cwd, refusal) {
+export function previewLabRefusal(cwd, studyId, refusal) {
     return {
-        schema: "humanish.run-result.v1",
+        ...studyResultIdentity("preview", studyId),
         ok: false,
         cwd: path.resolve(cwd),
         warnings: [],
@@ -18,7 +19,10 @@ export function admitPreviewPlan(plan, input) {
         ok: true,
         run: async () => ({
             route: "preview",
-            result: await runPreviewPlan(plan, input),
+            result: {
+                ...(await runPreviewPlan(plan, input)),
+                ...studyResultIdentity("preview", plan.labId),
+            },
         }),
     };
 }
@@ -28,7 +32,7 @@ function runPreviewPlan(plan, input) {
         ...(plan.lab === undefined ? {} : { lab: plan.lab }),
         cwd: input.cwd,
         dryRun: true,
-        simCount: plan.participantCount,
+        participantCount: plan.participantCount,
         ...(input.runId === undefined ? {} : { runId: input.runId }),
         ...(input.open === undefined ? {} : { observer: { open: input.open } }),
     });

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

@@ -34,8 +34,8 @@ interface ScriptedBundleArgs {
     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
+ * Project the scripted lab run into a humanish.run-bundle.v1 (no schema change: a new
+ * producer only). The key 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.
  */

package/dist/routes/scripted/bundle.js

@@ -1,5 +1,6 @@
 // Assemble the scripted-browser lab's run bundle from its sessions, and the review summary and
 // markdown that ship with it.
+import { verdictText } from "../../run/judge.js";
 import { redactText } from "../../evidence/redaction.js";
 import { buildRunCostSummary, desktopSpanToMinutes, spendFreeCostSummary, } from "../../run/cost-summary.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
@@ -7,8 +8,8 @@ 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
+ * Project the scripted lab run into a humanish.run-bundle.v1 (no schema change: a new
+ * producer only). The key 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.
  */
@@ -26,7 +27,7 @@ export function buildScriptedLabBundle(args) {
         persona: {
             id: args.persona.id,
             name: `Scripted journey persona (${args.persona.id})`,
-            source: `lab:${args.labId}`,
+            source: `study:${args.labId}`,
             sourceDigest: args.persona.promptDigest,
         },
         scenario: {
@@ -49,8 +50,8 @@ export function buildScriptedLabBundle(args) {
         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.",
+                ? "Scripted step URLs are reduced to loopback origin and path (query and hash removed), and step text passes text redaction. Screenshots are unblurred and kept for local use in the gitignored .humanish/ folder; they are not redacted for publishing, and policies.redactScreenshots is not supported on this route yet."
+                : "Dry-run bundle: no browser ran and no screenshots were captured. The scenario is digest-pinned; live step text passes text redaction when a session runs.",
         },
         artifacts: bundleArtifacts(),
         review,
@@ -75,11 +76,11 @@ function scriptedEvents(args) {
             at: args.run.createdAt,
             level: "info",
             type: "scripted-lab.subject.declared",
-            // Invariant 5: provenance recorded or its absence declared. The lab did not provision
+            // Provenance is 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}.`,
+                : `Subject app declared at ${args.appUrl}; humanish did not provision it, so its build and commit are unpinned. The evidence is tied to the scenario digest ${args.scenarioSourceDigest}.`,
         },
         {
             id: "event-002-spend",
@@ -98,7 +99,7 @@ function scriptedEvents(args) {
                 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}`,
+                message: `${result.capture.surface.id}: ${result.status} (${result.reason})`,
             }));
         }
     }
@@ -117,7 +118,7 @@ function scriptedEvents(args) {
             at: args.run.createdAt,
             level: "info",
             type: "scripted-lab.contract.ready",
-            message: `Dry-run contract bundle ready: scenario ${args.journey.scenarioId} @ ${args.scenarioSourceDigest} (${args.scenarioSource}, ${args.journey.steps.length} step${args.journey.steps.length === 1 ? "" : "s"}) parsed and digest-pinned; switch scenario.mode to live to actuate a real browser.`,
+            message: `Dry-run 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;
@@ -151,8 +152,8 @@ function buildScriptedReview(args) {
         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)."],
+            summary: `Dry run of scenario ${args.journey.scenarioId} (${args.scenarioSource}, ${args.journey.steps.length} steps) against ${args.appUrl}: composition and scenario checked at $0; no browser ran.`,
+            gaps: ["Live scripted session not yet run (dry run only)."],
         };
     }
     const passed = args.sessionResults.filter((result) => result.status === "passed").length;
@@ -176,7 +177,7 @@ export function renderScriptedReviewMarkdown(bundle) {
         "",
         `- run: ${bundle.runId}`,
         `- mode: ${bundle.mode}`,
-        `- verdict: ${bundle.review.verdict}`,
+        `- verdict: ${verdictText(bundle.review.verdict, bundle.mode)}`,
         `- summary: ${bundle.review.summary}`,
         `- scenario: ${bundle.scenario.id} @ ${bundle.scenario.sourceDigest} (${bundle.scenario.source})`,
         ...(subject ? [`- subject: ${subject.message}`] : []),

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

@@ -2,7 +2,7 @@ import type { LabDeps } from "../../lab/lab-deps.js";
 import type { RoutePlanResult, RouteRefusal, ScriptedPlan } from "../../lab/plan-types.js";
 import type { LabConfig } from "../../lab/types.js";
 /** 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"> {
+export interface ScriptedRefusal extends RouteRefusal<"scripted", "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_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.

package/dist/routes/scripted/plan.js

@@ -29,23 +29,23 @@ export function planScriptedLab(config, input) {
     });
     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);
+        return refuse("HUMANISH_SCRIPTED_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);
+        return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message, beforeScope);
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
-        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason, beforeScope);
+        return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason, beforeScope);
     const mediaReason = desktopMediaValidationReason(config);
     if (mediaReason)
-        return refuse("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", mediaReason);
+        return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", mediaReason);
     const cloneTargetReason = cloneTargetValidationReason(config);
     if (cloneTargetReason)
-        return refuse("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", cloneTargetReason);
+        return refuse("HUMANISH_SCRIPTED_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.`);
+        return refuse("HUMANISH_SCRIPTED_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.
@@ -53,19 +53,19 @@ export function planScriptedLab(config, input) {
     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]" });
+            return refuse("HUMANISH_SCRIPTED_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 });
+            return refuse("HUMANISH_SCRIPTED_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) });
+        return refuse("HUMANISH_SCRIPTED_SCENARIO_INVALID", "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.", { actor, appUrl: evidenceAppUrlOf(subject) });
     const requirements = [];
     if (!input.dryRun && subject.kind === "clone") {
         requirements.push({ kind: "key", name: "E2B_API_KEY" });

package/dist/routes/scripted/result.js

@@ -3,7 +3,8 @@ 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";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /** What judgeScripted reads from one surface's session. Scripted has no engagement or blocker rule. */
 function scriptedSurfaceFacts(result) {
     return {
@@ -116,7 +117,7 @@ export async function finishScriptedRun(inputs) {
     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.");
+        warnings.push("Screenshots are unblurred for local use: the bundle stays in the gitignored .humanish/ folder and nothing scans these pixels, so review them before sharing. policies.redactScreenshots is not supported on the scripted route yet.");
     }
     const observer = await finished.renderObserver();
     await validatePreparedRunArtifactPaths(runPaths);
@@ -135,10 +136,9 @@ export async function finishScriptedRun(inputs) {
     await finished.recordOutcome({ ok, execution });
     const harnessErrorSession = sessionResults.find((result) => result.completionReason === "harness_error");
     return {
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ...studyResultIdentity("scripted", plan.labId),
         ok,
         cwd,
-        labId: plan.labId,
         actor,
         appUrl: evidenceAppUrl,
         dryRun,
@@ -167,7 +167,7 @@ export async function finishScriptedRun(inputs) {
             ? {}
             : {
                 error: {
-                    code: "HUMANISH_SCRIPTED_LAB_FAILED",
+                    code: "HUMANISH_SCRIPTED_FAILED",
                     message: sessionError ??
                         (observer.ok
                             ? harnessErrorSession

package/dist/routes/scripted/route.js

@@ -10,7 +10,7 @@
 // against a real app (it fills forms and clicks buttons). A dry run parses and digest-pins the
 // scenario and writes the contract bundle without touching anything.
 //
-// Subject provenance (invariant 5): an app-url run declares that the lab did not provision the
+// Subject provenance: an app-url run declares that the lab did not provision the
 // subject, so its build provenance is unpinned and the evidence binds to the scenario digest. A
 // clone run records commit, env names, state provenance and a host digest, never the raw getHost
 // URL or a secret value.
@@ -30,7 +30,8 @@ import { UnsafeScriptedSessionResultError } from "./session-result.js";
 import { prepareScriptedRun } from "./setup.js";
 import { ScriptedSubject } from "./subject.js";
 import { runScriptedSessions, writeSurfaceTraces } from "./surface-sessions.js";
-import { SCRIPTED_BROWSER_LAB_SCHEMA, } from "./types.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /**
  * The config-taking entry point. It plans, returns a refusal with the envelope the route has always
  * returned at that refusal's stage, and otherwise runs the plan.
@@ -56,10 +57,9 @@ export async function scriptedLabRefusal(options, refusal) {
     const actorType = config.actors[0]?.type ?? "";
     if (refusal.beforeScope)
         return {
-            schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+            ...studyResultIdentity("scripted", config.id),
             ok: false,
             cwd,
-            labId: config.id,
             actor: actorType,
             dryRun,
             runId: options.runId ?? "not-created",
@@ -72,10 +72,9 @@ export async function scriptedLabRefusal(options, refusal) {
     const physicalCwd = await realpath(cwd);
     await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
     const refused = {
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ...studyResultIdentity("scripted", config.id),
         ok: false,
         cwd,
-        labId: config.id,
         actor: refusal.actor ?? actorType,
         appUrl: refusal.appUrl ?? config.subject.appUrl ?? "",
         dryRun,

package/dist/routes/scripted/scenario.js

@@ -26,7 +26,7 @@ export async function resolveScriptedScenario(projectRoot, ref) {
         if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
             return {
                 ok: false,
-                message: `scenario.ref path must stay inside the target cwd (got "${trimmed}") — provenance is recorded repo-relative and an escaping path cannot be.`,
+                message: `scenario.ref must stay inside the project directory, and "${trimmed}" does not: the run records it relative to the project.`,
             };
         }
         source = relative.split(path.sep).join("/");
@@ -80,7 +80,7 @@ export async function resolveScriptedScenario(projectRoot, ref) {
     if (!parsed.journey) {
         return {
             ok: false,
-            message: `${source} declares no executable browser steps — the scripted-browser actor needs a scenario with browser.steps.`,
+            message: `${source} declares no browser steps, and the scripted-browser actor needs a scenario with browser.steps.`,
         };
     }
     return { ok: true, journey: parsed.journey, source, sourceDigest };