humanish 0.110.0 → 0.110.2

package/dist/study/url-credentials.js

@@ -0,0 +1,34 @@
+// Every URL a study config declares, checked for a credential. Route planners call it, since a
+// library caller's config skips the parser that refuses these first.
+import { rosterOf } from "./parse/actors.js";
+import { entryCredentialReason, urlCredentialReason } from "./parse/url-credentials.js";
+/**
+ * The first URL in `config` that carries a credential, with why: the subject's app, serve and
+ * public surface URLs, and each participant's target and entry.
+ */
+export function studyUrlCredentialReason(config) {
+    const { subject } = config;
+    const reasons = [
+        () => subject.appUrl === undefined
+            ? undefined
+            : urlCredentialReason("subject.appUrl", subject.appUrl),
+        () => subject.serve === undefined
+            ? undefined
+            : urlCredentialReason("subject.serve.url", subject.serve.url),
+        ...(subject.product?.publicSurfaces ?? []).map((surface) => () => urlCredentialReason("subject.product.publicSurfaces", surface)),
+        ...config.actors.flatMap((actor) => (rosterOf(actor) ?? []).flatMap((participant, index) => [
+            () => participant.target === undefined
+                ? undefined
+                : urlCredentialReason(`participants[${index}].target`, participant.target),
+            () => participant.entry === undefined
+                ? undefined
+                : entryCredentialReason(`participants[${index}].entry`, participant.entry),
+        ])),
+    ];
+    for (const reason of reasons) {
+        const found = reason();
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}

package/dist/substrates/e2b/peer-install.d.ts

@@ -0,0 +1,51 @@
+type Manager = "npm" | "pnpm";
+/** Where the running humanish is installed, read from its own file's real path. */
+export type HumanishInstall = 
+/** The nearest package.json declaring humanish: the working directory's, or `up` levels above. */
+{
+    kind: "project";
+    up: number;
+    manager: Manager;
+}
+/** A one-shot runner's cache: `npx humanish` or `pnpm dlx humanish`. */
+ | {
+    kind: "one-shot";
+    unmanagedCwd: boolean;
+}
+/** The global directory npm installs to from here, or pnpm's global directory. */
+ | {
+    kind: "global";
+    manager: Manager;
+}
+/** A source checkout of humanish, run with node or tsx. */
+ | {
+    kind: "checkout";
+}
+/** Anywhere else, such as another project or a global prefix npm is not configured for here. */
+ | {
+    kind: "other";
+    unmanagedCwd: boolean;
+};
+export interface InstallContext {
+    cwd: string;
+    /** The directory npm's global installs go to from this environment. */
+    npmGlobalRoot: string;
+    /** Whether the package.json in `directory` declares humanish as a dependency. */
+    declaresHumanish: (directory: string) => boolean;
+    /** Whether `npm i` from `directory` installs into a node_modules no package.json declares. */
+    unmanaged: (directory: string) => boolean;
+}
+/** The install `modulePath` belongs to. */
+export declare function classifyHumanishInstall(modulePath: string, context: InstallContext): HumanishInstall;
+/** The running humanish's install, from this file's real path. */
+export declare function humanishInstall(cwd?: string): HumanishInstall;
+/**
+ * Where this humanish is installed, the command that puts `spec` (`@e2b/desktop`, or a version of
+ * it) where it will resolve, and that command as one or two sentences of advice.
+ */
+export declare function desktopPeerAdvice(install: HumanishInstall, spec?: string): {
+    where: string;
+    command: string;
+    advice: string;
+};
+export {};

package/dist/substrates/e2b/peer-install.js

@@ -0,0 +1,161 @@
+// How to add the optional @e2b/desktop peer depends on where humanish itself is installed: Node
+// resolves the peer from humanish's own directory, not from the project a command runs in. Advice
+// for the wrong place installs a copy Node never reads, and `npm i` in a directory whose manifest
+// does not declare what its node_modules holds prunes it, so a command names only a project whose
+// package.json declares humanish, or npm's or pnpm's global directory.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const NODE_MODULES = `${sep}node_modules${sep}`;
+/** The install `modulePath` belongs to. */
+export function classifyHumanishInstall(modulePath, context) {
+    const { cwd } = context;
+    const segments = modulePath.split(sep);
+    if (segments.includes("_npx") || segments.includes("dlx"))
+        return { kind: "one-shot", unmanagedCwd: context.unmanaged(cwd) };
+    if (modulePath.includes(`${sep}pnpm${sep}global${sep}`))
+        return { kind: "global", manager: "pnpm" };
+    const at = modulePath.indexOf(NODE_MODULES);
+    if (at < 0)
+        return { kind: "checkout" };
+    // The first node_modules is the project's; pnpm keeps humanish's files deeper, in .pnpm.
+    const root = modulePath.slice(0, at);
+    if (root === context.npmGlobalRoot)
+        return { kind: "global", manager: "npm" };
+    if (cwd === root || cwd.startsWith(`${root}${sep}`)) {
+        const manager = modulePath.includes(`${NODE_MODULES}.pnpm${sep}`) ? "pnpm" : "npm";
+        // A workspace member declares humanish in its own package.json, and the root may not.
+        for (let directory = cwd, up = 0;; directory = dirname(directory), up += 1) {
+            if (context.declaresHumanish(directory))
+                return { kind: "project", up, manager };
+            if (directory === root)
+                break;
+        }
+    }
+    return { kind: "other", unmanagedCwd: context.unmanaged(cwd) };
+}
+/** The `prefix` an npmrc file sets, with `~` and `$HOME` expanded; undefined when it sets none. */
+function npmrcPrefix(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const value = /^\s*prefix\s*=\s*(.+?)\s*$/m.exec(text)?.[1];
+    if (value === undefined)
+        return undefined;
+    return value
+        .replace(/^~(?=$|[\\/])/, homedir())
+        .replace(/\$\{?HOME\}?/g, homedir())
+        .replace(/^"(.*)"$/, "$1");
+}
+/**
+ * The global root npm installs to from this environment, by npm's own order: the prefix in the
+ * environment, then the user, global and built-in npmrc files (Homebrew sets it in the built-in
+ * one), then the prefix the Node binary implies.
+ */
+function npmGlobalRoot() {
+    const windows = process.platform === "win32";
+    const nodePrefix = windows ? dirname(process.execPath) : dirname(dirname(process.execPath));
+    const prefix = process.env.npm_config_prefix ||
+        process.env.NPM_CONFIG_PREFIX ||
+        npmrcPrefix(process.env.NPM_CONFIG_USERCONFIG || join(homedir(), ".npmrc")) ||
+        npmrcPrefix(process.env.NPM_CONFIG_GLOBALCONFIG || join(nodePrefix, "etc", "npmrc")) ||
+        npmrcPrefix(windows
+            ? join(nodePrefix, "node_modules", "npm", "npmrc")
+            : join(nodePrefix, "lib", "node_modules", "npm", "npmrc")) ||
+        nodePrefix;
+    return windows ? prefix : join(prefix, "lib");
+}
+function declaresHumanish(directory) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+        return ["dependencies", "devDependencies", "optionalDependencies"].some((field) => {
+            const declared = manifest[field];
+            return typeof declared === "object" && declared !== null && "humanish" in declared;
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `npm i` from `directory` would install into a node_modules no package.json declares: npm
+ * installs into the nearest directory, this one or above, that holds either.
+ */
+function unmanaged(directory) {
+    for (let current = directory;; current = dirname(current)) {
+        if (existsSync(join(current, "package.json")))
+            return false;
+        if (existsSync(join(current, "node_modules")))
+            return true;
+        if (dirname(current) === current)
+            return false;
+    }
+}
+/** The running humanish's install, from this file's real path. */
+export function humanishInstall(cwd = process.cwd()) {
+    return classifyHumanishInstall(fileURLToPath(import.meta.url), {
+        cwd,
+        npmGlobalRoot: npmGlobalRoot(),
+        declaresHumanish,
+        unmanaged,
+    });
+}
+/**
+ * Where this humanish is installed, the command that puts `spec` (`@e2b/desktop`, or a version of
+ * it) where it will resolve, and that command as one or two sentences of advice.
+ */
+export function desktopPeerAdvice(install, spec = "@e2b/desktop") {
+    const both = `npm i -D humanish ${spec}`;
+    const relativeTo = "Node resolves the peer relative to humanish itself, so";
+    switch (install.kind) {
+        case "project": {
+            // A directory option, not `cd`: one command, and no `&&` for Windows PowerShell 5.1.
+            const ups = Array.from({ length: install.up }, () => "..").join("/");
+            const command = install.manager === "pnpm"
+                ? `pnpm add -D ${ups ? `--dir ${ups} ` : ""}${spec}`
+                : `npm i -D ${ups ? `--prefix ${ups} ` : ""}${spec}`;
+            const place = ups ? "the project above this directory" : "this project";
+            return {
+                where: "",
+                command,
+                advice: `Install it beside humanish in ${place}: \`${command}\`.`,
+            };
+        }
+        case "global": {
+            const command = install.manager === "pnpm" ? `pnpm add -g ${spec}` : `npm i -g ${spec}`;
+            return {
+                where: ", and humanish is installed globally",
+                command,
+                advice: `${relativeTo} install it globally too: \`${command}\`. That reaches humanish while ` +
+                    "the global directory is still the one it was installed in.",
+            };
+        }
+        case "checkout":
+            return {
+                where: ", and humanish is running from a source checkout",
+                command: "pnpm install",
+                advice: spec === "@e2b/desktop"
+                    ? "Run `pnpm install` in the humanish checkout, which installs it as a dev dependency."
+                    : `Set ${spec} in the humanish checkout's package.json, then run \`pnpm install\` there.`,
+            };
+        case "one-shot":
+        case "other": {
+            const where = install.kind === "one-shot"
+                ? ", and humanish is running from an npx or pnpm dlx cache"
+                : ", and humanish is installed outside this project";
+            const run = `\`${both}\` then \`npx humanish run <study>\``;
+            return {
+                where,
+                command: both,
+                advice: install.unmanagedCwd
+                    ? `${relativeTo} it has to be installed with humanish. From here npm would install into a node_modules folder that no package.json declares, and \`npm i\` would remove what it holds. In your project's directory, run ${run}.`
+                    : `${relativeTo} a copy installed here is not found. Install both into this project and run that copy: ${run}.`,
+            };
+        }
+    }
+}

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

@@ -1,7 +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 E2BDesktopCreateOptions, type E2BDesktopModule, type E2BDesktopSandbox } from "./sdk.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`. */
 interface E2BSandboxReceiptTarget {
@@ -16,7 +16,7 @@ export interface E2BSandboxRequest {
     retry?: TransientRetryHooks;
     /**
      * Required so every caller decides. `null` is only for a caller that could not open a journal;
-     * that sandbox is reclaimable by its create-time `timeoutMs` alone.
+     * that sandbox carries no owner tags and is reclaimable by its create-time `timeoutMs` alone.
      */
     receipt: E2BSandboxReceiptTarget | null;
 }
@@ -57,13 +57,39 @@ export type E2BSandboxDestroyOutcome = {
     state: "kill-failed";
     detail: string;
 };
-/**
- * Kill one sandbox by its exact recorded id, for reclaim, and map the shared release result onto
- * reclaim's persisted outcome. It never lists the account.
- */
+/** 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: {
     requestTimeoutMs: number;
 }): Promise<E2BSandboxDestroyOutcome>;
+/** What `reclaim --check` learned about one sandbox by its exact id. */
+export type E2BSandboxPresence = {
+    state: "running" | "already-gone";
+} | {
+    state: "check-failed";
+    detail: string;
+};
+/**
+ * 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: {
+    requestTimeoutMs: number;
+}): Promise<E2BSandboxPresence>;
+/** What E2B listed for a run's owner tags. `sandboxes` holds exact matches only. */
+export interface E2BTagSearch {
+    status: "done" | "unavailable" | "failed";
+    sandboxes: E2BListedSandbox[];
+    detail?: string;
+}
+/**
+ * List the sandboxes E2B matches to every one of `tags`, filtered server-side. Each result is
+ * 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: {
+    requestTimeoutMs: number;
+}): Promise<E2BTagSearch>;
 /** Versioned public template built by runtime/browser-media/e2b-template.mjs. */
 export declare const E2B_SPEECH_TEMPLATE = "7409n13kr83f7g7abx5g";
 /** The desktop template a study asks for; undefined selects the SDK default. */
@@ -74,6 +100,8 @@ export declare function e2bDesktopTemplate(config: {
 export interface TransientRetryHooks {
     onRetry?: (reason: string) => void;
     sleep?: (ms: number) => Promise<void>;
+    /** False skips the retry, as when the run started stopping during the first attempt. */
+    canRetry?: () => boolean;
 }
 /** Wall-clock pause before the single retry; envd routing settles within a few seconds. */
 export declare const TRANSIENT_RETRY_DELAY_MS = 3000;

package/dist/substrates/e2b/sandbox.js

@@ -1,13 +1,17 @@
 // E2B sandbox acquisition and release. Every route that allocates an E2B sandbox calls this module,
-// so each allocation runs the same steps in the same order: create, one retry on a transient
+// so each allocation runs the same steps in the same order: register the create with the run's
+// in-process registry, tag the sandbox with the run's owner tags, create, one retry on a transient
 // provider error, capture of the exact id and kill authority, and a provider-qualified receipt in
 // the run directory before the caller gets the handle. The desktop startup guard
 // (guardDesktopSandboxCreate) is installed by loadE2BDesktopModule, so a create whose desktop
-// startup fails has already reclaimed its handle when the error reaches the retry here.
+// startup fails has already reclaimed its handle when the error reaches the retry here. The guard
+// reports the id before desktop startup begins, and the id goes to the registry and the receipt
+// journal at that point, so a startup error that quotes it is scrubbed from every run file.
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
-import { appendSandboxReceipt } from "../../run/sandbox-receipts.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 { E2B_DEBUG_KILL_DETAIL, E2BDesktopStartupError, e2bDebugMode, isSandboxNotFoundError, } from "./sdk.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) {
     return acquire(request, request.template);
@@ -17,33 +21,74 @@ export function acquireE2BShellSandbox(request) {
     return acquire(request, undefined);
 }
 async function acquire(request, template) {
-    const { module, options } = request;
-    // Without a template the SDK's one-argument create chooses its stock desktop template.
-    const sandbox = await withOneRetryOnTransientE2BError(() => template === undefined
-        ? module.Sandbox.create(options)
-        : module.Sandbox.create(template, options), request.retry);
-    const allocation = ownE2BSandbox(module, sandbox.sandboxId);
+    const { module } = request;
+    const target = request.receipt;
+    // Refused before any provider call once the run is stopping.
+    const ticket = target === null ? undefined : beginSandboxCreate(target.root, target.participantId);
+    // The receipts written when the guard reported an id, before desktop startup. A startup error
+    // can quote the id and the create may never return, so the journal holds it first.
+    const reported = new Map();
     try {
-        if (request.receipt !== null) {
-            const { root, participantId, now = Date.now } = request.receipt;
-            // Best effort by contract: a failed write leaves the TTL as the only backstop and never
-            // fails the participant.
-            await appendSandboxReceipt(root, {
+        // The owner tags let reclaim find this sandbox on E2B even if its id never reaches this
+        // process: a create that throws after E2B allocated, or a process that dies mid-create. The
+        // journal records them first, so reclaim knows which tags to search for.
+        const owner = target === null ? undefined : sandboxOwnerTags(target.root);
+        if (target !== null && owner !== undefined)
+            await recordSandboxOwnerOnce(target.root, () => appendSandboxOwner(target.root, owner));
+        const options = owner === undefined
+            ? request.options
+            : { ...request.options, metadata: { ...request.options.metadata, ...owner } };
+        const receipt = (sandboxId) => {
+            if (target === null)
+                return Promise.resolve(false);
+            const { root, participantId, now = Date.now } = target;
+            return appendSandboxReceipt(root, {
                 at: new Date(now()).toISOString(),
                 laneId: participantId,
                 provider: "e2b",
-                sandboxId: allocation.resourceId,
+                sandboxId,
                 ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
             });
+        };
+        if (ticket !== undefined)
+            observeDesktopAllocation(options, (sandboxId) => {
+                ticket.created(sandboxId);
+                // Started synchronously, so the run's writers know the id at once. A clock that throws
+                // fails only this write; the receipt after create throws it again.
+                if (!reported.has(sandboxId))
+                    reported.set(sandboxId, new Promise((resolve) => resolve(receipt(sandboxId))).catch(() => false));
+            });
+        const sandbox = await withOneRetryOnTransientE2BError(() => {
+            if (ticket?.stopping())
+                throw new SandboxCreateRefusedError();
+            // Without a template the SDK's one-argument create chooses its stock desktop template.
+            return template === undefined
+                ? module.Sandbox.create(options)
+                : module.Sandbox.create(template, options);
+        }, { ...request.retry, canRetry: () => ticket?.stopping() !== true });
+        ticket?.created(sandbox.sandboxId);
+        const allocation = ownE2BSandbox(module, 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
+            // report wrote is not written again, so reclaim counts the sandbox once.
+            if (!(await reported.get(allocation.resourceId)))
+                await receipt(allocation.resourceId);
+        }
+        catch (error) {
+            // The caller never receives this sandbox, so release it here. A throwing or invalid injected
+            // clock is the known case.
+            await allocation.close();
+            throw error;
         }
+        return { sandbox, allocation };
     }
-    catch (error) {
-        // The caller never receives this sandbox, so release it here. A throwing or invalid injected
-        // clock is the known case.
-        await allocation.close();
-        throw error;
+    finally {
+        // A create that threw settles once its reported receipts are on disk, as one that returned
+        // does. These writes never reject.
+        await Promise.all(reported.values());
+        ticket?.settled();
     }
-    return { sandbox, allocation };
 }
 /** The provider's kill method bound to its class, or undefined when the SDK has none. */
 function boundKill(module) {
@@ -57,7 +102,7 @@ function boundKill(module) {
  * recognized by type, means the same. Every other throw is unconfirmed, whatever its message
  * says: the SDK answers a 404 with false before it throws, so "not found" or "404" in a thrown
  * message comes from some other failure, such as a trace id. A true in debug mode sent no
- * request, so it confirms nothing. Never list the account.
+ * request, so it confirms nothing.
  */
 async function killById(kill, sandboxId, options) {
     if (kill === undefined)
@@ -84,12 +129,18 @@ async function killById(kill, sandboxId, options) {
         return { status: "unconfirmed", reason: "release_failed", error };
     }
 }
-function ownE2BSandbox(module, resourceId) {
+function ownE2BSandbox(module, resourceId, ticket) {
     // Bind the provider method now, before any hook can replace it on the shared module.
     const kill = boundKill(module);
     return ownDesktopAllocation({
         resourceId,
-        release: () => killById(kill, resourceId, { requestTimeoutMs: 60_000 }),
+        release: async () => {
+            const released = await killById(kill, resourceId, { requestTimeoutMs: 60_000 });
+            // The signal handler skips a sandbox its route already released.
+            if (released.status === "released")
+                ticket?.released(resourceId);
+            return released;
+        },
     });
 }
 /**
@@ -136,10 +187,8 @@ export function releaseUnavailableDetail(detail) {
         ? "installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the sandbox"
         : `${detail}; if the sandbox exists, server-side kill-on-timeout will reclaim it`;
 }
-/**
- * Kill one sandbox by its exact recorded id, for reclaim, and map the shared release result onto
- * reclaim's persisted outcome. It never lists the account.
- */
+/** 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);
     if (released.status === "released")
@@ -156,6 +205,68 @@ export async function destroyE2BSandbox(module, sandboxId, options) {
             return { state: "kill-failed", detail: redactText(toErrorMessage(released.error)) };
     }
 }
+/**
+ * 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")
+        return {
+            state: "check-failed",
+            detail: "the installed @e2b/desktop SDK has no Sandbox.getInfo",
+        };
+    try {
+        await module.Sandbox.getInfo(sandboxId, options);
+        return { state: "running" };
+    }
+    catch (error) {
+        if (isSandboxNotFoundError(error))
+            return { state: "already-gone" };
+        return { state: "check-failed", detail: redactText(toErrorMessage(error)) };
+    }
+}
+const TAG_SEARCH_PAGE_SIZE = 100;
+// One run tags at most a few dozen sandboxes. More pages than this means the filter was not
+// applied, and reading on would walk the whole account.
+const TAG_SEARCH_MAX_PAGES = 3;
+/**
+ * List the sandboxes E2B matches to every one of `tags`, filtered server-side. Each result is
+ * 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")
+        return {
+            status: "unavailable",
+            sandboxes: [],
+            detail: "the installed @e2b/desktop SDK has no Sandbox.list",
+        };
+    const sandboxes = [];
+    try {
+        const pages = module.Sandbox.list({
+            query: { metadata: tags },
+            limit: TAG_SEARCH_PAGE_SIZE,
+            requestTimeoutMs: options.requestTimeoutMs,
+        });
+        for (let page = 0; pages.hasNext; page += 1) {
+            if (page === TAG_SEARCH_MAX_PAGES)
+                return {
+                    status: "failed",
+                    sandboxes,
+                    detail: `E2B returned more than ${TAG_SEARCH_MAX_PAGES * TAG_SEARCH_PAGE_SIZE} sandboxes for one run's tags, so the search stopped before reading the rest`,
+                };
+            for (const listed of await pages.nextItems()) {
+                const metadata = listed.metadata ?? {};
+                if (Object.entries(tags).every(([key, value]) => metadata[key] === value))
+                    sandboxes.push(listed);
+            }
+        }
+        return { status: "done", sandboxes };
+    }
+    catch (error) {
+        return { status: "failed", sandboxes, detail: redactText(toErrorMessage(error)) };
+    }
+}
 /** Versioned public template built by runtime/browser-media/e2b-template.mjs. */
 export const E2B_SPEECH_TEMPLATE = "7409n13kr83f7g7abx5g";
 /** The desktop template a study asks for; undefined selects the SDK default. */
@@ -206,7 +317,7 @@ export async function withOneRetryOnTransientE2BError(attempt, hooks) {
         return await attempt();
     }
     catch (error) {
-        if (!isTransientE2BError(error))
+        if (!isTransientE2BError(error) || hooks?.canRetry?.() === false)
             throw error;
         const reason = error instanceof Error ? error.message : String(error);
         hooks?.onRetry?.(reason);

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

@@ -27,7 +27,32 @@ export interface E2BDesktopModule {
         getInfo?(sandboxId: string, options?: {
             requestTimeoutMs?: number;
         }): 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)
+         * and re-checks each tag on what comes back. The e2b SDK on the supported @e2b/desktop range
+         * (2.38 and later) returns a paginator.
+         */
+        list?(options?: E2BSandboxListOptions): E2BSandboxPaginator;
+    };
+}
+interface E2BSandboxListOptions {
+    query?: {
+        metadata?: Record<string, string>;
     };
+    limit?: number;
+    requestTimeoutMs?: number;
+}
+interface E2BSandboxPaginator {
+    readonly hasNext: boolean;
+    nextItems(): Promise<E2BListedSandbox[]>;
+}
+/** One sandbox as the list endpoint describes it. */
+export interface E2BListedSandbox {
+    sandboxId: string;
+    metadata?: Record<string, string>;
+    /** `running` or `paused`. */
+    state?: string;
 }
 interface E2BSandboxInfo {
     id?: string;
@@ -161,6 +186,14 @@ export interface E2BDesktopSandbox {
 }
 export declare function loadE2BDesktopModule(): Promise<E2BDesktopModule>;
 export declare const DESKTOP_CREATE_CLEANUP_TIMEOUT_MS = 10000;
+/**
+ * Call `observer` with the sandbox id as soon as the guarded SDK constructs the handle for a
+ * create made with this exact options object, before desktop startup runs. Startup can take
+ * seconds after E2B created the sandbox; this is the earliest point the id exists in this process.
+ * A module without the guard (a test fake) never calls it, and create's own result still reports
+ * the id.
+ */
+export declare function observeDesktopAllocation(options: E2BDesktopCreateOptions, observer: (sandboxId: string) => void): void;
 type DesktopCreateCleanup = "killed" | "already_gone" | "unconfirmed";
 /** Startup failed after this call acquired a handle. No credentials/options are included here. */
 export declare class E2BDesktopStartupError extends Error {