humanish 0.114.0 → 0.116.0

package/dist/study/summary.js

@@ -7,12 +7,11 @@ import { localRuntimeStatus } from "../substrates/local/runtime.js";
 // what a stakeholder reads on the screen where they decide whether to press Start.
 //
 // Resolved analysis defaults are shown independently of declared participant caps. A cap that is not
-// declared is not "unlimited" and not "$0"; it is a line the screen does not draw.
-import { resolveStudyDryRun } from "./plan.js";
-import { routeOf } from "./plan.js";
-import { localCodexParticipantCheck, planCliRun } from "./doctor.js";
+// declared is not "unlimited" and not "$0": the screen says that no cap is set.
+import { planStudy, resolveStudyDryRun, routeOf } from "./plan.js";
+import { localCodexParticipantCheck } from "./doctor.js";
 import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
-import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
+import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
 import { inspectStudyManifest } from "./discover.js";
 import { computerUseParticipantCount, isComputerUseComposition } from "./routing.js";
@@ -70,7 +69,7 @@ function participantsOf(config) {
 /** The computer-use caps. Other routes draw none. */
 function summaryCapsOf(config) {
     if (!isComputerUseComposition(config))
-        return {};
+        return undefined;
     const caps = config.caps;
     return {
         ...(typeof caps?.maxUsd === "number" ? { laneUsd: caps.maxUsd } : {}),
@@ -89,18 +88,17 @@ export async function readStudySummary(cwd, study, options = {}) {
     const route = routeOf(inspected.config);
     let keysReady;
     let missingKeys;
-    const dryRun = resolveStudyDryRun(inspected.config, undefined, true) === true;
-    // A live key check reads the plan's requirements. A study the planner refuses has none to check,
-    // so the summary reports the refusal in place of its keys.
-    const planned = options.checkKeys === true && !dryRun ? await planCliRun(inspected.config, cwd) : undefined;
+    const mode = resolveStudyDryRun(inspected.config, undefined, true) === true ? "dry-run" : "live";
+    // The keys are the live plan's, whatever the file's mode: the screen offers a live run of every
+    // study, and a dry run needs no keys to report. A study the planner refuses live has none to
+    // check, so the summary reports the refusal in place of its keys.
+    const planned = options.checkKeys === true ? planStudy(inspected.config, { cwd, dryRun: false }) : undefined;
     const planRefusal = planned?.ok === false ? planned.refusal.message : undefined;
-    if (options.checkKeys === true && planned?.ok !== false) {
-        const requirements = planned?.planned.plan.requirements ?? [];
+    if (planned?.ok === true) {
+        const requirements = planned.planned.plan.requirements;
         const subjectKeys = requiredSubjectEnv(requirements);
         const email = inspected.config.comms?.email;
-        const receivingKey = !dryRun && email?.kind === "real"
-            ? await receivingRequiredKey(cwd, email.connection)
-            : undefined;
+        const receivingKey = email?.kind === "real" ? await receivingRequiredKey(cwd, email.connection) : undefined;
         const candidates = [
             "OPENAI_API_KEY",
             "CODEX_API_KEY",
@@ -108,13 +106,11 @@ export async function readStudySummary(cwd, study, options = {}) {
             ...subjectKeys,
             ...(receivingKey ? [receivingKey] : []),
         ];
-        const probes = dryRun
-            ? []
-            : await probeKeySources(candidates, {
-                cwd,
-                env: options.env ?? process.env,
-                ...(options.keyDeps === undefined ? {} : { deps: options.keyDeps }),
-            }).catch(() => []);
+        const probes = await probeKeySources(candidates, {
+            cwd,
+            env: options.env ?? process.env,
+            ...(options.keyDeps === undefined ? {} : { deps: options.keyDeps }),
+        }).catch(() => []);
         const present = new Set(probes.filter((probe) => probe.source !== null).map((probe) => probe.name));
         const required = requiredKeys(requirements, (name) => present.has(name));
         const missing = [
@@ -130,6 +126,7 @@ export async function readStudySummary(cwd, study, options = {}) {
     const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route, computerUseParticipantCount(inspected.config));
     const subject = subjectOf(config);
     const participants = participantsOf(inspected.config);
+    const caps = summaryCapsOf(inspected.config);
     const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)
         ? await localRuntimeStatus({
             ...(options.env ? { env: options.env } : {}),
@@ -143,7 +140,9 @@ export async function readStudySummary(cwd, study, options = {}) {
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
     return {
-        ...(analysis ? { analysis } : {}),
+        ...(analysis
+            ? { analysis: { ...analysis, line: formatAutomaticAnalysisBudget(analysis) } }
+            : {}),
         ...(runtime
             ? { runtime: { ok: runtime.ok, installed: runtime.installed, message: runtime.message } }
             : {}),
@@ -168,7 +167,8 @@ export async function readStudySummary(cwd, study, options = {}) {
         ...(participants === undefined ? {} : { participants }),
         model: inspected.config.actor?.model ?? DEFAULT_OPENAI_CU_MODEL,
         reasoningEffort: reasoningEffortOf(inspected.config),
-        caps: summaryCapsOf(inspected.config),
+        ...(caps === undefined ? {} : { caps }),
+        mode,
         ...(keysReady === undefined ? {} : { keysReady }),
         ...(missingKeys === undefined ? {} : { missingKeys }),
         ...(planRefusal === undefined ? {} : { planRefusal }),

package/dist/study/warnings.d.ts

@@ -1,5 +1,6 @@
 import type { ResolvedPersona } from "./persona.js";
 import type { StudyConfig } from "./types.js";
+import { type Participant } from "./plan-participants.js";
 /**
  * The fields a config sets that its route does not read, each as `field` or `field (reason)`.
  * parseStudy refuses a study for any of them.
@@ -10,17 +11,23 @@ export declare function inertFieldLabels(config: StudyConfig): string[];
  * `participants[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
  */
 export declare function inertFieldPaths(config: StudyConfig): string[];
+export declare function forwardDeclaredWarnings(config: StudyConfig): string[];
 /**
- * The warning for `execution.egressAllow` on a route that ignores it, or undefined. Only the
- * terminal route creates its sandbox with the list as an outbound allowlist; on any other route the
- * study author would trust a list that blocks nothing. `humanish study check` and every run print
- * it, and the run records it in its bundle.
- * Removed in the first minor release on or after 2026-11-04: deprecated on 2026-10-05. That release refuses the field off the terminal
- * route.
+ * The warnings about a study's own fields that a run records in its bundle as `study.warning`
+ * events: `execution.egressAllow` off the terminal route, and participant text that reads like a
+ * script. parseStudy reports them too, after its other warnings, so `study check` and every run
+ * print them.
  */
-export declare function egressAllowIgnoredWarning(config: StudyConfig): string | undefined;
-export declare function forwardDeclaredWarnings(config: StudyConfig): string[];
-/** Authored participant text is checked before runtime instructions or researcher criteria join it. */
-export declare function scriptedMissionWarnings(config: StudyConfig): string[];
-/** Backgrounds give participants a reason to act beyond the assigned task. */
-export declare function personaBackgroundWarnings(config: StudyConfig, personas: ReadonlyMap<string, ResolvedPersona>): string[];
+export declare function recordedStudyWarnings(config: StudyConfig): string[];
+/**
+ * A warning for each participant whose persona has no background, which gives a participant a
+ * reason to act beyond the assigned task. `participants` are the records the planner builds: a
+ * computer-use or shared-world plan's participants, or `plannedParticipants` before a plan exists.
+ */
+export declare function personaBackgroundWarnings(studyId: string, participants: readonly Pick<Participant, "id" | "personaId">[], personas: ReadonlyMap<string, ResolvedPersona>): string[];
+/**
+ * The participant records planStudy builds for a study's declared participants, for `study check`
+ * and `study show`, which run no plan. Only computer-use and shared-world studies have them; a run's
+ * `--count` is not applied.
+ */
+export declare function plannedParticipants(config: StudyConfig): readonly Participant[];

package/dist/study/warnings.js

@@ -1,5 +1,6 @@
+import { cli } from "../cli/invocation.js";
 import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
-import { declaredParticipantIds } from "./plan-participants.js";
+import { computerUseParticipants, declaredParticipantIds, sharedWorldParticipants, } from "./plan-participants.js";
 import { addressedRecipients } from "./parse/comms.js";
 import { participantList, participantInstruction, declaredParticipantCount, } from "./study-fields.js";
 // The computer-use and terminal routes consume mission/persona/model (they compose the agent prompt
@@ -268,12 +269,11 @@ export function inertFieldPaths(config) {
 /**
  * The warning for `execution.egressAllow` on a route that ignores it, or undefined. Only the
  * terminal route creates its sandbox with the list as an outbound allowlist; on any other route the
- * study author would trust a list that blocks nothing. `humanish study check` and every run print
- * it, and the run records it in its bundle.
+ * study author would trust a list that blocks nothing.
  * Removed in the first minor release on or after 2026-11-04: deprecated on 2026-10-05. That release refuses the field off the terminal
  * route.
  */
-export function egressAllowIgnoredWarning(config) {
+function egressAllowIgnoredWarning(config) {
     if (config.execution?.egressAllow === undefined || config.route === "terminal")
         return undefined;
     return `\`execution.egressAllow\` is ignored on route: ${config.route}. Only route: terminal creates its sandbox with that outbound allowlist, and this route's browser desktops can reach any site. Remove the field: the first minor release on or after 2026-11-04 refuses it on every route except terminal.`;
@@ -288,9 +288,6 @@ export function forwardDeclaredWarnings(config) {
         : [
             `These fields are set, but no route reads them yet, so they have no effect: ${inert.join(", ")}.`,
         ];
-    const egressIgnored = egressAllowIgnoredWarning(config);
-    if (egressIgnored !== undefined)
-        warnings.push(egressIgnored);
     // A declared cap below the participant count is legal but loud: the roster promises N live actors
     // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
     // waves is otherwise indistinguishable from the all-live run the author meant.
@@ -311,7 +308,20 @@ export function forwardDeclaredWarnings(config) {
             warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants. These get no inbox and are never told one exists: ${uncovered.join(", ")}. Add a recipient with an address for each one whose flow needs email.`);
         }
     }
-    return [...warnings, ...scriptedMissionWarnings(config)];
+    return [...warnings, ...recordedStudyWarnings(config)];
+}
+/**
+ * The warnings about a study's own fields that a run records in its bundle as `study.warning`
+ * events: `execution.egressAllow` off the terminal route, and participant text that reads like a
+ * script. parseStudy reports them too, after its other warnings, so `study check` and every run
+ * print them.
+ */
+export function recordedStudyWarnings(config) {
+    const egressIgnored = egressAllowIgnoredWarning(config);
+    return [
+        ...(egressIgnored === undefined ? [] : [egressIgnored]),
+        ...scriptedMissionWarnings(config),
+    ];
 }
 const UI_ACTION = /\b(?:click|tap|press|type\b[^.!?\n]*?\binto|select\b[^.!?\n]*?\bfrom)\b/gi;
 function normalizedUrl(value) {
@@ -342,7 +352,7 @@ function actionChain(text) {
             /\bthen\b/i.test(text.slice((actions[0]?.index ?? 0) + (actions[0]?.[0].length ?? 0)))));
 }
 /** Authored participant text is checked before runtime instructions or researcher criteria join it. */
-export function scriptedMissionWarnings(config) {
+function scriptedMissionWarnings(config) {
     if (config.route !== "computer-use" && config.route !== "shared-world")
         return [];
     const fields = [
@@ -373,20 +383,32 @@ export function scriptedMissionWarnings(config) {
         ];
     });
 }
-/** Backgrounds give participants a reason to act beyond the assigned task. */
-export function personaBackgroundWarnings(config, personas) {
-    if (config.route !== "computer-use" && config.route !== "shared-world")
-        return [];
-    const roster = participantList(config);
-    return declaredParticipantIds(config).flatMap((id, index) => {
-        const personaId = roster?.[index]?.persona ?? config.actor?.persona;
+/**
+ * A warning for each participant whose persona has no background, which gives a participant a
+ * reason to act beyond the assigned task. `participants` are the records the planner builds: a
+ * computer-use or shared-world plan's participants, or `plannedParticipants` before a plan exists.
+ */
+export function personaBackgroundWarnings(studyId, participants, personas) {
+    return participants.flatMap(({ id, personaId }) => {
         if (personaId && personas.get(personaId)?.background)
             return [];
         const reason = personaId
             ? `persona ${personaId} has no readable background`
             : "no persona is assigned";
         return [
-            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run humanish study show ${config.id} --json to see what the participant receives.`,
+            `Participant ${id} has no persona background because ${reason}. Add a short, fictional background describing their experience and situation. Run ${cli(`study show ${studyId} --json`)} to see what the participant receives.`,
         ];
     });
 }
+/**
+ * The participant records planStudy builds for a study's declared participants, for `study check`
+ * and `study show`, which run no plan. Only computer-use and shared-world studies have them; a run's
+ * `--count` is not applied.
+ */
+export function plannedParticipants(config) {
+    if (config.route === "computer-use")
+        return computerUseParticipants(config);
+    if (config.route === "shared-world")
+        return sharedWorldParticipants(config).participants;
+    return [];
+}

package/dist/substrates/e2b/connection.d.ts

@@ -0,0 +1,12 @@
+import type { E2BConnection, E2BDesktopModule } from "./sdk.js";
+/** The connection an env names: E2B_API_KEY and E2B_DOMAIN, trimmed, each only when set. */
+export declare function e2bConnection(env: Readonly<Record<string, string | undefined>>): E2BConnection;
+/** The calls humanish makes on sandboxes that already exist. */
+export type E2BAccount = Pick<E2BDesktopModule["Sandbox"], "kill" | "getInfo" | "list">;
+/**
+ * The kill, getInfo and list of `module`, each carrying `connection`'s key and domain over the
+ * call's own options. `connection` may be a create's options, so the release of a sandbox reaches
+ * the account that created it. Each method is bound now: a hook that later replaces one on the
+ * shared module does not change this account. A method the installed SDK lacks stays absent.
+ */
+export declare function e2bAccount(module: E2BDesktopModule, connection: E2BConnection): E2BAccount;

package/dist/substrates/e2b/connection.js

@@ -0,0 +1,35 @@
+/** The connection an env names: E2B_API_KEY and E2B_DOMAIN, trimmed, each only when set. */
+export function e2bConnection(env) {
+    return named({ apiKey: env.E2B_API_KEY?.trim(), domain: env.E2B_DOMAIN?.trim() });
+}
+/**
+ * The kill, getInfo and list of `module`, each carrying `connection`'s key and domain over the
+ * call's own options. `connection` may be a create's options, so the release of a sandbox reaches
+ * the account that created it. Each method is bound now: a hook that later replaces one on the
+ * shared module does not change this account. A method the installed SDK lacks stays absent.
+ */
+export function e2bAccount(module, connection) {
+    const sdk = module.Sandbox;
+    const reached = named(connection);
+    const account = {};
+    if (typeof sdk.kill === "function") {
+        const kill = sdk.kill.bind(sdk);
+        account.kill = (sandboxId, options) => kill(sandboxId, { ...options, ...reached });
+    }
+    if (typeof sdk.getInfo === "function") {
+        const getInfo = sdk.getInfo.bind(sdk);
+        account.getInfo = (sandboxId, options) => getInfo(sandboxId, { ...options, ...reached });
+    }
+    if (typeof sdk.list === "function") {
+        const list = sdk.list.bind(sdk);
+        account.list = (options) => list({ ...options, ...reached });
+    }
+    return account;
+}
+/** Only the key and the domain, and only when non-empty: the SDK reads an empty one as unset. */
+function named(values) {
+    return {
+        ...(values.apiKey ? { apiKey: values.apiKey } : {}),
+        ...(values.domain ? { domain: values.domain } : {}),
+    };
+}

package/dist/substrates/e2b/desktop-executor.d.ts

@@ -6,7 +6,7 @@ import type { CuaExecutor, CuaObservation } from "../../actors/computer-use/loop
  * executor awaits every call, which is correct for both sync and async returns.
  */
 export interface E2BDesktopLike {
-    /** Optional command surface used only for best-effort substrate fallbacks. */
+    /** The sandbox's command surface: keypresses, held modifiers and typed text run xdotool here. */
     commands?: {
         run(command: string, options?: {
             requestTimeoutMs?: number;
@@ -48,8 +48,6 @@ export interface E2BDesktopLike {
     scroll(direction?: "up" | "down", amount?: number): Promise<void> | void;
     /** Write text at the current cursor position (the SDK's typing method). */
     write(text: string): Promise<void> | void;
-    /** Press a key or chord (the SDK's key method); accepts the keys array. */
-    press(key: string | string[]): Promise<void> | void;
     /** Drag from one coordinate tuple to another. */
     drag(from: [number, number], to: [number, number]): Promise<void> | void;
     /** Wait for the given number of milliseconds. */

package/dist/substrates/e2b/desktop-executor.js

@@ -2,11 +2,11 @@ import { shellQuote } from "../shell.js";
 import { perceptualSignature } from "../../evidence/frame-signature.js";
 import { commandFailureInfo } from "../command-failure.js";
 import { ComputerUseExecutorError } from "../../actors/computer-use/executor-error.js";
-import { xdotoolHeldModifiers } from "../../guest/desktop-keys.js";
+import { xdotoolChord, xdotoolHeldModifiers } from "../../guest/desktop-keys.js";
 const DEFAULT_WAIT_MS = 500;
 const DEFAULT_SCROLL_AMOUNT_PER_TICK = 100;
 const TYPE_COMMAND_TIMEOUT_MS = 15_000;
-const HELD_KEYS_TIMEOUT_MS = 15_000;
+const KEY_COMMAND_TIMEOUT_MS = 15_000;
 const CURSOR_READ_TIMEOUT_MS = 500;
 /**
  * The stock image's xdotool waits ~15s on a synchronized move to its current position.
@@ -234,11 +234,15 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
                 }
                 return;
             }
-            case "keypress":
-                // The SDK press() accepts a string[] directly; pass the keys through so
-                // a chord (e.g. ["Control", "a"]) is pressed together, not in sequence.
-                await desktop.press(action.keys);
+            case "keypress": {
+                // One chord, so ctrl and a are pressed together. A name the table cannot map is
+                // refused here, before anything reaches the desktop.
+                const chord = xdotoolChord(action.keys);
+                if (!desktop.commands)
+                    throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
+                await runKeyCommand(desktop.commands, `key --clearmodifiers ${chord}`);
                 return;
+            }
             case "drag": {
                 // The SDK drag takes two endpoints, not an N-point path: drag from the
                 // first to the last point. 0 points is a safe no-op; 1 point has no
@@ -279,11 +283,10 @@ async function withHeldModifiers(desktop, chord, run) {
     const commands = desktop.commands;
     if (!commands)
         throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
-    const options = { requestTimeoutMs: HELD_KEYS_TIMEOUT_MS, timeoutMs: HELD_KEYS_TIMEOUT_MS };
     let failed = false;
     let failure;
     try {
-        await commands.run(`xdotool keydown ${chord}`, options);
+        await runKeyCommand(commands, `keydown ${chord}`);
         await run();
     }
     catch (error) {
@@ -292,7 +295,7 @@ async function withHeldModifiers(desktop, chord, run) {
     }
     // A keydown that failed may still have pressed some keys, so the release always runs.
     try {
-        await commands.run(`xdotool keyup ${chord}`, options);
+        await runKeyCommand(commands, `keyup ${chord}`);
     }
     catch {
         throw new ComputerUseExecutorError("execution_failed", "outcome_uncertain");
@@ -300,3 +303,33 @@ async function withHeldModifiers(desktop, chord, run) {
     if (failed)
         throw failure;
 }
+/**
+ * A key command xdotool did not complete. The loop reads `exitCode` and `stderr` the way it reads
+ * the SDK's CommandExitError, so it records the action as a failed desktop command and skips it.
+ */
+class ComputerUseKeyError extends Error {
+    exitCode;
+    stderr;
+    constructor(exitCode, stderr) {
+        super(`key command failed (exit ${exitCode})`);
+        this.name = "ComputerUseKeyError";
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}
+/**
+ * Run an xdotool key command: `key`, `keydown` or `keyup` with a chord from the key table, whose
+ * names are plain shell words, so the command and its stderr hold no participant text. The SDK
+ * throws its own error on a non-zero exit. xdotool skips a name it cannot resolve with a "No such
+ * key name" warning and still exits 0, so that warning fails the command too.
+ */
+async function runKeyCommand(commands, command) {
+    const result = await commands.run(`xdotool ${command}`, {
+        requestTimeoutMs: KEY_COMMAND_TIMEOUT_MS,
+        timeoutMs: KEY_COMMAND_TIMEOUT_MS,
+    });
+    const exitCode = result.exitCode ?? 0;
+    const stderr = result.stderr ?? "";
+    if (exitCode !== 0 || stderr.includes("No such key name"))
+        throw new ComputerUseKeyError(exitCode, stderr);
+}

package/dist/substrates/e2b/lifetime.d.ts

@@ -1,9 +1,29 @@
 /**
- * E2B refuses a sandbox lifetime over one hour ("400: Timeout cannot be greater than 1 hours").
- * A derived deadline has to stay under it, and saying so at plan time beats discovering it from a
- * raw provider 400 after a plan has already printed.
+ * The longest lifetime humanish asks E2B for, in milliseconds, and whether it is the default or
+ * the setting; or why the setting cannot be read.
  */
-export declare const MAX_SANDBOX_MS: number;
+export type SandboxCeiling = {
+    readonly ok: true;
+    readonly ms: number;
+    readonly source: "default" | "setting";
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * The sandbox ceiling: HUMANISH_E2B_MAX_SANDBOX_MINUTES when set, else 60 minutes. E2B refuses a
+ * longer sandbox with a 400 ("Timeout cannot be greater than 1 hours" on Hobby), and neither its
+ * API nor its SDK says which plan a key is on, so the operator states it. A derived deadline has
+ * to stay under the ceiling, and saying so at plan time beats a provider 400 after the plan printed.
+ */
+export declare function sandboxCeiling(env: Readonly<Record<string, string | undefined>>): SandboxCeiling;
+/** The ceiling in use and where it came from, or why the setting cannot be read (doctor's row). */
+export declare function describeSandboxCeiling(ceiling: SandboxCeiling): string;
+/**
+ * The sentence a plan refusal adds when a `deadlineMs` sandbox deadline passes the ceiling: the
+ * setting value that would admit it, when an E2B plan allows that long.
+ */
+export declare function ceilingAdvice(deadlineMs: number): string;
 /** Server-side reclamation buffer past a participant's own wall-clock stop. */
 export declare const SANDBOX_TIMEOUT_BUFFER_MS: number;
 /** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */

package/dist/substrates/e2b/lifetime.js

@@ -2,12 +2,49 @@
 // deadline when they set a sandbox's server-side timeout. A dead host process can never orphan a
 // sandbox past that timeout, so every route derives it from these values.
 import { readPositiveInt } from "../../study/parse/values.js";
+/** The setting that tells humanish how long the operator's E2B plan lets a sandbox live. */
+const SANDBOX_CEILING_SETTING = "HUMANISH_E2B_MAX_SANDBOX_MINUTES";
+/** E2B's Hobby plan ends a sandbox after 1 hour, so a key on any plan can use this ceiling. */
+const DEFAULT_CEILING_MINUTES = 60;
+/** E2B's Pro plan allows 24 hours, the longest lifetime E2B documents. */
+const LARGEST_CEILING_MINUTES = 24 * 60;
 /**
- * E2B refuses a sandbox lifetime over one hour ("400: Timeout cannot be greater than 1 hours").
- * A derived deadline has to stay under it, and saying so at plan time beats discovering it from a
- * raw provider 400 after a plan has already printed.
+ * The sandbox ceiling: HUMANISH_E2B_MAX_SANDBOX_MINUTES when set, else 60 minutes. E2B refuses a
+ * longer sandbox with a 400 ("Timeout cannot be greater than 1 hours" on Hobby), and neither its
+ * API nor its SDK says which plan a key is on, so the operator states it. A derived deadline has
+ * to stay under the ceiling, and saying so at plan time beats a provider 400 after the plan printed.
  */
-export const MAX_SANDBOX_MS = 60 * 60_000;
+export function sandboxCeiling(env) {
+    const declared = env[SANDBOX_CEILING_SETTING]?.trim() ?? "";
+    if (declared === "")
+        return { ok: true, ms: DEFAULT_CEILING_MINUTES * 60_000, source: "default" };
+    const minutes = /^\d+$/.test(declared) ? Number.parseInt(declared, 10) : Number.NaN;
+    if (!(minutes >= 1 && minutes <= LARGEST_CEILING_MINUTES))
+        return {
+            ok: false,
+            message: `${SANDBOX_CEILING_SETTING} must be a whole number of minutes from 1 to ${LARGEST_CEILING_MINUTES} (got "${declared.slice(0, 40)}"). Set it to the sandbox lifetime your E2B plan allows: ${DEFAULT_CEILING_MINUTES} on Hobby, ${LARGEST_CEILING_MINUTES} on Pro. Unset, it is ${DEFAULT_CEILING_MINUTES}.`,
+        };
+    return { ok: true, ms: minutes * 60_000, source: "setting" };
+}
+/** The ceiling in use and where it came from, or why the setting cannot be read (doctor's row). */
+export function describeSandboxCeiling(ceiling) {
+    if (!ceiling.ok)
+        return ceiling.message;
+    const minutes = ceiling.ms / 60_000;
+    return ceiling.source === "setting"
+        ? `${minutes} minutes, from ${SANDBOX_CEILING_SETTING}. A study whose sandbox deadline is longer is refused before any sandbox is created, and E2B refuses a lifetime past the plan's own limit.`
+        : `${minutes} minutes, E2B's Hobby limit. On a plan with longer sandboxes (Pro allows ${LARGEST_CEILING_MINUTES} minutes), set ${SANDBOX_CEILING_SETTING} to that plan's limit.`;
+}
+/**
+ * The sentence a plan refusal adds when a `deadlineMs` sandbox deadline passes the ceiling: the
+ * setting value that would admit it, when an E2B plan allows that long.
+ */
+export function ceilingAdvice(deadlineMs) {
+    const needed = Math.ceil(deadlineMs / 60_000);
+    return needed <= LARGEST_CEILING_MINUTES
+        ? ` If your E2B plan allows longer sandboxes (Pro allows ${LARGEST_CEILING_MINUTES} minutes), set ${SANDBOX_CEILING_SETTING} to ${needed} or more.`
+        : ` No E2B plan humanish knows allows a sandbox past ${LARGEST_CEILING_MINUTES} minutes.`;
+}
 /** Server-side reclamation buffer past a participant's own wall-clock stop. */
 export const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
 /** Room a provisioned subject adds to the sandbox deadline for clone, install, build, start and probe. */

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

@@ -1,6 +1,7 @@
 import type { PreparedOutputRoot } from "../../run/contained-output.js";
 import { type DesktopReleaseResult, type OwnedDesktopAllocation } from "../desktop-session.js";
 import type { StudyConfig } from "../../study/types.js";
+import { type E2BAccount } from "./connection.js";
 import { type E2BDesktopCreateOptions, type E2BDesktopModule, type E2BDesktopSandbox, type E2BListedSandbox } from "./sdk.js";
 /** Where an allocation's receipt goes: the run's prepared root, under a public-safe participant
  *  label. The receipt line saves it as `laneId`. */
@@ -59,7 +60,7 @@ export type E2BSandboxDestroyOutcome = {
 };
 /** Kill one sandbox by its exact id, for reclaim, and map the shared release result onto
  *  reclaim's persisted outcome. */
-export declare function destroyE2BSandbox(module: E2BDesktopModule, sandboxId: string, options: {
+export declare function destroyE2BSandbox(account: E2BAccount, sandboxId: string, options: {
     requestTimeoutMs: number;
 }): Promise<E2BSandboxDestroyOutcome>;
 /** What `reclaim --check` learned about one sandbox by its exact id. */
@@ -73,7 +74,7 @@ export type E2BSandboxPresence = {
  * Ask E2B whether one sandbox still exists, by exact id. A SandboxNotFoundError, recognized by
  * type, means gone; any other error leaves the answer open.
  */
-export declare function inspectE2BSandbox(module: E2BDesktopModule, sandboxId: string, options: {
+export declare function inspectE2BSandbox(account: E2BAccount, sandboxId: string, options: {
     requestTimeoutMs: number;
 }): Promise<E2BSandboxPresence>;
 /** What E2B listed for a run's owner tags. `sandboxes` holds exact matches only. */
@@ -87,7 +88,7 @@ export interface E2BTagSearch {
  * checked against every tag again, so a server that ignored the filter still cannot hand back
  * another run's sandbox, and the search stops after a few pages instead of walking the account.
  */
-export declare function findE2BSandboxesByTags(module: E2BDesktopModule, tags: Record<string, string>, options: {
+export declare function findE2BSandboxesByTags(account: E2BAccount, tags: Record<string, string>, options: {
     requestTimeoutMs: number;
 }): Promise<E2BTagSearch>;
 /** Versioned public template built by runtime/browser-media/e2b-template.mjs. */

package/dist/substrates/e2b/sandbox.js

@@ -11,6 +11,7 @@ import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { beginSandboxCreate, recordSandboxOwnerOnce, SandboxCreateRefusedError, sandboxOwnerTags, } from "../../run/sandbox-creates.js";
 import { appendSandboxOwner, appendSandboxReceipt } from "../../run/sandbox-receipts.js";
 import { ownDesktopAllocation, } from "../desktop-session.js";
+import { e2bAccount } from "./connection.js";
 import { E2B_DEBUG_KILL_DETAIL, E2BDesktopStartupError, e2bDebugMode, isSandboxNotFoundError, observeDesktopAllocation, } from "./sdk.js";
 /** A desktop sandbox, on the stock `desktop` template or a named one. */
 export function acquireE2BDesktopSandbox(request) {
@@ -67,7 +68,8 @@ async function acquire(request, template) {
                 : module.Sandbox.create(template, options);
         }, { ...request.retry, canRetry: () => ticket?.stopping() !== true });
         ticket?.created(sandbox.sandboxId);
-        const allocation = ownE2BSandbox(module, sandbox.sandboxId, ticket);
+        // The release reaches the account the create used, whatever process.env names.
+        const allocation = ownE2BSandbox(e2bAccount(module, options), sandbox.sandboxId, ticket);
         try {
             // Best effort by contract: a failed write leaves the owner tags and the TTL as the
             // backstops and never fails the participant. One line per sandbox: a receipt the guard's
@@ -90,12 +92,6 @@ async function acquire(request, template) {
         ticket?.settled();
     }
 }
-/** The provider's kill method bound to its class, or undefined when the SDK has none. */
-function boundKill(module) {
-    return typeof module.Sandbox.kill === "function"
-        ? module.Sandbox.kill.bind(module.Sandbox)
-        : undefined;
-}
 /**
  * Kill one sandbox by exact id and read the answer in the release vocabulary both callers share.
  * The SDK resolves false for an id it no longer knows (a 404), and a SandboxNotFoundError,
@@ -129,9 +125,8 @@ async function killById(kill, sandboxId, options) {
         return { status: "unconfirmed", reason: "release_failed", error };
     }
 }
-function ownE2BSandbox(module, resourceId, ticket) {
-    // Bind the provider method now, before any hook can replace it on the shared module.
-    const kill = boundKill(module);
+function ownE2BSandbox(account, resourceId, ticket) {
+    const { kill } = account;
     return ownDesktopAllocation({
         resourceId,
         release: async () => {
@@ -189,8 +184,8 @@ export function releaseUnavailableDetail(detail) {
 }
 /** Kill one sandbox by its exact id, for reclaim, and map the shared release result onto
  *  reclaim's persisted outcome. */
-export async function destroyE2BSandbox(module, sandboxId, options) {
-    const released = await killById(boundKill(module), sandboxId, options);
+export async function destroyE2BSandbox(account, sandboxId, options) {
+    const released = await killById(account.kill, sandboxId, options);
     if (released.status === "released")
         return { state: released.reason === "terminated" ? "killed" : "already-gone" };
     switch (released.reason) {
@@ -209,14 +204,14 @@ export async function destroyE2BSandbox(module, sandboxId, options) {
  * Ask E2B whether one sandbox still exists, by exact id. A SandboxNotFoundError, recognized by
  * type, means gone; any other error leaves the answer open.
  */
-export async function inspectE2BSandbox(module, sandboxId, options) {
-    if (typeof module.Sandbox.getInfo !== "function")
+export async function inspectE2BSandbox(account, sandboxId, options) {
+    if (account.getInfo === undefined)
         return {
             state: "check-failed",
             detail: "the installed @e2b/desktop SDK has no Sandbox.getInfo",
         };
     try {
-        await module.Sandbox.getInfo(sandboxId, options);
+        await account.getInfo(sandboxId, options);
         return { state: "running" };
     }
     catch (error) {
@@ -234,8 +229,8 @@ const TAG_SEARCH_MAX_PAGES = 3;
  * checked against every tag again, so a server that ignored the filter still cannot hand back
  * another run's sandbox, and the search stops after a few pages instead of walking the account.
  */
-export async function findE2BSandboxesByTags(module, tags, options) {
-    if (typeof module.Sandbox.list !== "function")
+export async function findE2BSandboxesByTags(account, tags, options) {
+    if (account.list === undefined)
         return {
             status: "unavailable",
             sandboxes: [],
@@ -243,7 +238,7 @@ export async function findE2BSandboxesByTags(module, tags, options) {
         };
     const sandboxes = [];
     try {
-        const pages = module.Sandbox.list({
+        const pages = account.list({
             query: { metadata: tags },
             limit: TAG_SEARCH_PAGE_SIZE,
             requestTimeoutMs: options.requestTimeoutMs,