humanish 0.115.0 → 0.117.0

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,16 +48,12 @@ 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. */
     wait(ms: number): Promise<void> | void;
 }
 export interface E2BDesktopExecutorOptions {
-    /** Fallback wait when a wait action carries no ms. Default 500. */
-    defaultWaitMs?: number;
     /**
      * Pixels of CuaAction scroll dy per one SDK scroll tick. The executor maps
      * abs(dy) / scrollAmountPerTick to the SDK's integer `amount` (floored at 1 for

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";
-const DEFAULT_WAIT_MS = 500;
+import { CUA_WAIT_LIMITS } from "../../actors/computer-use/wait.js";
+import { xdotoolChord, xdotoolHeldModifiers } from "../../guest/desktop-keys.js";
 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.
@@ -145,7 +145,6 @@ async function typeText(desktop, text) {
  * screenshot or action is ever logged.
  */
 export function createE2BDesktopExecutor(desktop, options = {}) {
-    const defaultWaitMs = options.defaultWaitMs ?? DEFAULT_WAIT_MS;
     const scrollAmountPerTick = options.scrollAmountPerTick ?? DEFAULT_SCROLL_AMOUNT_PER_TICK;
     return {
         async observe() {
@@ -234,11 +233,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
@@ -254,7 +257,8 @@ export function createE2BDesktopExecutor(desktop, options = {}) {
                 return;
             }
             case "wait":
-                await desktop.wait(action.ms ?? defaultWaitMs);
+                // The loop sends every wait with its length; planWait owns the lengths.
+                await desktop.wait(action.ms ?? CUA_WAIT_LIMITS.settleMs);
                 return;
             case "screenshot":
                 // No-op: the loop calls observe() separately to capture each frame, so
@@ -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,

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

@@ -15,18 +15,14 @@ export interface E2BDesktopModule {
          * killed, false otherwise (the SDK's own doc comment). This boolean is the primary by-id
          * cleanup proof: a caller never needs to re-list to confirm reclamation.
          */
-        kill?(sandboxId: string, options?: {
-            requestTimeoutMs?: number;
-        }): Promise<boolean>;
+        kill?(sandboxId: string, options?: E2BRequestOptions): Promise<boolean>;
         /**
          * Fetch one sandbox by its exact id (never account-wide). Throws a SandboxNotFoundError-
          * shaped error (see isSandboxNotFoundError below) when the id no longer exists; that thrown
          * error is the by-id confirmation that a killed sandbox is gone. Optional: older SDKs may
          * lack it, so callers fall back to kill()'s own boolean rather than ever calling Sandbox.list.
          */
-        getInfo?(sandboxId: string, options?: {
-            requestTimeoutMs?: number;
-        }): Promise<E2BSandboxInfo>;
+        getInfo?(sandboxId: string, options?: E2BRequestOptions): Promise<E2BSandboxInfo>;
         /**
          * List sandboxes whose metadata matches every `query.metadata` pair, filtered server-side.
          * Reclaim calls it only with a run's owner tags (sandboxOwnerTags in src/run/sandbox-creates.ts)
@@ -36,12 +32,23 @@ export interface E2BDesktopModule {
         list?(options?: E2BSandboxListOptions): E2BSandboxPaginator;
     };
 }
-interface E2BSandboxListOptions {
+/**
+ * Which E2B account a call reaches. The SDK reads E2B_API_KEY and E2B_DOMAIN from process.env for
+ * a call that names neither, and an empty value counts as none.
+ */
+export interface E2BConnection {
+    apiKey?: string;
+    domain?: string;
+}
+/** The options of a call on a sandbox that exists: its account, and how long the request may take. */
+interface E2BRequestOptions extends E2BConnection {
+    requestTimeoutMs?: number;
+}
+interface E2BSandboxListOptions extends E2BRequestOptions {
     query?: {
         metadata?: Record<string, string>;
     };
     limit?: number;
-    requestTimeoutMs?: number;
 }
 interface E2BSandboxPaginator {
     readonly hasNext: boolean;
@@ -78,7 +85,11 @@ export interface E2BNetworkOptions {
         };
     }[]>;
 }
-export interface E2BDesktopCreateOptions {
+/**
+ * A create names its account. e2bAccount (connection.ts) gives every later call on the sandbox the
+ * same one.
+ */
+export interface E2BDesktopCreateOptions extends E2BConnection {
     apiKey: string;
     dpi?: number;
     envs?: Record<string, string>;

package/dist/substrates/local/capacity.d.ts

@@ -53,8 +53,23 @@ export declare function localCapacity(host: LocalCapacity["host"], size: Machine
 }): LocalCapacity;
 /** This machine's memory and CPUs, or the size a test passes in. */
 export declare function machineSize(machine?: MachineSize): MachineSize;
-/** A new VM's size: room for four desktops, capped at half the Mac's memory and CPUs. */
-export declare function defaultVmSize(mac: MachineSize): VmSize;
+/** The humanish Lima VM as `limactl list` shows it: whether it exists, and its size when listed. */
+interface LimaVmListing {
+    readonly exists: boolean;
+    readonly size?: MachineSize;
+}
+/**
+ * The humanish Lima VM's memory and CPUs: the size Lima lists for it, or for a VM that does not
+ * exist yet, the size setup creates (room for four desktops, capped at half the Mac's memory and
+ * CPUs). Undefined for an existing VM that lists no size: Lima omits the memory it cannot parse,
+ * and a default in its place would be a guess.
+ */
+export declare function limaVmSize(vm: LimaVmListing, mac: MachineSize): VmSize | undefined;
+/**
+ * Desktops the humanish Lima VM holds, or will hold once setup creates it. Undefined when its size
+ * is unknown.
+ */
+export declare function limaCapacity(vm: LimaVmListing, mac: MachineSize): LocalCapacity | undefined;
 /**
  * Why a VM size the user asked for cannot work, or undefined: it must hold at least one desktop
  * and fit within the Mac.
@@ -73,3 +88,4 @@ export declare function capacityShortfall(capacity: LocalCapacity, needed: numbe
 } | undefined;
 /** What a participant whose desktop Docker killed for memory is told, with what to change. */
 export declare function outOfMemoryMessage(host: LocalCapacity["host"]): string;
+export {};

package/dist/substrates/local/capacity.js

@@ -50,14 +50,33 @@ function vmSizeFor(desktops) {
 export function machineSize(machine) {
     return machine ?? { memoryBytes: totalmem(), cpus: availableParallelism() };
 }
-/** A new VM's size: room for four desktops, capped at half the Mac's memory and CPUs. */
-export function defaultVmSize(mac) {
+/**
+ * The humanish Lima VM's memory and CPUs: the size Lima lists for it, or for a VM that does not
+ * exist yet, the size setup creates (room for four desktops, capped at half the Mac's memory and
+ * CPUs). Undefined for an existing VM that lists no size: Lima omits the memory it cannot parse,
+ * and a default in its place would be a guess.
+ */
+export function limaVmSize(vm, mac) {
+    if (vm.size !== undefined)
+        return { memoryGiB: vm.size.memoryBytes / GiB, cpus: vm.size.cpus };
+    if (vm.exists)
+        return undefined;
     const wanted = vmSizeFor(DEFAULT_VM_DESKTOPS);
     return {
         memoryGiB: Math.min(wanted.memoryGiB, Math.floor(mac.memoryBytes / GiB / 2)),
         cpus: Math.min(wanted.cpus, Math.floor(mac.cpus / 2)),
     };
 }
+/**
+ * Desktops the humanish Lima VM holds, or will hold once setup creates it. Undefined when its size
+ * is unknown.
+ */
+export function limaCapacity(vm, mac) {
+    const size = limaVmSize(vm, mac);
+    if (size === undefined)
+        return undefined;
+    return localCapacity("lima-vm", { memoryBytes: size.memoryGiB * GiB, cpus: size.cpus }, { planned: !vm.exists, machine: mac });
+}
 /**
  * Why a VM size the user asked for cannot work, or undefined: it must hold at least one desktop
  * and fit within the Mac.

package/dist/substrates/local/runtime-host.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { cli } from "../../cli/invocation.js";
-import { defaultVmSize, machineSize, vmSizeProblem, } from "./capacity.js";
+import { limaVmSize, machineSize, vmSizeProblem, } from "./capacity.js";
 import { plural } from "../../run/text.js";
 const exec = promisify(execFile);
 export const LIMA_INSTANCE = "humanish-runtime";
@@ -124,22 +124,18 @@ export async function limaStatus(options = {}) {
 export async function prepareLima(options = {}, progress) {
     const status = await limaStatus(options);
     const mac = machineSize(options.machine);
-    const current = status.size === undefined
-        ? defaultVmSize(mac)
-        : { memoryGiB: status.size.memoryBytes / 1024 ** 3, cpus: status.size.cpus };
-    const size = { ...current, ...options.size };
+    const current = limaVmSize(status, mac);
     if (options.size !== undefined) {
+        const size = sizeToApply(current, options.size);
         const problem = vmSizeProblem(size, mac);
         if (problem !== undefined)
             throw new Error(problem);
-    }
-    // An existing VM whose size Lima did not list gets the asked-for size without a comparison.
-    const differs = status.size === undefined
-        ? options.size !== undefined
-        : size.cpus !== current.cpus || size.memoryGiB !== current.memoryGiB;
-    if (status.exists && differs) {
-        await resizeLima(size, status.ready, options, progress);
-        return;
+        // An existing VM whose size Lima did not list gets the asked-for size without a comparison.
+        const differs = current === undefined || size.cpus !== current.cpus || size.memoryGiB !== current.memoryGiB;
+        if (status.exists && differs) {
+            await resizeLima(size, status.ready, options, progress);
+            return;
+        }
     }
     if (status.ready)
         return;
@@ -153,7 +149,7 @@ export async function prepareLima(options = {}, progress) {
         const work = await mkdtemp(path.join(tmpdir(), "humanish-lima-"));
         try {
             const file = path.join(work, "host.yaml");
-            await writeFile(file, limaTemplate(size), { mode: 0o600 });
+            await writeFile(file, limaTemplate(sizeToApply(current, options.size)), { mode: 0o600 });
             await hostExec("limactl", ["start", "--tty=false", "--name", LIMA_INSTANCE, file], options, 15 * 60_000);
         }
         finally {
@@ -161,6 +157,17 @@ export async function prepareLima(options = {}, progress) {
         }
     }
 }
+/**
+ * The size to create or resize the VM at: the asked-for values over the VM's current size. Only an
+ * existing VM that lists no size has no current size, so there a value not asked for is unknown.
+ */
+function sizeToApply(current, asked = {}) {
+    const memoryGiB = asked.memoryGiB ?? current?.memoryGiB;
+    const cpus = asked.cpus ?? current?.cpus;
+    if (memoryGiB === undefined || cpus === undefined)
+        throw new Error(`limactl lists no size for the humanish Lima VM, so humanish cannot tell which ${memoryGiB === undefined ? "--memory" : "--cpus"} to keep. Run ${cli("runtime setup --memory <GiB> --cpus <n>")} with both values.`);
+    return { memoryGiB, cpus };
+}
 /** Lima changes the memory and CPUs of a stopped instance only. Running desktops keep it running. */
 async function resizeLima(size, running, options, progress) {
     if (running) {

package/dist/substrates/local/runtime.js

@@ -6,24 +6,16 @@ import path from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { LOCAL_MEDIA_RUNTIME_RELEASES, LOCAL_RUNTIME_RELEASES } from "./runtime-release.js";
-import { defaultVmSize, localCapacity, machineSize, } from "./capacity.js";
+import { limaCapacity, localCapacity, machineSize, } from "./capacity.js";
 import { limaStatus, loadRuntimeArchive, prepareLima, runtimeArchitecture, runtimeDocker, runtimeExec, usesLima, } from "./runtime-host.js";
 import { cli } from "../../cli/invocation.js";
 const docker = async (args, options) => (await runtimeDocker(args, options)).stdout.trim();
 const runtimeRelease = (options) => options.release ??
     (options.media ? LOCAL_MEDIA_RUNTIME_RELEASES : LOCAL_RUNTIME_RELEASES)[runtimeArchitecture(options) ?? "amd64"];
-/** Desktops the existing Lima VM holds, the VM setup would create, or this Linux machine. */
+/** Desktops the Lima VM holds (or setup would create), or this Linux machine. */
 function runtimeCapacity(options, lima) {
-    if (lima === undefined)
-        return localCapacity("linux-host", machineSize(options.machine));
     const machine = machineSize(options.machine);
-    if (lima.size !== undefined)
-        return localCapacity("lima-vm", lima.size, { machine });
-    // An existing VM whose size Lima did not list has an unknown size, which no default replaces.
-    if (lima.exists)
-        return undefined;
-    const planned = defaultVmSize(machine);
-    return localCapacity("lima-vm", { memoryBytes: planned.memoryGiB * 1024 ** 3, cpus: planned.cpus }, { planned: true, machine });
+    return lima === undefined ? localCapacity("linux-host", machine) : limaCapacity(lima, machine);
 }
 /**
  * How many desktops the local runtime holds, read without starting anything. Undefined when the