humanish 0.111.1 → 0.111.3

package/dist/run/run.js

@@ -2,16 +2,18 @@
 // token that lets the Observer and automatic analysis read it. Routes build bundles and write
 // their own evidence files; this module owns when the run starts, how it is published, and how it
 // is closed on every exit.
+import { randomBytes } from "node:crypto";
 import { redactText } from "../evidence/redaction.js";
 import { buildObserverData } from "../observer/data.js";
 import { renderObserver } from "../observer/render.js";
-import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, } from "./bundle.js";
+import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, buildRunSource, } from "./bundle.js";
 import { judgeExecution, } from "./judge.js";
 import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
 import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
+import { RunSecrets } from "./secrets.js";
 import { beginRunStatus, runStatusOutcome, } from "./status.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
@@ -239,7 +241,7 @@ export async function runScope(fn) {
         return operation;
     };
     const refuse = (message) => Promise.reject(new RunLifecycleError(message));
-    const startRun = (options) => {
+    const startRunWith = (options) => {
         if (closed)
             return refuse("The run scope has closed.");
         if (started)
@@ -277,6 +279,9 @@ export async function runScope(fn) {
             return { ok: true, run: run.run };
         })());
     };
+    function startRun(...args) {
+        return args.length === 1 ? startRunWith(args[0]) : startRecordedRun(startRunWith, ...args);
+    }
     const openRun = (options, runId, paths, runStatus) => {
         const now = options.now ?? Date.now;
         const createdAt = new Date(now()).toISOString();
@@ -301,6 +306,7 @@ export async function runScope(fn) {
             mode: options.mode,
             ...(options.study === undefined ? {} : { study: options.study }),
             paths,
+            secrets: options.secrets ?? new RunSecrets([]),
             participantStarted() {
                 participantsRan = true;
             },
@@ -348,3 +354,33 @@ export async function runScope(fn) {
     }
     return { result: outcome.result, finished };
 }
+/** Start a recorded route's run through `start`, the scope's own form, then capture its source. */
+async function startRecordedRun(start, plan, input, route) {
+    const started = await start({
+        cwd: route.cwd,
+        runId: input.runId,
+        mintRunId: () => mintRunId(route.prefix),
+        mode: plan.dryRun ? "dry-run" : "live",
+        study: plan.study,
+        warnings: plan.warnings,
+        sandboxes: route.sandboxes,
+        renderReview: route.renderReview,
+        observer: { open: input.open === true, render: input.deps?.renderObserver },
+        now: route.now,
+        secrets: route.secrets,
+    });
+    if (!started.ok)
+        return started;
+    const source = await buildRunSource({
+        cwd: route.cwd,
+        capturedAt: started.run.createdAt,
+        humanishSource: "present",
+        packageName: "humanish",
+    });
+    return { ok: true, run: { ...started.run, source } };
+}
+/** `<prefix>-<wall-clock time, with : and . as ->-<8 hex>`. */
+function mintRunId(prefix) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${prefix}-${stamp}-${randomBytes(4).toString("hex")}`;
+}

package/dist/run/secrets.d.ts

@@ -0,0 +1,22 @@
+/** Each route's seed list, marker and floor are its own; the defaults are what most routes use. */
+interface RunSecretsOptions {
+    /** The text that replaces each value. */
+    readonly marker?: string;
+    /** The shortest value scrubbed. A shorter value is ordinary text often enough to leave alone. */
+    readonly minLength?: number;
+}
+export declare class RunSecrets {
+    #private;
+    /**
+     * Replaces every held value with the marker. It reads the values on each call, so a value added
+     * after the scrub was handed to a participant or a subject is scrubbed from then on.
+     */
+    readonly scrub: (text: string) => string;
+    /** `seed` keeps its order; values shorter than the floor are dropped. */
+    constructor(seed: readonly string[], options?: RunSecretsOptions);
+    /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
+    add(values: readonly string[]): void;
+    /** The held values, seed first, in one array that later `add` calls extend. */
+    values(): readonly string[];
+}
+export {};

package/dist/run/secrets.js

@@ -0,0 +1,33 @@
+// The literal values one run scrubs from what it writes: the provider keys and subject env values
+// its route reads, and the values the run provisions while it runs, such as the addresses email
+// receiving registers. These have no secret shape for pattern redaction to find, so each is
+// replaced as written; redactText runs after the scrub and finds secrets by shape.
+import { scrubLiterals } from "../evidence/redaction.js";
+export class RunSecrets {
+    // Private fields stay out of JSON.stringify and object spread, so a Run that reaches a writer
+    // whole cannot carry the values with it.
+    #held;
+    #minLength;
+    /**
+     * Replaces every held value with the marker. It reads the values on each call, so a value added
+     * after the scrub was handed to a participant or a subject is scrubbed from then on.
+     */
+    scrub;
+    /** `seed` keeps its order; values shorter than the floor are dropped. */
+    constructor(seed, options = {}) {
+        // An empty value would match between every character.
+        this.#minLength = Math.max(1, options.minLength ?? 4);
+        this.#held = seed.filter((value) => value.length >= this.#minLength);
+        this.scrub = scrubLiterals(this.#held, options.marker);
+    }
+    /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
+    add(values) {
+        for (const value of values)
+            if (value.length >= this.#minLength && !this.#held.includes(value))
+                this.#held.push(value);
+    }
+    /** The held values, seed first, in one array that later `add` calls extend. */
+    values() {
+        return this.#held;
+    }
+}

package/dist/run/study-result.d.ts

@@ -7,5 +7,39 @@ export interface StudyResultIdentity<R extends string> {
     /** The study's `id`. */
     studyId: string;
 }
+/**
+ * The error codes every recorded route's result can carry besides its own: a study, option or
+ * analysis refusal from before the route's checks, and a run id that is already taken. Each route's
+ * error-code union is this set plus the codes named for that route.
+ */
+export type StudyResultErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_RUN_ID_IN_USE";
 /** The identity fields for a result of route `route` from the study `studyId`. */
 export declare function studyResultIdentity<R extends string>(route: R, studyId: string): StudyResultIdentity<R>;
+/** What every refused study's result carries besides its identity and its route's own fields. */
+export interface RefusalBase<C extends string> {
+    /** The study's `id`. */
+    studyId: string;
+    cwd: string;
+    /** The caller's warnings array, kept by reference so warnings added later still show. Empty when omitted. */
+    warnings?: string[];
+    error: {
+        code: C;
+        message: string;
+    };
+}
+/**
+ * A refused study's result on route `route`: its identity, `ok: false` and `cwd`, then `fields`
+ * in the caller's order, then `warnings` and `error`. A result is written as JSON, so the key order
+ * is part of the output; a site whose order differs spreads its remaining fields after this. The
+ * caller keeps runId, actor, dryRun and the route's fields, whose values and order differ by site.
+ */
+export declare function refusedResult<R extends string, C extends string, F extends object>(route: R, base: RefusalBase<C>, fields: F): StudyResultIdentity<R> & {
+    ok: false;
+    cwd: string;
+} & F & {
+    warnings: string[];
+    error: {
+        code: C;
+        message: string;
+    };
+};

package/dist/run/study-result.js

@@ -7,3 +7,19 @@ export const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
 export function studyResultIdentity(route, studyId) {
     return { schema: STUDY_RESULT_SCHEMA, route, studyId };
 }
+/**
+ * A refused study's result on route `route`: its identity, `ok: false` and `cwd`, then `fields`
+ * in the caller's order, then `warnings` and `error`. A result is written as JSON, so the key order
+ * is part of the output; a site whose order differs spreads its remaining fields after this. The
+ * caller keeps runId, actor, dryRun and the route's fields, whose values and order differ by site.
+ */
+export function refusedResult(route, base, fields) {
+    return {
+        ...studyResultIdentity(route, base.studyId),
+        ok: false,
+        cwd: base.cwd,
+        ...fields,
+        warnings: base.warnings ?? [],
+        error: base.error,
+    };
+}

package/dist/study/requirements.d.ts

@@ -1,8 +1,5 @@
-import type { StudyPlan, Requirement } from "./plan-types.js";
-/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
-export declare function missingKeys(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
-/** The subject env names the requirements list and `env` lacks, in declaration order. */
-export declare function missingSubjectEnv(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
+import { type LocalAgentRefusal } from "../actors/local-agent/readiness.js";
+import type { Brain, StudyPlan, Requirement } from "./plan-types.js";
 /**
  * The provider keys the requirements name, in plan order. A `key-one-of` names the first of its
  * keys that `isPresent` reports, else OPENAI_API_KEY.
@@ -18,3 +15,61 @@ export declare function requiredSubjectEnv(requirements: readonly Requirement[])
  * a declared scorer's host code, are not in the plan.
  */
 export declare function keyNamesOf(plan: StudyPlan): ReadonlySet<string>;
+/** A live check's refusal, in its route's error code. */
+export interface LiveRefusal<C extends string> {
+    readonly code: C;
+    readonly message: string;
+}
+/** One live check: its refusal, or undefined when this machine passes it. */
+export type LiveCheck<C extends string> = () => LiveRefusal<C> | undefined | Promise<LiveRefusal<C> | undefined>;
+/**
+ * The first refusal of `checks`, run one at a time in the order given. Which check comes first
+ * decides which error a run with two problems reports, so each route keeps its own order.
+ */
+export declare function firstLiveRefusal<C extends string>(checks: readonly LiveCheck<C>[]): Promise<LiveRefusal<C> | undefined>;
+/**
+ * Refuses a run whose environment lacks a provider key the requirements list. `need` writes the
+ * route's sentence for the missing names ("OPENAI_API_KEY and E2B_API_KEY"); the message goes on
+ * to say where discovery looked and what fills each key. With `suggestLocalAgent`, a missing
+ * OPENAI_API_KEY also names each coding agent signed in on this machine: someone new meets this
+ * refusal first, and an agent they already use runs the participants without a key.
+ */
+export declare function keysCheck<C extends string>(args: {
+    readonly requirements: readonly Requirement[];
+    readonly env: Record<string, string | undefined>;
+    readonly code: C;
+    readonly need: (names: string) => string;
+    readonly suggestLocalAgent?: boolean;
+}): Promise<LiveRefusal<C> | undefined>;
+/**
+ * Refuses a local-agent brain whose CLI is missing, signed out, too old, or cannot honor the
+ * caps, before any sandbox is paid for. `codes` names the route's code for each kind of refusal.
+ */
+export declare function localAgentCheck<C extends string>(args: {
+    readonly brain: Brain;
+    readonly env: Record<string, string | undefined>;
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+    readonly codes: Readonly<Record<LocalAgentRefusal["kind"], C>>;
+}): Promise<LiveRefusal<C> | undefined>;
+/** Refuses a run whose environment lacks a subject env name the requirements list. */
+export declare function subjectEnvCheck<C extends string>(args: {
+    readonly requirements: readonly Requirement[];
+    readonly env: Record<string, string | undefined>;
+    readonly code: C;
+}): LiveRefusal<C> | undefined;
+/**
+ * Refuses a maxUsd or maxTotalUsd cap on a model with no rate in src/run/pricing.ts. The loop
+ * could not measure spend against the cap, and running uncapped would drop the protection the
+ * cap promised; the operator picks a priced model or removes the cap.
+ */
+export declare function unpricedCapCheck<C extends string>(args: {
+    readonly caps: {
+        readonly maxUsd?: number;
+        readonly maxTotalUsd?: number;
+    };
+    readonly model: string;
+    readonly code: C;
+}): LiveRefusal<C> | undefined;

package/dist/study/requirements.js

@@ -1,13 +1,23 @@
+// The keys and subject env a live plan's requirements list, and the live checks that read them.
+// Each route lists the checks below (keysCheck, localAgentCheck, subjectEnvCheck,
+// unpricedCapCheck) in its own order, with its own error codes. Doctor and the TUI ask
+// requiredKeys and requiredSubjectEnv which names to report, and `run` asks keyNamesOf which
+// key-source lines to print, so the planner alone decides what a run needs. The terminal runtime
+// key (`key-one-of`) stays with buildRuntimeAuth at run time, which also picks its placement.
+import { detectLocalAgents } from "../actors/local-agent/cli.js";
+import { localAgentRefusal } from "../actors/local-agent/readiness.js";
+import { describeMissingKeys } from "../keys/key-resolution.js";
+import { MODEL_RATES, unpricedCapMessage } from "../run/pricing.js";
 /** Provider keys in the order the routes name them in a refusal. */
 const KEY_ORDER = ["OPENAI_API_KEY", "E2B_API_KEY"];
 const present = (env, name) => (env[name]?.trim() ?? "") !== "";
 /** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
-export function missingKeys(requirements, env) {
+function missingKeys(requirements, env) {
     const required = new Set(requirements.flatMap((requirement) => (requirement.kind === "key" ? [requirement.name] : [])));
     return KEY_ORDER.filter((name) => required.has(name) && !present(env, name));
 }
 /** The subject env names the requirements list and `env` lacks, in declaration order. */
-export function missingSubjectEnv(requirements, env) {
+function missingSubjectEnv(requirements, env) {
     return requiredSubjectEnv(requirements).filter((name) => !present(env, name));
 }
 /**
@@ -52,3 +62,79 @@ export function keyNamesOf(plan) {
         names.add("OPENAI_API_KEY");
     return names;
 }
+/**
+ * The first refusal of `checks`, run one at a time in the order given. Which check comes first
+ * decides which error a run with two problems reports, so each route keeps its own order.
+ */
+export async function firstLiveRefusal(checks) {
+    for (const check of checks) {
+        const refusal = await check();
+        if (refusal !== undefined)
+            return refusal;
+    }
+    return undefined;
+}
+/**
+ * Refuses a run whose environment lacks a provider key the requirements list. `need` writes the
+ * route's sentence for the missing names ("OPENAI_API_KEY and E2B_API_KEY"); the message goes on
+ * to say where discovery looked and what fills each key. With `suggestLocalAgent`, a missing
+ * OPENAI_API_KEY also names each coding agent signed in on this machine: someone new meets this
+ * refusal first, and an agent they already use runs the participants without a key.
+ */
+export async function keysCheck(args) {
+    const { env } = args;
+    const missing = missingKeys(args.requirements, env);
+    if (missing.length === 0)
+        return undefined;
+    const suggestion = args.suggestLocalAgent === true && missing.includes("OPENAI_API_KEY")
+        ? await signedInAgentSuggestion(env)
+        : "";
+    return {
+        code: args.code,
+        message: `${args.need(missing.join(" and "))} ${describeMissingKeys(missing, env)}${suggestion}`,
+    };
+}
+/** The sentence naming the coding agents signed in on this machine, or "" when none is. */
+async function signedInAgentSuggestion(env) {
+    const ready = (await detectLocalAgents({ env })).filter((agent) => agent.authStatus === "authenticated");
+    if (ready.length === 0)
+        return "";
+    const labels = ready.map((agent) => agent.label).join(" and ");
+    return ` ${labels} reports authenticated on this machine. Set actor.type: local-agent to use ${ready.length === 1 ? "it" : "one"} instead of a key.`;
+}
+/**
+ * Refuses a local-agent brain whose CLI is missing, signed out, too old, or cannot honor the
+ * caps, before any sandbox is paid for. `codes` names the route's code for each kind of refusal.
+ */
+export async function localAgentCheck(args) {
+    const { brain, env, caps } = args;
+    if (brain.kind !== "local-agent")
+        return undefined;
+    const refusal = await localAgentRefusal({ agent: brain.agent, env, caps });
+    return refusal === undefined
+        ? undefined
+        : { code: args.codes[refusal.kind], message: refusal.message };
+}
+/** Refuses a run whose environment lacks a subject env name the requirements list. */
+export function subjectEnvCheck(args) {
+    const unset = missingSubjectEnv(args.requirements, args.env);
+    if (unset.length === 0)
+        return undefined;
+    return {
+        code: args.code,
+        message: `subject.env declares ${unset.join(", ")} but the environment does not provide ${unset.length === 1 ? "it" : "them"} (pass via --dotenv; values are never persisted).`,
+    };
+}
+/**
+ * Refuses a maxUsd or maxTotalUsd cap on a model with no rate in src/run/pricing.ts. The loop
+ * could not measure spend against the cap, and running uncapped would drop the protection the
+ * cap promised; the operator picks a priced model or removes the cap.
+ */
+export function unpricedCapCheck(args) {
+    const { caps, model } = args;
+    if (caps.maxUsd === undefined && caps.maxTotalUsd === undefined)
+        return undefined;
+    if (MODEL_RATES[model.trim().toLowerCase()])
+        return undefined;
+    return { code: args.code, message: unpricedCapMessage(model) };
+}

package/dist/study/run-study-events.d.ts

@@ -1,3 +1,4 @@
+import { RunSecrets } from "../run/secrets.js";
 import type { CuaParticipantPlan } from "../routes/computer-use/types.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
 import type { InternalRunStudyOptions } from "../run-study.js";
@@ -50,12 +51,12 @@ export type StudyEvent = {
  * analysis API key. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
-export declare function knownSecretValues(config: StudyConfig, options: InternalRunStudyOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): string[];
+export declare function knownSecrets(config: StudyConfig, options: InternalRunStudyOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): RunSecrets;
 /**
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
- * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
+ * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secrets`.
  */
-export declare function studyEventEmitter(onEvent: ((event: StudyEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: StudyEvent) => void) | undefined;
+export declare function studyEventEmitter(onEvent: ((event: StudyEvent) => void | Promise<void>) | undefined, warnings: string[], secrets: () => RunSecrets): ((event: StudyEvent) => void) | undefined;
 /** The computer-use participant plan as a `plan` event: ids, personas, devices and digests. */
 export declare function planEvent(plan: CuaParticipantPlan): StudyEvent;
 export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): StudyEvent;

package/dist/study/run-study-events.js

@@ -1,32 +1,28 @@
 // What a run reports through RunStudyOptions.onEvent, and how a callback failure becomes a run
 // warning. normalizeRunStudyOptions (run-study-options.ts) builds the emitter and hands it to the
 // route hook bags it maps; the event values are built here.
-import { redactText, scrubLiterals, toErrorMessage } from "../evidence/redaction.js";
+import { redactText, toErrorMessage } from "../evidence/redaction.js";
+import { RunSecrets } from "../run/secrets.js";
 /**
  * The literal values to scrub from an onEvent warning: the provider keys and the declared subject
  * env from every env the run could read (the `env` option and process.env), and the
  * analysis API key. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
-export function knownSecretValues(config, options, forwardedEnv) {
+export function knownSecrets(config, options, forwardedEnv) {
     const sources = [forwardedEnv, options.env, process.env];
     const names = ["OPENAI_API_KEY", "E2B_API_KEY", "CODEX_API_KEY", ...(config.subject.env ?? [])];
-    const values = new Set();
-    const add = (value) => {
-        const trimmed = value?.trim() ?? "";
-        if (trimmed.length >= 4)
-            values.add(trimmed);
-    };
+    const secrets = new RunSecrets([]);
     for (const env of sources)
         for (const name of names)
-            add(env?.[name]);
-    return [...values];
+            secrets.add([env?.[name]?.trim() ?? ""]);
+    return secrets;
 }
 /**
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
- * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
+ * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secrets`.
  */
-export function studyEventEmitter(onEvent, warnings, secretValues) {
+export function studyEventEmitter(onEvent, warnings, secrets) {
     if (onEvent === undefined)
         return undefined;
     return (event) => {
@@ -37,8 +33,7 @@ export function studyEventEmitter(onEvent, warnings, secretValues) {
             let detail;
             try {
                 // Read here, not up front: a run with no failing callback never touches the env.
-                const scrub = scrubLiterals(secretValues());
-                detail = redactText(scrub(toErrorMessage(error)));
+                detail = redactText(secrets().scrub(toErrorMessage(error)));
             }
             catch {
                 detail = "the thrown value has no message";

package/dist/study/run-study-options.d.ts

@@ -23,6 +23,9 @@ export declare function removedOptionRefusal(options: RunStudyOptions): Refusal
  * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
  */
 export declare function normalizeRunStudyOptions(config: StudyConfig, route: StudyRoute, options: InternalRunStudyOptions): Normalized | Refusal;
-/** A refusal in the route's own result envelope, before any run exists. */
+/**
+ * A refusal in the route's own result envelope, before any run exists. Each route's own fields come
+ * after `error` here.
+ */
 export declare function optionRefusalOutcome(config: StudyConfig, route: StudyRoute, options: RunStudyOptions, refusal: Refusal): StudyOutcome;
 export {};

package/dist/study/run-study-options.js

@@ -5,8 +5,8 @@
 import path from "node:path";
 import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { resolveStudyDryRun } from "./plan.js";
-import { knownSecretValues, studyEventEmitter } from "./run-study-events.js";
-import { studyResultIdentity } from "../run/study-result.js";
+import { knownSecrets, studyEventEmitter } from "./run-study-events.js";
+import { refusedResult } from "../run/study-result.js";
 import { participantList } from "./study-fields.js";
 const unsupported = (option, route, reason) => ({
     ok: false,
@@ -93,7 +93,7 @@ export function normalizeRunStudyOptions(config, route, options) {
     // The route gets this copy, so it is the env a warning is scrubbed against, whatever the caller
     // does to its own object afterwards.
     const forwardedEnv = env === undefined ? undefined : { ...env };
-    const emit = studyEventEmitter(onEvent, warnings, () => knownSecretValues(config, options, forwardedEnv));
+    const emit = studyEventEmitter(onEvent, warnings, () => knownSecrets(config, options, forwardedEnv));
     // Every route reads its typed options directly, and onEvent reaches it as `emit`. unsupportedOption
     // already refused an option no route reads; the preview route reads no env.
     const normalized = { ...forwarded };
@@ -101,33 +101,29 @@ export function normalizeRunStudyOptions(config, route, options) {
         normalized.env = forwardedEnv;
     return { ok: true, options: normalized, warnings, emit };
 }
-/** A refusal in the route's own result envelope, before any run exists. */
+/**
+ * A refusal in the route's own result envelope, before any run exists. Each route's own fields come
+ * after `error` here.
+ */
 export function optionRefusalOutcome(config, route, options, refusal) {
-    const cwd = path.resolve(options.cwd);
-    const error = { code: refusal.code, message: refusal.message };
-    const actor = config.actor?.type ?? "";
-    const dryRun = resolveStudyDryRun(config, options.dryRun, true) ?? true;
-    const runId = options.runId ?? "not-created";
-    const common = { ok: false, cwd, actor, dryRun, runId, warnings: [], error };
+    const base = {
+        studyId: config.id,
+        cwd: path.resolve(options.cwd),
+        error: { code: refusal.code, message: refusal.message },
+    };
+    const common = {
+        actor: config.actor?.type ?? "",
+        dryRun: resolveStudyDryRun(config, options.dryRun, true) ?? true,
+        runId: options.runId ?? "not-created",
+    };
     switch (route) {
         case "preview":
-            return {
-                route: "preview",
-                result: {
-                    ...studyResultIdentity("preview", config.id),
-                    ok: false,
-                    cwd,
-                    warnings: [],
-                    error,
-                },
-            };
+            return { route: "preview", result: refusedResult("preview", base, {}) };
         case "computer-use":
             return {
                 route: "computer-use",
                 result: {
-                    ...studyResultIdentity("computer-use", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("computer-use", base, common),
                     appUrl: config.subject.appUrl ?? config.subject.serve?.url ?? "",
                     lanes: [],
                 },
@@ -136,9 +132,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "scripted",
                 result: {
-                    ...studyResultIdentity("scripted", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("scripted", base, common),
                     appUrl: config.subject.appUrl ?? "",
                     sessions: [],
                 },
@@ -147,9 +141,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "terminal",
                 result: {
-                    ...studyResultIdentity("terminal", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("terminal", base, common),
                     product: config.subject.product?.name ?? "",
                 },
             };
@@ -158,9 +150,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
             return {
                 route: "shared-world",
                 result: {
-                    ...studyResultIdentity("shared-world", config.id),
-                    ...common,
-                    ok: false,
+                    ...refusedResult("shared-world", base, common),
                     topology: "shared-world",
                     topologyMode: "concurrent",
                     roleCount: participantCount,

package/dist/substrates/e2b/subject-sandbox.d.ts

@@ -0,0 +1,58 @@
+import type { PreparedOutputRoot } from "../../run/contained-output.js";
+import { type DesktopResourceObservation } from "./desktop-resources.js";
+import type { E2BDesktopModule, E2BDesktopSandbox } from "./sdk.js";
+/** The subject desktop's billed span and size, for the run's cost estimate. */
+export interface SubjectDesktopUsage {
+    durationMs: number | undefined;
+    observation: DesktopResourceObservation | undefined;
+    killed: boolean;
+}
+/** The run the subject sandbox reports to. */
+export interface SubjectSandboxRun {
+    /** The run's warnings. Acquisition and release append to it. */
+    warnings: string[];
+    scrub: (text: string) => string;
+    now: () => number;
+}
+/** How to create the subject sandbox. */
+export interface SubjectSandboxRequest {
+    module: E2BDesktopModule;
+    apiKey: string;
+    requestTimeoutMs: number;
+    /**
+     * The participants' session budget. The sandbox outlives it by the provision budget, each seed
+     * step's budget and the reclamation buffer, so E2B kills it only after the run is done with it.
+     */
+    sessionTimeoutMs: number;
+    seed: readonly {
+        readonly timeoutMs?: number | undefined;
+    }[];
+    /** The route's labels. Acquisition adds the run's owner tags. */
+    metadata: Record<string, string>;
+    /** The subject's environment at create; an empty record sets none. */
+    envs: Record<string, string>;
+    template: string | undefined;
+    /** Where the receipt goes, under the participant label `subject`. */
+    root: PreparedOutputRoot;
+}
+export declare class E2BSubjectSandbox {
+    sandboxId: string | undefined;
+    killed: boolean;
+    /** The scrubbed release warning when the release is unconfirmed. */
+    releaseWarning: string | undefined;
+    private readonly run;
+    private allocation;
+    private createdAtMs;
+    private tornDownAtMs;
+    private resources;
+    constructor(run: SubjectSandboxRun);
+    /**
+     * Creates the sandbox and reads its size. The receipt is on disk before this returns, so
+     * `humanish reclaim` can kill the sandbox by exact id if the process dies during provisioning.
+     */
+    acquire(request: SubjectSandboxRequest): Promise<E2BDesktopSandbox>;
+    /** Releases the sandbox by exact id, when one was acquired. An unconfirmed release is reported. */
+    release(): Promise<void>;
+    /** The billed span and size, when a sandbox was acquired. */
+    desktopUsage(): SubjectDesktopUsage | undefined;
+}