humanish 0.138.0 → 0.139.1

package/CHANGELOG.md

@@ -8,6 +8,27 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.139.1: Hosted Codex participants work with an AGENTS.md in the Codex home (2026-10-21)
+
+humanish 0.139.1 fixes hosted Codex participants for operators whose Codex home
+(`CODEX_HOME`, or `~/.codex`) holds an `AGENTS.md`. Codex adds that file to every thread, and
+humanish refused the launch as `codex_unsafe_configuration` with no reason. humanish now admits
+that file, leaves it unchanged, and says the participant also received it. Every other
+`codex_unsafe_configuration` refusal names the setting it refused.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.139.1)
+
+## 0.139.0: Computer-use studies can run on Modal desktops (2026-10-19)
+
+humanish 0.139.0 can run a computer-use study's desktops on Modal. Set
+`execution.target: modal-desktop` on an `app-url` study and each participant gets its own Modal
+sandbox running the same desktop the E2B route uses: Xvfb, XFCE, xdotool input, screenshots, a
+live noVNC stream, Chromium and recordings. The same study file runs on E2B or Modal
+with only the target changed. Clone and local-tree subjects, shared worlds, E2B templates and
+camera or speech media stay on E2B.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.139.0)
+
 ## 0.138.0: A terminal study can run on Modal (2026-10-19)
 
 humanish 0.138.0 can run a terminal study's shell on Modal as well as E2B. Set

package/dist/actors/codex/operator-instructions.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The note for an instruction file Codex added from the operator's Codex home: the participant
+ * also read it, so its persona may follow the operator's instructions.
+ */
+export declare function operatorInstructionsWarning(files: readonly string[] | undefined): string | undefined;

package/dist/actors/codex/operator-instructions.js

@@ -0,0 +1,9 @@
+/**
+ * The note for an instruction file Codex added from the operator's Codex home: the participant
+ * also read it, so its persona may follow the operator's instructions.
+ */
+export function operatorInstructionsWarning(files) {
+    if (files === undefined || files.length === 0)
+        return undefined;
+    return `Codex also gave this participant ${files.join(" and ")} from your Codex home (CODEX_HOME, or ~/.codex), as it does for every Codex thread. The participant may follow those instructions as well as its persona. humanish does not change that file.`;
+}

package/dist/actors/codex/restricted-launch.d.ts

@@ -53,15 +53,20 @@ export interface LaunchState {
     protocolIncompatibilities: string[] | undefined;
     /** Schema values beyond the baseline, recorded at launch. */
     protocolAdditions: string[] | undefined;
+    /** What in the operator's Codex setup a refusal objects to, without paths or values. */
+    refusalReason: string | undefined;
+    /** The instruction file names Codex added from the operator's Codex home (operator auth). */
+    operatorInstructionFiles: string[] | undefined;
 }
 /** An admitted value, or the refusal a launch stops with. */
 export type Admission<T> = {
     readonly value: T;
 } | {
     readonly refusal: RestrictedCodexAnalysisErrorCode;
+    readonly reason?: string;
 };
-/** The admitted value; a refusal stops the launch. */
-export declare function admitted<T>(admission: Admission<T>): T;
+/** The admitted value; a refusal stops the launch and records its reason on the state. */
+export declare function admitted<T>(admission: Admission<T>, state: Pick<LaunchState, "refusalReason">): T;
 /** `-c key=value` arguments for an operator-auth launch, which keeps the operator's config file. */
 export declare function configArguments(overrides: Record<string, unknown>): string[];
 /** initialize: the admitted release, this platform, and (isolated auth) the private home. */
@@ -109,9 +114,12 @@ export declare function admitThread(reply: Record<string, unknown>, expected: {
     cwd: string;
     reasoningEffort: ReasoningEffort;
     cliVersion: string;
+    /** Operator auth: the Codex home directories whose own instruction file is admitted. */
+    operatorHomes?: readonly string[];
 }): Admission<{
     model: string;
     threadId: string;
+    instructionFiles: string[];
 }>;
 /** mcpServerStatus/list (isolated auth): no MCP server is running for the thread. */
 export declare function admitMcpStatus(reply: Record<string, unknown>): Admission<void>;

package/dist/actors/codex/restricted-launch.js

@@ -10,12 +10,14 @@ import path from "node:path";
 import { checkVersion, childEnvironment, generateProtocolSchema, resolveExecutable, } from "./restricted-executable.js";
 import { checkProtocol, loadProtocolSchema } from "./protocol-compat.js";
 import { protocolContract } from "./protocol-contract.js";
-import { admitsRestrictedCodexConfig, admitsRestrictedCodexThread, codexRecord, restrictedCodexConfig, } from "./restricted-policy.js";
+import { restrictedCodexConfigViolation, admitsRestrictedCodexThread, codexRecord, restrictedCodexConfig, } from "./restricted-policy.js";
 import { RestrictedCodexDeadline, RestrictedCodexStop, RestrictedCodexTransport, ownCodexProcess, } from "./restricted-transport.js";
-/** The admitted value; a refusal stops the launch. */
-export function admitted(admission) {
-    if ("refusal" in admission)
+/** The admitted value; a refusal stops the launch and records its reason on the state. */
+export function admitted(admission, state) {
+    if ("refusal" in admission) {
+        state.refusalReason = admission.reason;
         throw new RestrictedCodexStop(admission.refusal);
+    }
     return admission.value;
 }
 /** `-c key=value` arguments for an operator-auth launch, which keeps the operator's config file. */
@@ -37,8 +39,12 @@ export function admitInitialize(reply, expected) {
 }
 /** config/read: the restricted configuration, and the model it selects, if any. */
 export function admitEffectiveConfig(reply, configPath, requestedModel, mode) {
-    if (!admitsRestrictedCodexConfig(reply, configPath, requestedModel, mode))
-        return { refusal: "codex_unsafe_configuration" };
+    const violation = restrictedCodexConfigViolation(reply, configPath, requestedModel, mode);
+    if (violation !== null)
+        return {
+            refusal: "codex_unsafe_configuration",
+            reason: `in the effective Codex config, ${violation}`,
+        };
     const configuredModel = codexRecord(reply.config).model;
     return { value: typeof configuredModel === "string" ? configuredModel : undefined };
 }
@@ -60,8 +66,16 @@ export function admitAccount(reply, operatorAuth) {
  */
 export function threadConfigFor(effectiveConfig, overrides) {
     const mcpNames = Object.keys(codexRecord(codexRecord(effectiveConfig.config).mcp_servers));
-    if (mcpNames.length > 100 || mcpNames.some((name) => !/^[A-Za-z0-9_-]{1,200}$/.test(name)))
-        return { refusal: "codex_unsafe_configuration" };
+    if (mcpNames.length > 100)
+        return {
+            refusal: "codex_unsafe_configuration",
+            reason: "more than 100 MCP servers are configured",
+        };
+    if (mcpNames.some((name) => !/^[A-Za-z0-9_-]{1,200}$/.test(name)))
+        return {
+            refusal: "codex_unsafe_configuration",
+            reason: "an MCP server name uses characters other than letters, digits, _ and -",
+        };
     const threadConfig = { ...overrides };
     for (const name of mcpNames)
         threadConfig[`mcp_servers.${name}.enabled`] = false;
@@ -101,14 +115,46 @@ export function threadStartParams(args) {
 }
 /** thread/start's reply: the model it runs (the selected one, when one was) and the thread id. */
 export function admitThread(reply, expected) {
+    const sources = Array.isArray(reply.instructionSources)
+        ? reply.instructionSources
+        : [];
+    // Codex adds the instruction file in its home to every thread, with no setting to skip it, and
+    // humanish never edits the operator's files. An operator-auth launch admits that one file and
+    // reports it; anything else stays refused. Basenames keep the operator's paths out of the run.
+    const homes = expected.operatorHomes ?? [];
+    const homeFile = (source) => typeof source === "string" &&
+        homes.includes(path.dirname(source)) &&
+        ["AGENTS.md", "AGENTS.override.md"].includes(path.basename(source));
+    const other = sources.filter((source) => !homeFile(source));
+    if (other.length > 0)
+        return {
+            refusal: "codex_unsafe_configuration",
+            reason: `Codex loaded instructions from ${other
+                .map((source) => (typeof source === "string" ? path.basename(source) : "a file"))
+                .join(", ")}`,
+        };
     const returnedModel = codexRecord(reply.thread).model;
     if (typeof returnedModel !== "string" ||
         returnedModel.length === 0 ||
         returnedModel.length > 200 ||
         (expected.selectedModel !== undefined && returnedModel !== expected.selectedModel) ||
-        !admitsRestrictedCodexThread(reply, returnedModel, expected.cwd, expected.reasoningEffort, expected.cliVersion))
+        !admitsRestrictedCodexThread({ ...reply, instructionSources: [] }, returnedModel, expected.cwd, expected.reasoningEffort, expected.cliVersion))
         return { refusal: "codex_unsafe_configuration" };
-    return { value: { model: returnedModel, threadId: String(codexRecord(reply.thread).id) } };
+    return {
+        value: {
+            model: returnedModel,
+            threadId: String(codexRecord(reply.thread).id),
+            instructionFiles: sources.filter(homeFile).map((source) => path.basename(source)),
+        },
+    };
+}
+/** The operator's Codex home as configured and as resolved, for matching its instruction file. */
+async function operatorCodexHomes(options, sourceEnv) {
+    const configured = options.authHome ?? sourceEnv.CODEX_HOME ?? path.join(sourceEnv.HOME ?? homedir(), ".codex");
+    if (!path.isAbsolute(configured))
+        return [];
+    const resolved = await realpath(configured).catch(() => configured);
+    return [...new Set([configured, resolved])];
 }
 /** mcpServerStatus/list (isolated auth): no MCP server is running for the thread. */
 export function admitMcpStatus(reply) {
@@ -223,15 +269,15 @@ export async function launchAdmittedAppServer(settings, state, request, deadline
         home,
         operatorAuth,
         platform: settings.platform,
-    }));
+    }), state);
     launched.notify("initialized", {});
     enter("config/read");
     const effective = await launched.rpc("config/read", { includeLayers: true, cwd: state.cwd });
-    const selectedModel = admitted(admitEffectiveConfig(effective, configPath, request.model, configMode));
+    const selectedModel = admitted(admitEffectiveConfig(effective, configPath, request.model, configMode), state);
     enter("account/read");
     const account = await launched.rpc("account/read", { refreshToken: false });
-    state.authentication = admitted(admitAccount(account, operatorAuth));
-    const threadConfig = admitted(threadConfigFor(effective, config.overrides));
+    state.authentication = admitted(admitAccount(account, operatorAuth), state);
+    const threadConfig = admitted(threadConfigFor(effective, config.overrides), state);
     enter("thread/start");
     const thread = await launched.rpc("thread/start", threadStartParams({
         cwd: state.cwd,
@@ -245,12 +291,15 @@ export async function launchAdmittedAppServer(settings, state, request, deadline
         cwd: state.cwd,
         reasoningEffort,
         cliVersion: state.cliVersion,
-    }));
+        ...(operatorAuth ? { operatorHomes: await operatorCodexHomes(options, sourceEnv) } : {}),
+    }), state);
     state.resolvedModel = started.model;
+    if (started.instructionFiles.length > 0)
+        state.operatorInstructionFiles = started.instructionFiles;
     state.threadId = started.threadId;
     if (!operatorAuth) {
         enter("mcpServerStatus/list");
-        admitted(admitMcpStatus(await launched.rpc("mcpServerStatus/list", { limit: 100 })));
+        admitted(admitMcpStatus(await launched.rpc("mcpServerStatus/list", { limit: 100 })), state);
     }
     state.identity = {
         requestedModel: request.model,

package/dist/actors/codex/restricted-participant.d.ts

@@ -35,6 +35,10 @@ export interface ParticipantReadiness {
     protocolIncompatibilities?: readonly string[];
     /** Schema values beyond the baseline, recorded by a launch that passed. */
     protocolAdditions?: readonly string[];
+    /** What in the operator's Codex setup the launch refused, without paths or values. */
+    refusalReason?: string;
+    /** The instruction file names Codex added from the operator's Codex home. */
+    operatorInstructionFiles?: readonly string[];
     /** The model thread/start resolved from the operator's configuration or the declared model. */
     resolvedModel?: string;
     authentication?: "chatgpt-account" | "api-key";

package/dist/actors/codex/restricted-participant.js

@@ -7,6 +7,7 @@ import { resolveWaitSettings } from "../computer-use/wait.js";
 import { createRestrictedCodexSession, } from "./restricted-session.js";
 import { PARTICIPANT_PROFILE, PARTICIPANT_LIMITS as L, PARTICIPANT_FINAL_SCHEMA, participantToolSchema, parseParticipantTool, parseParticipantFinal, } from "./restricted-participant-policy.js";
 import { truncatedFrameWarning, unknownNotificationsWarning } from "./restricted-notifications.js";
+import { operatorInstructionsWarning } from "./operator-instructions.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage } from "./protocol-compat.js";
 const codeOf = (code) => {
     if (code === "cancelled" || code === "timeout" || code === "refusal")
@@ -236,6 +237,10 @@ export async function checkRestrictedCodexParticipantReadiness(options) {
         ...(session.protocolAdditions === undefined || session.protocolAdditions.length === 0
             ? {}
             : { protocolAdditions: session.protocolAdditions }),
+        ...(session.refusalReason === undefined ? {} : { refusalReason: session.refusalReason }),
+        ...(session.operatorInstructionFiles === undefined
+            ? {}
+            : { operatorInstructionFiles: session.operatorInstructionFiles }),
         ...(session.resolvedModel === undefined ? {} : { resolvedModel: session.resolvedModel }),
         ...(session.authentication === undefined ? {} : { authentication: session.authentication }),
     };
@@ -298,6 +303,10 @@ function sessionReport(session, operator) {
             ? undefined
             : protocolIncompatibilityMessage(session.cliVersion, session.protocolIncompatibilities),
         protocolAdditionsWarning(session.cliVersion, session.protocolAdditions),
+        session.refusalReason === undefined
+            ? undefined
+            : `humanish stopped the Codex launch because ${session.refusalReason}.`,
+        operatorInstructionsWarning(session.operatorInstructionFiles),
         unknownNotificationsWarning(session.unknownNotifications, session.cliVersion),
         truncatedFrameWarning(session.truncatedFrameBytes),
     ].filter((warning) => warning !== undefined);

package/dist/actors/codex/restricted-policy.d.ts

@@ -64,8 +64,11 @@ export declare function restrictedCodexConfig(model: string | undefined, mode?:
     toml: string;
     overrides: Record<string, unknown>;
 };
-/** Inspect before thread/start, which could otherwise start inherited integrations. */
-export declare function admitsRestrictedCodexConfig(raw: unknown, configPath: string, model: string | undefined, mode?: RestrictedCodexConfigMode): boolean;
+/**
+ * Inspect before thread/start, which could otherwise start inherited integrations. Returns the
+ * first setting that does not match, named by its config key and never by its value, or null.
+ */
+export declare function restrictedCodexConfigViolation(raw: unknown, configPath: string, model: string | undefined, mode?: RestrictedCodexConfigMode): string | null;
 export declare function admitsRestrictedCodexThread(raw: unknown, model: string, cwd: string, reasoningEffort: ReasoningEffort, cliVersion: string): boolean;
 export declare function restrictedCodexRequestError(request: RestrictedCodexRequest, operatorParticipant?: boolean): RestrictedCodexAnalysisErrorCode | null;
 export declare function restrictedCodexUsage(raw: unknown): RestrictedCodexUsage | null;

package/dist/actors/codex/restricted-policy.js

@@ -98,11 +98,14 @@ max_depth = 1
 `;
     return { toml, overrides };
 }
-/** Inspect before thread/start, which could otherwise start inherited integrations. */
-export function admitsRestrictedCodexConfig(raw, configPath, model, mode = {}) {
+/**
+ * Inspect before thread/start, which could otherwise start inherited integrations. Returns the
+ * first setting that does not match, named by its config key and never by its value, or null.
+ */
+export function restrictedCodexConfigViolation(raw, configPath, model, mode = {}) {
     const root = codexRecord(raw), config = codexRecord(root.config), features = codexRecord(config.features);
     if (!Array.isArray(root.layers) || root.layers.length === 0)
-        return false;
+        return "config/read reported no config layers";
     if (!mode.operatorAuth) {
         let ownLayer = false;
         for (const rawLayer of root.layers) {
@@ -112,14 +115,14 @@ export function admitsRestrictedCodexConfig(raw, configPath, model, mode = {}) {
                 name.profile === null &&
                 (layer.disabledReason === null || layer.disabledReason === undefined)) {
                 if (ownLayer)
-                    return false;
+                    return "humanish's config layer appears twice";
                 ownLayer = true;
             }
             else if (name.type !== "system" || !empty(layer.config))
-                return false;
+                return `a ${String(name.type)} config layer is active`;
         }
         if (!ownLayer)
-            return false;
+            return "humanish's config layer is missing";
     }
     const reasoningEffort = mode.reasoningEffort ?? "low", codeMode = mode.participantCodeMode === true;
     const inheritedModel = config.model;
@@ -130,77 +133,92 @@ export function admitsRestrictedCodexConfig(raw, configPath, model, mode = {}) {
                 inheritedModel.length > 0 &&
                 inheritedModel.length <= 200)
         : inheritedModel === model;
-    if (!modelAdmitted ||
-        config.model_provider !== "openai" ||
-        config.model_reasoning_effort !== reasoningEffort ||
-        (!mode.operatorAuth && config.forced_login_method !== "chatgpt") ||
-        config.sandbox_mode !== "read-only" ||
-        config.approval_policy !== "never" ||
-        config.project_doc_max_bytes !== 0 ||
-        config.web_search !== "disabled" ||
-        features.skip_host_skill_discovery !== true ||
-        codexRecord(config.history).persistence !== "none" ||
-        codexRecord(config.analytics).enabled !== false ||
-        disabledFeatures.some((name) => features[name] !== false) ||
-        codeModeFeatures.some((name) => features[name] !== codeMode))
-        return false;
     const agents = codexRecord(config.agents), skills = codexRecord(config.skills);
-    if (agents.enabled !== false ||
-        agents.max_concurrent_threads_per_session !== 1 ||
-        agents.max_depth !== 1 ||
-        codexRecord(skills.bundled).enabled !== false ||
-        Object.keys(skills).some((key) => key !== "bundled"))
-        return false;
+    const pinned = [
+        ["model", modelAdmitted],
+        ["model_provider", config.model_provider === "openai"],
+        ["model_reasoning_effort", config.model_reasoning_effort === reasoningEffort],
+        ["forced_login_method", mode.operatorAuth === true || config.forced_login_method === "chatgpt"],
+        ["sandbox_mode", config.sandbox_mode === "read-only"],
+        ["approval_policy", config.approval_policy === "never"],
+        ["project_doc_max_bytes", config.project_doc_max_bytes === 0],
+        ["web_search", config.web_search === "disabled"],
+        ["features.skip_host_skill_discovery", features.skip_host_skill_discovery === true],
+        ["history.persistence", codexRecord(config.history).persistence === "none"],
+        ["analytics.enabled", codexRecord(config.analytics).enabled === false],
+        ...disabledFeatures.map((name) => [
+            `features.${name}`,
+            features[name] === false,
+        ]),
+        ...codeModeFeatures.map((name) => [
+            `features.${name}`,
+            features[name] === codeMode,
+        ]),
+        ["agents.enabled", agents.enabled === false],
+        ["agents.max_threads", agents.max_concurrent_threads_per_session === 1],
+        ["agents.max_depth", agents.max_depth === 1],
+        ["skills.bundled.enabled", codexRecord(skills.bundled).enabled === false],
+    ];
+    const mismatch = pinned.find(([, ok]) => !ok)?.[0];
+    if (mismatch !== undefined)
+        return `${mismatch} is not the value humanish sets`;
+    const extraSkills = Object.keys(skills).find((key) => key !== "bundled");
+    if (extraSkills !== undefined)
+        return `skills.${extraSkills} is set`;
     if (!mode.operatorAuth) {
-        for (const key of [
-            "mcp_servers",
-            "plugins",
-            "hooks",
-            "notify",
-            "instructions",
-            "developer_instructions",
-            "permissions",
-            "profiles",
-            "projects",
-            "model_providers",
-            "experimental_compact_prompt_file",
-            "experimental_model_instructions_file",
-            "model_instructions_file",
-            "model_catalog_json",
-            "openai_base_url",
-            "orchestrator",
-            "experimental_thread_store",
-            "experimental_thread_store_endpoint",
-            "experimental_realtime_ws_base_url",
-            "experimental_realtime_webrtc_call_base_url",
-            "forced_chatgpt_workspace_id",
-            "log_dir",
-            "sqlite_home",
-            "otel",
-            "marketplaces",
-            "js_repl_node_path",
-            "js_repl_node_module_dirs",
-            "responses_api_metadata",
-            "compact_prompt",
-            "profile",
-            "default_permissions",
-            "auto_review",
-            "apps",
-            "browser_use",
-            "computer_use",
-            "desktop",
-            "memories",
-            "realtime",
-        ])
-            if (!empty(config[key]))
-                return false;
+        const inherited = isolatedUnsetKeys.find((key) => !empty(config[key]));
+        if (inherited !== undefined)
+            return `${inherited} is set`;
         if (Object.values(codexRecord(config.shell_environment_policy)).some((value) => !empty(value)))
-            return false;
+            return "shell_environment_policy is set";
+        if (config.cli_auth_credentials_store !== "file")
+            return "cli_auth_credentials_store is not file";
+        if (config.chatgpt_base_url !== "https://chatgpt.com/backend-api/")
+            return "chatgpt_base_url is not the ChatGPT backend";
     }
-    return (mode.operatorAuth ||
-        (config.cli_auth_credentials_store === "file" &&
-            config.chatgpt_base_url === "https://chatgpt.com/backend-api/"));
+    return null;
 }
+/** Settings an isolated launch requires to be unset: each could add tools, instructions or egress. */
+const isolatedUnsetKeys = [
+    "mcp_servers",
+    "plugins",
+    "hooks",
+    "notify",
+    "instructions",
+    "developer_instructions",
+    "permissions",
+    "profiles",
+    "projects",
+    "model_providers",
+    "experimental_compact_prompt_file",
+    "experimental_model_instructions_file",
+    "model_instructions_file",
+    "model_catalog_json",
+    "openai_base_url",
+    "orchestrator",
+    "experimental_thread_store",
+    "experimental_thread_store_endpoint",
+    "experimental_realtime_ws_base_url",
+    "experimental_realtime_webrtc_call_base_url",
+    "forced_chatgpt_workspace_id",
+    "log_dir",
+    "sqlite_home",
+    "otel",
+    "marketplaces",
+    "js_repl_node_path",
+    "js_repl_node_module_dirs",
+    "responses_api_metadata",
+    "compact_prompt",
+    "profile",
+    "default_permissions",
+    "auto_review",
+    "apps",
+    "browser_use",
+    "computer_use",
+    "desktop",
+    "memories",
+    "realtime",
+];
 export function admitsRestrictedCodexThread(raw, model, cwd, reasoningEffort, cliVersion) {
     const value = codexRecord(raw), thread = codexRecord(value.thread), sandbox = codexRecord(value.sandbox);
     return (typeof thread.id === "string" &&

package/dist/actors/codex/restricted-session.d.ts

@@ -53,6 +53,10 @@ export interface RestrictedCodexSession {
     readonly protocolIncompatibilities?: readonly string[] | undefined;
     /** Schema values beyond the baseline humanish knows, recorded at launch. */
     readonly protocolAdditions?: readonly string[] | undefined;
+    /** What in the operator's Codex setup the launch refused, without paths or values. */
+    readonly refusalReason?: string | undefined;
+    /** The instruction file names Codex added from the operator's Codex home. */
+    readonly operatorInstructionFiles?: readonly string[] | undefined;
     run(request: RestrictedCodexRequest, readinessOnly?: boolean): Promise<RestrictedCodexResult>;
     close(): Promise<boolean>;
 }

package/dist/actors/codex/restricted-session.js

@@ -356,6 +356,8 @@ export function createRestrictedCodexSession(options = {}) {
         unknownNotifications: new Map(),
         protocolIncompatibilities: undefined,
         protocolAdditions: undefined,
+        refusalReason: undefined,
+        operatorInstructionFiles: undefined,
         activeDeadline: undefined,
         interrupt: undefined,
         closed: false,
@@ -399,6 +401,12 @@ export function createRestrictedCodexSession(options = {}) {
         get protocolAdditions() {
             return state.protocolAdditions;
         },
+        get refusalReason() {
+            return state.refusalReason;
+        },
+        get operatorInstructionFiles() {
+            return state.operatorInstructionFiles;
+        },
         run(request, readinessOnly = false) {
             const refusal = refusedRun(settings, state, request, () => pending !== undefined);
             if (refusal)

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

@@ -15,7 +15,10 @@ export declare function describeSubjectState(state: RunSubjectProvenance["state"
 /** Human-readable provenance line for the single-participant subject.provenance event of a clone
  *  or local-tree subject: claims "cloned/packed and served" only when it actually happened. */
 export declare function subjectProvenanceMessage(provenance: RunSubjectProvenance, publicAppUrl: string, dryRun: boolean, hasSession: boolean): string;
+/** The label a run records for the desktop `execution.target` names. */
+export declare function desktopSubstrate(target: string | undefined): "local-desktop" | "modal-desktop" | "e2b-desktop";
 export declare function providerResourcesForOutcome(args: {
+    provider: "e2b-desktop" | "modal-desktop";
     outcome: ParticipantRunOutcome | undefined;
     createdAt: string;
     ids: ParticipantIds;

package/dist/routes/computer-use/bundle-parts.js

@@ -73,6 +73,14 @@ export function subjectProvenanceMessage(provenance, publicAppUrl, dryRun, hasSe
     }
     return "Subject local-tree packing attempted; archive digest unresolved (provisioning failed before resolution)";
 }
+/** The label a run records for the desktop `execution.target` names. */
+export function desktopSubstrate(target) {
+    return target === "local"
+        ? "local-desktop"
+        : target === "modal-desktop"
+            ? "modal-desktop"
+            : "e2b-desktop";
+}
 export function providerResourcesForOutcome(args) {
     if (args.outcome?.sandboxId === undefined) {
         return [];
@@ -80,7 +88,7 @@ export function providerResourcesForOutcome(args) {
     return [
         {
             schema: "humanish.provider-resource.v1",
-            provider: "e2b-desktop",
+            provider: args.provider,
             kind: "sandbox",
             id: args.outcome.sandboxId,
             owner: "humanish",

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

@@ -6,7 +6,7 @@ import { judgeOneParticipant, judgeParticipants } from "../../run/judge.js";
 import { renderReviewMarkdown } from "../../run/review-markdown.js";
 import { desktopSpanToMinutes } from "../../run/cost-summary.js";
 import { e2bDesktopTemplate } from "../../substrates/e2b/sandbox.js";
-import { providerResourcesForOutcome } from "./bundle-parts.js";
+import { desktopSubstrate, providerResourcesForOutcome } from "./bundle-parts.js";
 import { participantFactsOf } from "./participant-facts.js";
 import { buildCuaFanoutBundle } from "./fanout-bundle.js";
 import { buildSingleParticipantBundle } from "./single-bundle.js";
@@ -96,9 +96,7 @@ function singleParticipantArgs(base, state) {
         desktopRoute: base.plan.runner.desktop !== "in-process",
         substrate: base.plan.runner.desktop === "in-process"
             ? "local-filesystem"
-            : plan.residual.execution?.target === "local"
-                ? "local-desktop"
-                : "e2b-desktop",
+            : desktopSubstrate(plan.residual.execution?.target),
         ...(outcome?.desktopGeometry === undefined ? {} : { desktopGeometry: outcome.desktopGeometry }),
         ...(outcome?.recording === undefined ? {} : { recording: outcome.recording }),
         ...(outcome?.networkLog === undefined ? {} : { network: outcome.networkLog }),
@@ -127,6 +125,7 @@ function singleParticipantArgs(base, state) {
         ...(desktopTemplate === undefined ? {} : { desktopTemplate }),
         ...(outcome?.desktopBrowser === undefined ? {} : { desktopBrowser: outcome.desktopBrowser }),
         providerResources: providerResourcesForOutcome({
+            provider: base.plan.residual.execution?.target === "modal-desktop" ? "modal-desktop" : "e2b-desktop",
             outcome,
             createdAt: base.run.createdAt,
             ids: spec,

package/dist/routes/computer-use/e2b-desktop/prepare.js

@@ -11,6 +11,7 @@ import { observeDesktopResources } from "../../../substrates/e2b/desktop-resourc
 import { acquireE2BDesktopSandbox, e2bDesktopTemplate, withOneRetryOnTransientE2BError, } from "../../../substrates/e2b/sandbox.js";
 import { loadE2BDesktopModule } from "../../../substrates/e2b/sdk.js";
 import { e2bShell } from "../../../substrates/e2b/shell.js";
+import { loadModalDesktopModule } from "../../../substrates/modal/sandbox.js";
 import { attachReceivingInbox, participantCommsEnv, startCommsCatch } from "./comms.js";
 import { participantSubjectEnv } from "../types.js";
 import { plural } from "../../../run/text.js";
@@ -30,11 +31,14 @@ export async function acquireParticipantDesktop(ctx, state) {
     // Off-app comms: the base-URL env is injected at sandbox create, so the app reads it at
     // boot; the catch starts right after create.
     const commsEnv = participantCommsEnv(ctx.comms);
-    const desktopModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
+    const provider = deps.sandboxProvider ?? "e2b";
+    const desktopModule = await (deps.desktopModule ??
+        (provider === "modal" ? () => loadModalDesktopModule(env) : loadE2BDesktopModule))();
     // An explicit template wins. Speech gets the versioned media image; ordinary
-    // browser studies retain the SDK default desktop.
+    // browser studies retain the SDK default desktop. A Modal desktop has one image.
     const acquired = await acquireE2BDesktopSandbox({
         module: desktopModule,
+        provider,
         options: {
             apiKey: deps.e2bApiKey,
             requestTimeoutMs: deps.requestTimeoutMs,
@@ -67,7 +71,7 @@ export async function acquireParticipantDesktop(ctx, state) {
             dpi: 96,
             lifecycle: { onTimeout: "kill" },
         },
-        template: e2bDesktopTemplate(residual),
+        template: provider === "modal" ? undefined : e2bDesktopTemplate(residual),
         retry: {
             // The default loader reclaims an acquired handle before retrying failed desktop startup.
             // Its error names the cleanup outcome; pre-construction allocation failures remain unowned.
@@ -92,7 +96,7 @@ export async function acquireParticipantDesktop(ctx, state) {
     state.sandboxId = acquired.allocation.resourceId;
     // The billed span starts the instant the sandbox exists.
     state.sandboxCreatedAtMs = deps.now();
-    const desktopResources = await observeDesktopResources(desktop);
+    const desktopResources = await observeDesktopResources(desktop, undefined, provider === "modal" ? "modal.create" : "e2b.getInfo");
     state.desktopResources = desktopResources;
     if ("reason" in desktopResources) {
         warnings.push(`Desktop resource size unavailable (${desktopResources.reason}); compute cost remains unpriced.`);

package/dist/routes/computer-use/fanout-bundle.js

@@ -5,7 +5,7 @@ import { cuaGoalSource } from "../../actors/goal-source.js";
 import { redactEncodedText } from "../../evidence/encoded-text.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, gapsListClause, skippedSentence, withCuaReviewProvenance, } from "../../run/outcomes.js";
-import { providerResourcesForOutcome, publicSafeAppUrlLabel, streakGaps } from "./bundle-parts.js";
+import { desktopSubstrate, providerResourcesForOutcome, publicSafeAppUrlLabel, streakGaps, } from "./bundle-parts.js";
 import { subjectName } from "../../run/subject-name.js";
 import { participantFeedbackCandidates } from "./participant-feedback.js";
 import { participantFactsOf } from "./participant-facts.js";
@@ -179,7 +179,7 @@ function fanoutFeedbackCandidates(args) {
             runId: args.run.runId,
             scenarioId: `cua-${plan.studyId}`,
             adapterId: plan.studyId,
-            substrate: plan.residual.execution?.target === "local" ? "local-desktop" : "e2b-desktop",
+            substrate: desktopSubstrate(plan.residual.execution?.target),
             participants: specs.map((spec, index) => {
                 const outcome = outcomes?.[index];
                 return {
@@ -241,6 +241,7 @@ export function buildCuaFanoutBundle(args) {
     const desktopTemplate = e2bDesktopTemplate(plan.residual);
     const desktopBrowser = fanoutDesktopBrowser(args);
     const providerResources = (outcomes ?? []).flatMap((outcome) => providerResourcesForOutcome({
+        provider: plan.residual.execution?.target === "modal-desktop" ? "modal-desktop" : "e2b-desktop",
         outcome,
         createdAt: args.run.createdAt,
         ids: outcome.spec,