promigence 0.1.0-beta.12

package/dist/sdk/client.js

@@ -0,0 +1,2583 @@
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { inspect } from "node:util";
+import { dirname, join } from "node:path";
+import { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, ServiceRestartError, SpendCapError, TimeoutError, UnreachableError, DEFAULT_API_URL, ERRORS_DOCS_URL, FILE_PUT_CHUNK_BYTES, MAX_OUTPUT_BYTES_DEFAULT, VERSION, WAIT_TIMEOUT_MS, PreviewsUnavailableError, exitForCode, previewsOff, withPreviewsFix, } from "./core.js";
+import { buildBundle } from "./bundle.js";
+import { keychainReadCached, keychainStore, storeLabel } from "./credstore.js";
+import { CALLER_HEADER, resolveCaller, userAgentWithCaller } from "./caller.js";
+import { connectPty } from "./pty.js";
+import { connectSshTunnel } from "./ssh.js";
+import { H2Response, Http2Transport, http2Allowed, warmTls } from "./http2.js";
+import { CONTEXT_TAR_PREFIX } from "./context.js";
+import { proxyFetch, proxyFor, transportEnv } from "./proxy.js";
+import { mark, traceBegin, traceEvent } from "./trace.js";
+import { KEYED_CREATES } from "./keyed.gen.js";
+import { customDispatcher, longRequestDispatcher } from "./dispatcher.js";
+import { compromisedKeyCause, guardedFetchDispatcher } from "./ca-guard.js";
+import { hintArg } from "./hint.js";
+import { GITHUB_REPO_PREFIX, githubCreateBody, } from "./github.js";
+import { GITLAB_REPO_PREFIX, } from "./gitlab.js";
+export const FILE_TIMEOUT_MS = 15 * 60_000;
+export const isWaiting = (s) => s === "queued" || s === "awaiting_capacity";
+function b64ToBytes(s) {
+    if (!s)
+        return new Uint8Array(0);
+    const bin = typeof atob === "function"
+        ? atob(s)
+        : Buffer.from(s, "base64").toString("binary");
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function bytesToB64(b) {
+    if (typeof btoa !== "function")
+        return Buffer.from(b).toString("base64");
+    let bin = "";
+    for (let i = 0; i < b.length; i += 8192)
+        bin += String.fromCharCode(...b.subarray(i, i + 8192));
+    return btoa(bin);
+}
+function modeParam(mode) {
+    return typeof mode === "number" ? mode.toString(8) : mode;
+}
+export function execOutputBytes(r, stream = "stdout") {
+    const b64 = r[`${stream}_b64`];
+    if (typeof b64 === "string")
+        return b64ToBytes(b64);
+    return new TextEncoder().encode(r[stream] ?? "");
+}
+function pageOf(r, key, asked) {
+    if (Array.isArray(r))
+        return { items: r, nextCursor: null, limit: asked };
+    const o = (r ?? {});
+    const items = Array.isArray(o[key]) ? o[key] : [];
+    const c = o["next_cursor"];
+    return {
+        items,
+        nextCursor: typeof c === "string" && c !== "" ? c : null,
+        limit: typeof o["limit"] === "number" ? o["limit"] : asked,
+    };
+}
+function orgSeg(org) {
+    if (!org?.trim())
+        throw new InvalidArgumentError("an organization is required", "Pass its id (org_…) or name; me().org_id is this key's.");
+    return encodeURIComponent(org.trim());
+}
+function pageQuery(limit, max, cursor) {
+    const q = new URLSearchParams({ limit: String(Math.max(1, Math.min(max, Math.floor(limit)))) });
+    if (cursor)
+        q.set("cursor", cursor);
+    return q.toString();
+}
+function expiryFields(o) {
+    const body = {};
+    if (o.expiresInDays !== undefined)
+        body["expires_in_days"] = o.expiresInDays;
+    if (o.expiresAt !== undefined)
+        body["expires_at"] = o.expiresAt;
+    return body;
+}
+export const NOTICE_HEADER = "promigence-notice";
+export const MAX_SOURCES = 8;
+export function configDir(env = process.env) {
+    return join(env["XDG_CONFIG_HOME"] || join(homedir(), ".config"), "promigence");
+}
+export function credentialsPath(env = process.env) {
+    return join(configDir(env), "credentials");
+}
+export function credentialsTrustProblem(path) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    const gid = typeof process.getgid === "function" ? process.getgid() : undefined;
+    if (uid === undefined)
+        return undefined;
+    for (const p of [dirname(path), path]) {
+        let st;
+        try {
+            st = statSync(p);
+        }
+        catch {
+            return undefined;
+        }
+        if (st.uid !== uid)
+            return `${p} belongs to another user (uid ${st.uid})`;
+        if ((st.mode & 0o002) !== 0)
+            return `${p} is writable by every user`;
+        if ((st.mode & 0o020) !== 0 && st.gid !== gid)
+            return `${p} is writable by group ${st.gid}`;
+    }
+    return undefined;
+}
+const credentialsWarned = new Set();
+export function credentialsExposure(path) {
+    if (typeof process.getuid !== "function")
+        return undefined;
+    let st;
+    try {
+        st = statSync(path);
+    }
+    catch {
+        return undefined;
+    }
+    if ((st.mode & 0o044) === 0)
+        return undefined;
+    return `${path} is readable by ${(st.mode & 0o004) !== 0 ? "every user" : "its group"} (mode ${(st.mode & 0o777).toString(8)})`;
+}
+function decodeCredentials(buf) {
+    if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe)
+        return buf.subarray(2).toString("utf16le");
+    if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+        const le = Buffer.from(buf.subarray(2));
+        le.swap16();
+        return le.toString("utf16le");
+    }
+    if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf)
+        return buf.subarray(3).toString("utf8");
+    return buf.toString("utf8");
+}
+export function storedCredentials(env = process.env, platform = process.platform) {
+    const path = credentialsPath(env);
+    let present = true;
+    try {
+        statSync(path);
+    }
+    catch (e) {
+        present = e.code !== "ENOENT";
+    }
+    if (!present) {
+        const store = keychainStore(env, platform);
+        if (store === undefined)
+            return undefined;
+        const r = keychainReadCached(store, path, env);
+        if (r.status === "found")
+            return { text: r.text, store, path };
+        if (r.status === "absent")
+            return undefined;
+        if (r.locked) {
+            const why = `${storeLabel(store)} is locked`;
+            if (!credentialsWarned.has(why)) {
+                credentialsWarned.add(why);
+                process.emitWarning(`${why}, so the Promigence key stored in it cannot be read (an SSH session cannot unlock it). `
+                    + (store === "macos-keychain" ? "Unlock it with `security unlock-keychain`, or " : "Unlock it, or ")
+                    + "set PROMIGENCE_API_KEY for this shell.", { code: "PROMIGENCE_CREDENTIALS" });
+            }
+        }
+        return { unavailable: { store, reason: r.reason, locked: r.locked }, path };
+    }
+    const untrusted = credentialsTrustProblem(path);
+    if (untrusted !== undefined) {
+        if (!credentialsWarned.has(untrusted)) {
+            credentialsWarned.add(untrusted);
+            process.emitWarning(`ignoring the Promigence credentials file: ${untrusted}. Fix the owner or mode (chmod go-w), `
+                + "or set XDG_CONFIG_HOME to a directory only you can write.", { code: "PROMIGENCE_CREDENTIALS" });
+        }
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = decodeCredentials(readFileSync(path));
+    }
+    catch {
+        return undefined;
+    }
+    const exposed = credentialsExposure(path);
+    if (exposed !== undefined && !credentialsWarned.has(exposed)) {
+        credentialsWarned.add(exposed);
+        process.emitWarning(`the Promigence credentials file holds an API key and ${exposed}. `
+            + `Run \`chmod 600 ${path}\` (promigence login writes it that way).`, { code: "PROMIGENCE_CREDENTIALS" });
+    }
+    return { text: raw, store: "file", path };
+}
+export function storedCredentialsText(env = process.env) {
+    const s = storedCredentials(env);
+    return s === undefined || "unavailable" in s ? undefined : s;
+}
+function parseCredentials(raw) {
+    const text = raw.trim();
+    if (!text)
+        return {};
+    if (text.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(text);
+            const out = {};
+            const key = parsed["api_key"] ?? parsed["apiKey"];
+            const url = parsed["api_url"] ?? parsed["apiUrl"];
+            if (typeof key === "string" && key.trim())
+                out.api_key = key.trim();
+            if (typeof url === "string" && url)
+                out.api_url = url;
+            return out;
+        }
+        catch {
+            return {};
+        }
+    }
+    const first = text.split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#"));
+    return first ? { api_key: first } : {};
+}
+export function readCredentialsWithStore(env = process.env) {
+    const s = storedCredentials(env);
+    if (s === undefined)
+        return { creds: {}, store: undefined };
+    if ("unavailable" in s)
+        return { creds: {}, store: undefined, unavailable: s.unavailable };
+    return { creds: parseCredentials(s.text), store: s.store };
+}
+export function readCredentials(env = process.env) {
+    return readCredentialsWithStore(env).creds;
+}
+function storedName(store, env) {
+    return store === undefined || store === "file" ? `the credentials file (${credentialsPath(env)})` : storeLabel(store);
+}
+const COMPAT_REFUSED_HOSTS = /(^|\.)e2b(-staging)?\.(app|dev|pro)$/i;
+export function apiUrlFromCompatUrl(url) {
+    const u = (url ?? "").trim();
+    if (!u)
+        return undefined;
+    let host = "";
+    try {
+        host = new URL(u.includes("://") ? u : `https://${u}`).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    return COMPAT_REFUSED_HOSTS.test(host) ? undefined : u;
+}
+export function apiUrlFromCompatDomain(domain) {
+    const d = (domain ?? "").trim().replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    if (!d || COMPAT_REFUSED_HOSTS.test(d))
+        return undefined;
+    return `https://api.${d}/v1`;
+}
+export function compatApiKey(key) {
+    const k = key?.trim();
+    return k && !k.startsWith("e2b_") ? k : undefined;
+}
+export function keyOrigin(env = process.env) {
+    if (env["PROMIGENCE_API_KEY"]?.trim())
+        return "PROMIGENCE_API_KEY";
+    const stored = readCredentialsWithStore(env);
+    if (stored.creds.api_key)
+        return stored.store === "macos-keychain" ? "macOS Keychain" : stored.store === "secret-service" ? "Secret Service keyring" : "credentials file";
+    return undefined;
+}
+function resolveCredentials(opts, env = process.env) {
+    const set = (v) => (v ? v : undefined);
+    const trim = (u) => {
+        const t = u.replace(/\/+$/, "");
+        return /^https?:\/\/[^/?#]+$/i.test(t) ? `${t}/v1` : t;
+    };
+    const optKey = opts.apiKey?.trim();
+    const envKey = optKey === undefined ? set(env["PROMIGENCE_API_KEY"]?.trim()) : undefined;
+    const envUrl = optKey !== undefined && opts.apiUrl !== undefined ? undefined : set(env["PROMIGENCE_API_URL"]);
+    const given = optKey !== undefined || envKey !== undefined;
+    const { creds, store } = given
+        ? { creds: {}, store: undefined }
+        : readCredentialsWithStore(env);
+    const source = optKey !== undefined ? "opts" : envKey !== undefined ? "env" : creds.api_key !== undefined ? "file" : undefined;
+    const ours = optKey ?? envKey ?? creds.api_key;
+    const fallback = ours === undefined ? opts.fallbackKey : undefined;
+    const fallbackKey = set(fallback?.apiKey.trim());
+    const fallbackUrl = fallbackKey === undefined ? undefined : set(fallback?.apiUrl);
+    const fromFile = () => trim(creds.api_url ?? fallbackUrl ?? DEFAULT_API_URL);
+    const fromEnv = () => (envUrl !== undefined ? trim(envUrl) : fromFile());
+    const apiUrl = opts.apiUrl !== undefined ? trim(opts.apiUrl) : fromEnv();
+    const paired = source === "file" ? fromFile() : source === "env" ? fromEnv() : apiUrl;
+    if (ours !== undefined && paired !== apiUrl) {
+        const keyFrom = source === "file" ? (store === undefined || store === "file" ? "the credentials file" : storeLabel(store)) : "PROMIGENCE_API_KEY";
+        const urlFrom = opts.apiUrl !== undefined ? "apiUrl" : "PROMIGENCE_API_URL";
+        const refusal = new InvalidArgumentError(`the API key from ${keyFrom} belongs to ${paired}; it is not sent to ${apiUrl} (from ${urlFrom})`, source === "file"
+            ? `Pass the key with the URL (apiKey beside apiUrl, or PROMIGENCE_API_KEY beside PROMIGENCE_API_URL), or run \`promigence login\` against ${apiUrl}.`
+            : "Pass apiKey together with apiUrl, or set PROMIGENCE_API_URL to that URL instead of passing apiUrl.");
+        return { apiKey: undefined, apiUrl, refusal };
+    }
+    const key = ours ?? fallbackKey;
+    if (key) {
+        const from = source === "opts" ? "the apiKey option" : source === "env" ? "PROMIGENCE_API_KEY"
+            : source === "file" ? storedName(store, env) : fallback.from;
+        const refusal = keyRefusal(key, from);
+        if (refusal)
+            return { apiKey: undefined, apiUrl, refusal };
+    }
+    return { apiKey: key, apiUrl };
+}
+function keyRefusal(key, from) {
+    if (/^[\x21-\x7E]+$/.test(key))
+        return undefined;
+    return new AuthError(`the API key from ${from} is not a valid HTTP header value (it holds a space, a control character or a non-ASCII character)`, `Check ${from} for stray characters inside the key, or run \`promigence login\` to store a fresh one.`);
+}
+function transportDetail(err) {
+    const refused = compromisedKeyCause(err);
+    if (refused !== undefined)
+        return refused.message;
+    const e = err;
+    if (e?.name === "TypeError" && /header/i.test(e.message ?? ""))
+        return "a request header holds a character HTTP does not allow";
+    return e?.cause?.code ?? e?.message ?? "connection failed";
+}
+function bodyExtra(payload) {
+    const e = payload.error;
+    return {
+        ...(e?.docs ? { docs: e.docs } : {}),
+        ...(typeof e?.category === "string" ? { category: e.category } : {}),
+        ...(typeof e?.retryable === "boolean" ? { retryable: e.retryable } : {}),
+    };
+}
+function codeForStatus(status) {
+    if (status === 400 || status === 422)
+        return "usage";
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 404)
+        return "not_found";
+    if (status === 409)
+        return "cap_exceeded";
+    if (status === 402)
+        return "cap_exceeded";
+    if (status === 429)
+        return "rate_limited";
+    if (status === 502 || status === 503 || status === 504)
+        return "unreachable";
+    return "internal";
+}
+function errorCodeOf(text) {
+    try {
+        const code = JSON.parse(text)?.error?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const IMAGE_DIGEST_RE = /^[^\s@]+@sha256:[0-9a-f]{64}$/;
+const SHA256_RE = /^sha256:[0-9a-f]{64}$/;
+const IMAGE_TAG_RE = /^[A-Za-z0-9_.-]+$/;
+const IMAGE_REPO_RE = /^[a-z0-9._/-]+$/;
+export function imageRefProblem(image) {
+    if (typeof image !== "string")
+        return "it is not a string";
+    const ref = image.trim();
+    if (!ref)
+        return "it is empty";
+    if (ref.length > 1024)
+        return "it is longer than 1024 characters";
+    if (/[\s\x00-\x1f\x7f]/.test(ref))
+        return "it contains whitespace";
+    let rest = ref;
+    const at = rest.lastIndexOf("@");
+    if (at >= 0) {
+        const digest = rest.slice(at + 1);
+        if (!SHA256_RE.test(digest))
+            return `digest ${JSON.stringify(digest)} is not \`sha256:\` followed by 64 lower-case hex characters`;
+        rest = rest.slice(0, at);
+    }
+    const colon = rest.lastIndexOf(":");
+    if (colon >= 0 && !rest.slice(colon + 1).includes("/")) {
+        const tag = rest.slice(colon + 1);
+        if (!tag)
+            return "its tag is empty";
+        if (!IMAGE_TAG_RE.test(tag))
+            return `tag ${JSON.stringify(tag)} is not a valid tag`;
+        rest = rest.slice(0, colon);
+    }
+    const slash = rest.indexOf("/");
+    const head = slash >= 0 ? rest.slice(0, slash) : "";
+    const repo = slash >= 0 && (head.includes(".") || head.includes(":") || head === "localhost") ? rest.slice(slash + 1) : rest;
+    if (!repo)
+        return "it names no repository";
+    if (!IMAGE_REPO_RE.test(repo)) {
+        return `repository ${JSON.stringify(repo)} is not a valid name (lower-case letters, digits, \`.\`, \`_\`, \`-\` and \`/\`)`;
+    }
+    return undefined;
+}
+export function checkImageRef(image) {
+    const problem = imageRefProblem(image);
+    if (problem !== undefined) {
+        throw new InvalidArgumentError(`image ${JSON.stringify(image ?? null)} is not an image reference: ${problem}`, "Pass a tag such as python:3.12 or ghcr.io/org/app:v1 (the API pins it to a digest when " +
+            "the snapshot is created), or a reference already pinned as NAME@sha256:<64 hex>.");
+    }
+}
+export function imageRefNamesVersion(image) {
+    const ref = image.trim();
+    if (ref.includes("@"))
+        return true;
+    const colon = ref.lastIndexOf(":");
+    return colon >= 0 && !ref.slice(colon + 1).includes("/");
+}
+export function checkImageVersioned(image) {
+    if (imageRefNamesVersion(image))
+        return;
+    const ref = image.trim();
+    throw new InvalidArgumentError(`image ${JSON.stringify(ref)} names no tag or digest, so it would be pinned to whatever ${ref}:latest is today`, `Name the version: a tag (${ref}:<version>), ${ref}:latest if you mean the moving tag, or a digest (${ref}@sha256:<64 hex>).`);
+}
+export const CONTEXT_GIT_RE = /^(?:https?:\/\/|ssh:\/\/|git:\/\/|git@)\S+@[0-9a-f]{40}$/i;
+export function repoUrlCredential(url) {
+    const u = url.trim();
+    const sep = u.indexOf("://");
+    let auth;
+    if (sep >= 0) {
+        const rest = u.slice(sep + 3);
+        const end = rest.search(/[/?#]/);
+        auth = end < 0 ? rest : rest.slice(0, end);
+    }
+    else {
+        const colon = u.indexOf(":");
+        if (colon >= 0 && !u.slice(0, colon).includes("/"))
+            auth = u.slice(0, colon);
+    }
+    if (auth !== undefined && (auth.includes("@") || /%40/i.test(auth) || (sep >= 0 && u.includes("@")))) {
+        return "userinfo";
+    }
+    if (u.includes("?"))
+        return "query";
+    if (u.includes("#"))
+        return "fragment";
+    return undefined;
+}
+export function withoutPin(s) {
+    const at = s.lastIndexOf("@");
+    return at > 0 && !s.slice(at + 1).includes("/") ? s.slice(0, at) : s;
+}
+export const REPO_CREDENTIALS_FIX = "Nothing was built or billed. A repository URL never carries a credential. For a private repository, connect its " +
+    "host once for your organization (`promigence github connect` or `promigence gitlab connect`) and name it as " +
+    "`--repo owner/name` (`--repo gitlab:group/project`); a public one is named by its plain https:// URL, with no " +
+    "user name, password, token, query string or fragment in it.";
+export function checkRepoUrl(url, field) {
+    if (typeof url === "string" && repoUrlCredential(url) !== undefined) {
+        throw new InvalidArgumentError(`credentials in repository URLs are not accepted (${field})`, REPO_CREDENTIALS_FIX, "repo_credentials_not_supported");
+    }
+}
+export function checkDockerfileContext(context) {
+    const c = typeof context === "string" ? context.trim() : "";
+    if (!c.startsWith(CONTEXT_TAR_PREFIX))
+        checkRepoUrl(withoutPin(c), "dockerfile.context");
+    if (!c) {
+        throw new InvalidArgumentError("snapshots.create dockerfile needs a context", "Pass { dockerfile: { context: 'https://github.com/org/app@<40-char sha>', path: 'Dockerfile' } }, " +
+            "or pack a directory with packContext('./app').");
+    }
+    if (c.startsWith(CONTEXT_TAR_PREFIX) || CONTEXT_GIT_RE.test(c))
+        return;
+    throw new InvalidArgumentError(`dockerfile.context must be a git URL pinned to a full 40-character sha, got ${JSON.stringify(context)}`, "A branch or a tag is not a pin: pass URL@<40-char sha> (git rev-parse HEAD), or pack a local " +
+        "directory with packContext('./app').");
+}
+function sourcesBody(sources) {
+    if (sources.length > MAX_SOURCES) {
+        throw new InvalidArgumentError(`snapshots.create takes at most ${MAX_SOURCES} extra sources, got ${sources.length}`, "An environment assembled from more repositories than that is cheaper to build once as " +
+            "an image and snapshot from there.");
+    }
+    return sources.map((s, i) => {
+        checkRepoUrl(s?.repo, `sources[${i}].repo`);
+        if (!s?.repo) {
+            throw new InvalidArgumentError(`snapshots.create sources[${i}] needs a repo`, "Pass { repo: 'https://github.com/org/lib', commit: <40-char sha> }.");
+        }
+        if (!/^[0-9a-f]{40}$/i.test(s.commit ?? "")) {
+            throw new InvalidArgumentError(`snapshots.create sources[${i}] needs a full 40-character commit sha, got ${JSON.stringify(s.commit ?? null)}`, "A branch or a short sha is not a pin: pass the full sha (git rev-parse HEAD).");
+        }
+        const out = { repo: s.repo, commit: s.commit.toLowerCase() };
+        if (s.path)
+            out["path"] = s.path;
+        return out;
+    });
+}
+function verifyBody(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === "string")
+        return v ? { cmd: v, allow_fast: false } : undefined;
+    if (!v.cmd)
+        return undefined;
+    const raw = v;
+    return { cmd: v.cmd, allow_fast: Boolean(raw.allowFast ?? raw.allow_fast ?? false) };
+}
+export function snapshotCreateBody(opts) {
+    const o = (opts ?? {});
+    const forms = [
+        ["image", o.image !== undefined],
+        ["dockerfile", o.dockerfile !== undefined],
+        ["repo", o.repo !== undefined || o.commit !== undefined],
+    ].filter(([, present]) => present).map(([n]) => n);
+    if (forms.length === 0) {
+        throw new InvalidArgumentError("snapshots.create needs an image, a dockerfile or a repo", "Pass { image: 'registry/name@sha256:…' }, { dockerfile: { context: …, path: 'Dockerfile' } }, " +
+            "or { repo: 'https://github.com/org/app', commit: <40-char sha> }.");
+    }
+    if (forms.length > 1) {
+        throw new InvalidArgumentError(`snapshots.create takes one input form, got ${forms.join(" + ")}`, "Pass exactly one of image, dockerfile, or repo/commit.");
+    }
+    const verify = verifyBody(o.verify);
+    let body;
+    const github = typeof o.repo === "string"
+        && (o.repo.trim().startsWith(GITHUB_REPO_PREFIX) || o.repo.trim().startsWith(GITLAB_REPO_PREFIX));
+    if (o.env !== undefined && Object.keys(o.env).length && forms[0] === "repo") {
+        throw new InvalidArgumentError("snapshots.create env is for an image or a Dockerfile", "A repository snapshot sets its environment in its setup steps, or pass env on each command.");
+    }
+    if ((o.user !== undefined || o.setupUser !== undefined) && forms[0] === "repo") {
+        throw new InvalidArgumentError("snapshots.create user and setupUser are for an image or a Dockerfile", "A repository snapshot runs as root; name a user on each command instead ({ user: 'app' }).");
+    }
+    if (o.setupUser !== undefined && o.user === undefined) {
+        throw new InvalidArgumentError("snapshots.create setupUser needs user", "Pass { user: 'app', setupUser: 'app' }: start, setup and verify as app too (without setupUser they run as root), every later command as app.");
+    }
+    if (!github && (o.ref !== undefined || o.from !== undefined || o.track)) {
+        throw new InvalidArgumentError("snapshots.create ref, from and track are for a connected repository (repo: 'github:owner/name' or 'gitlab:group/project')", "Pass { repo: 'github:your-org/app', ref: 'main' }, or drop them for this form.");
+    }
+    if (github) {
+        body = githubCreateBody({
+            repo: o.repo, commit: o.commit, ref: o.ref, from: o.from, track: o.track,
+            setup: o.setup, verify, tier: o.tier, alias: o.alias,
+            others: [
+                ["sources", Boolean(o.sources?.length)], ["start", o.start !== undefined],
+                ["registrySecret", Boolean(o.registrySecret)],
+            ],
+        });
+    }
+    else if (forms[0] === "repo") {
+        if (!o.repo)
+            throw new InvalidArgumentError("snapshots.create needs a repo", "Pass { repo: 'https://github.com/org/app' }.");
+        checkRepoUrl(o.repo, "repo");
+        if (!/^[0-9a-f]{40}$/i.test(o.commit ?? "")) {
+            throw new InvalidArgumentError(`snapshots.create needs a full 40-character commit sha, got ${JSON.stringify(o.commit ?? null)}`, "A branch or a short sha is not a pin: pass the full sha (git rev-parse HEAD).");
+        }
+        if (!verify) {
+            throw new InvalidArgumentError("snapshots.create needs a verify command", "Pass { verify: { cmd: 'bun typecheck' } } — a snapshot with nothing to verify is not verified.");
+        }
+        body = { repo: o.repo, commit: o.commit.toLowerCase(), setup: o.setup ?? [], verify };
+        if (o.sources?.length)
+            body["sources"] = sourcesBody(o.sources);
+        if (o.tier !== undefined)
+            body["tier"] = o.tier;
+    }
+    else {
+        if (o.sources?.length) {
+            throw new InvalidArgumentError("snapshots.create sources is part of the repo form", "An image already carries its tree and may not have git in it: clone the extra " +
+                "repository in a setup step, or pass { repo, commit, sources }.");
+        }
+        body = {};
+        if (forms[0] === "image") {
+            checkImageRef(o.image);
+            body["image"] = o.image;
+        }
+        else {
+            const ctx = o.dockerfile?.context;
+            checkDockerfileContext(ctx);
+            body["dockerfile"] = { context: ctx, ...(o.dockerfile.path ? { path: o.dockerfile.path } : {}) };
+        }
+        if (o.setup?.length)
+            body["setup"] = [...o.setup];
+        if (verify)
+            body["verify"] = verify;
+        if (o.start !== undefined && o.start !== "" && !(Array.isArray(o.start) && o.start.length === 0)) {
+            body["start"] = typeof o.start === "string" ? o.start : [...o.start];
+        }
+        if (o.tier !== undefined)
+            body["tier"] = o.tier;
+        if (o.registrySecret)
+            body["registry_secret"] = o.registrySecret;
+        if (o.env !== undefined && Object.keys(o.env).length)
+            body["env"] = { ...o.env };
+        if (o.user !== undefined)
+            body["user"] = o.user;
+        if (o.setupUser !== undefined)
+            body["setup_user"] = o.setupUser;
+    }
+    if (o.alias)
+        body["alias"] = o.alias;
+    if (o.grade) {
+        if (!o.grade.cmd)
+            throw new InvalidArgumentError("snapshots.create grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
+        const g = { cmd: o.grade.cmd };
+        if (o.grade.holdoutCmd)
+            g["holdout_cmd"] = o.grade.holdoutCmd;
+        if (o.grade.timeoutMs !== undefined)
+            g["timeout_ms"] = o.grade.timeoutMs;
+        if (o.grade.score !== undefined)
+            g["score"] = o.grade.score;
+        body["grade"] = g;
+    }
+    if (o.gradeOutput !== undefined) {
+        if (o.gradeOutput && !o.grade) {
+            throw new InvalidArgumentError("snapshots.create gradeOutput needs a grade", "Pass { grade: { cmd: 'pytest -q tests/' }, gradeOutput: true }.");
+        }
+        body["grade_output"] = o.gradeOutput;
+    }
+    return body;
+}
+const ENV_CODES = new Set([
+    "fork_failed", "start_timeout", "readiness_failed", "verify_too_slow", "verify_each_failed",
+    "toolchain_mismatch", "sandbox_unresponsive", "oom_within_tier", "disk_full_within_tier",
+    "sandbox_interrupted", "integrity_mismatch", "egress_unavailable", "service_timeout",
+    "resume_unavailable", "sandbox_unreachable", "capacity_busy", "region_at_capacity",
+    "builder_unavailable", "builder_busy", "overloaded", "tier_unavailable", "snapshot_unavailable",
+    "capacity_limit", "registry_unavailable", "network_policy_unsupported", "secrets_unavailable",
+    "secret_binding_unsupported", "idempotency_key_in_use",
+]);
+const REFUSED_503_CODES = new Set([
+    "resume_unavailable", "sandbox_unreachable", "capacity_busy", "region_at_capacity",
+    "builder_unavailable", "builder_busy", "overloaded", "tier_unavailable", "registry_unavailable",
+    "secrets_unavailable",
+]);
+function withoutCliHelp(fix) {
+    const out = fix.replace(/\s*See `promigence [^`]*--help`\.?\s*$/, "").trim();
+    if (out === fix.trim())
+        return fix;
+    return out === "" ? "Change what the message names, then call again." : out;
+}
+export function errorFor(code, message, fix, extra = {}) {
+    const attach = (e) => {
+        const w = e;
+        w.docs = extra.docs ?? `${ERRORS_DOCS_URL}#${code}`;
+        if (extra.status !== undefined)
+            w.status = extra.status;
+        if (extra.requestId !== undefined)
+            w.requestId = extra.requestId;
+        if (extra.retryAfterMs !== undefined)
+            w.retryAfterMs = extra.retryAfterMs;
+        if (extra.category !== undefined)
+            w.category = extra.category;
+        if (extra.retryable !== undefined)
+            w.retryable = extra.retryable;
+        return e;
+    };
+    if ((code === "usage" || code === "invalid_argument" || code === "unsupported") && previewsOff(message)) {
+        return attach(new PreviewsUnavailableError());
+    }
+    switch (code) {
+        case "auth": return attach(new AuthError(message, fix));
+        case "not_found": return attach(new NotFoundError(message, fix));
+        case "unreachable": return attach(new UnreachableError(message, fix));
+        case "rate_limited": return attach(new RateLimitError(message, extra.retryAfterMs));
+        case "cap_exceeded":
+        case "cap_killed":
+        case "cap_paused":
+        case "credits_paused":
+            return attach(new SpendCapError(message, fix, code));
+        case "not_verified": return attach(new NotVerifiedError(message, fix));
+        case "timeout": return attach(new TimeoutError(message, fix));
+        case "usage":
+        case "invalid_argument":
+            return attach(new InvalidArgumentError(message, extra.cli ? fix : withoutCliHelp(fix), code));
+        case "not_released": return attach(new NotReleasedError(message));
+        case "service_restart": return attach(new ServiceRestartError(message, fix));
+        default:
+            if (ENV_CODES.has(code) || extra.category === "env")
+                return attach(new EnvFailedError(code, message, fix));
+            return attach(new ApiError({
+                code,
+                message,
+                fix,
+                exitCode: exitForCode(code),
+                ...(extra.docs === undefined ? {} : { docs: extra.docs }),
+                ...(extra.status === undefined ? {} : { status: extra.status }),
+                ...(extra.requestId === undefined ? {} : { requestId: extra.requestId }),
+            }));
+    }
+}
+const KEYED_PATTERNS = KEYED_CREATES.map(([m, p]) => [m, p.split("/").filter(Boolean)]);
+const KEYED_METHODS = new Set(KEYED_CREATES.map(([m]) => m));
+export function isKeyedCreate(method, path) {
+    if (!KEYED_METHODS.has(method))
+        return false;
+    const segs = (path.split("?")[0] ?? "").split("/").filter(Boolean);
+    for (const [m, pat] of KEYED_PATTERNS) {
+        if (m !== method || pat.length !== segs.length)
+            continue;
+        let all = true;
+        for (let i = 0; i < pat.length; i++) {
+            const s = pat[i];
+            if (s.startsWith("{") ? (segs[i] ?? "").length === 0 : s !== segs[i]) {
+                all = false;
+                break;
+            }
+        }
+        if (all)
+            return true;
+    }
+    return false;
+}
+function commandTimeoutMs(v) {
+    if (v === undefined)
+        return undefined;
+    if (!Number.isInteger(v) || v <= 0) {
+        throw new InvalidArgumentError(`timeoutMs must be a positive whole number of milliseconds, got ${String(v)}`, "Omit it for the default (15 minutes in the foreground, the sandbox's own timeout in the background), or pass a bound such as 600_000.");
+    }
+    return v;
+}
+export function checkSandboxId(sandboxId, call) {
+    if (typeof sandboxId === "string" && sandboxId.trim() !== "")
+        return;
+    throw new InvalidArgumentError(`${call} needs a sandbox id, got ${JSON.stringify(sandboxId ?? null)}`, "Pass the id a create returned (sandbox.sandboxId, `sbx_…`). An unset environment variable is the usual way to pass an empty one.");
+}
+export function checkSpendCap(spendCap) {
+    if (typeof spendCap === "number" && Number.isFinite(spendCap) && spendCap >= 0)
+        return spendCap;
+    throw new InvalidArgumentError(`spend cap must be a number of US dollars, 0 or more, got ${String(spendCap)}`, "Pass spendCap: 1 (or PROMIGENCE_SPEND_CAP=1): the most this run may spend.");
+}
+export function newIdempotencyKey() {
+    return `idk_${globalThis.crypto.randomUUID()}`;
+}
+function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const secs = Number(header.trim());
+    if (Number.isFinite(secs))
+        return Math.max(0, secs * 1000);
+    const at = Date.parse(header);
+    if (!Number.isNaN(at))
+        return Math.max(0, at - Date.now());
+    return undefined;
+}
+const MAX_RETRY_SLEEP_MS = 10_000;
+const STREAM_IDLE_MS = 90_000;
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+const POLLING_TICK_MS = 5;
+const PARKED_TICK_MS = 50;
+async function keepingLoopAwake(everyMs, fn) {
+    let tick;
+    try {
+        tick = setInterval(() => { }, everyMs);
+        tick.unref?.();
+        return await fn();
+    }
+    finally {
+        if (tick !== undefined)
+            clearInterval(tick);
+    }
+}
+const WAIT_MS_CAP = 30_000;
+export const LONG_POLL_MS = 5_000;
+const BUILD_POLL_MS = 10_000;
+const PROGRESS_POLL_MS = 200;
+const WAITED_HEADER = "promigence-waited-ms";
+const seg = (s) => encodeURIComponent(s).replace(/%40/g, "@");
+function waitQuery(waitMs) {
+    return waitMs !== undefined && waitMs > 0
+        ? `?wait_ms=${Math.min(Math.floor(waitMs), WAIT_MS_CAP)}`
+        : "";
+}
+const notReleased = (what) => Promise.reject(new NotReleasedError(what));
+let defaultUserAgent;
+const APP_SPAN = /^\s*app\s*;(?:.*;)?\s*dur=([0-9]+(?:\.[0-9]+)?)/;
+export function serverAppMs(header) {
+    if (!header)
+        return null;
+    if (!header.includes(",")) {
+        const m = APP_SPAN.exec(header);
+        return m ? Number(m[1]) : null;
+    }
+    for (const part of header.split(",")) {
+        const m = APP_SPAN.exec(part);
+        if (m)
+            return Number(m[1]);
+    }
+    return null;
+}
+function headerOf(res, name) {
+    return res instanceof H2Response ? res.header(name) : res.headers.get(name);
+}
+export class PromigenceClient {
+    apiUrl;
+    #apiKey;
+    #keyRefusal;
+    #bearer;
+    fetchImpl;
+    ownFetch;
+    h2;
+    requestTimeoutMs;
+    maxRetries;
+    retryBaseMs;
+    userAgent;
+    cliErrors;
+    caller;
+    stats = { requests: 0, retries: 0 };
+    lastTiming = null;
+    notice;
+    onNotice;
+    onTiming;
+    noticesSeen = new Set();
+    constructor(opts = {}) {
+        traceEvent("client:ctor");
+        const resolved = resolveCredentials(opts);
+        this.#apiKey = resolved.apiKey;
+        this.#keyRefusal = resolved.refusal;
+        this.apiUrl = resolved.apiUrl;
+        const env = opts.fetch === undefined ? transportEnv() : undefined;
+        const proxy = env !== undefined ? proxyFor(this.apiUrl, env) : undefined;
+        this.fetchImpl = opts.fetch ?? (proxy ? proxyFetch(proxy) : globalThis.fetch);
+        this.ownFetch = opts.fetch === undefined && proxy === undefined;
+        this.h2 = env !== undefined && this.apiUrl.startsWith("https:") && http2Allowed(opts.http2, env)
+            ? new Http2Transport(this.fetchImpl)
+            : undefined;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? 30_000;
+        this.maxRetries = opts.maxRetries ?? 3;
+        this.retryBaseMs = opts.retryBaseMs ?? 250;
+        this.caller = resolveCaller(opts.caller);
+        this.userAgent = userAgentWithCaller(opts.userAgent ?? (defaultUserAgent ??= `promigence/${VERSION} node/${process.versions.node}`), this.caller);
+        this.onNotice = opts.onNotice;
+        this.onTiming = opts.onTiming;
+        this.cliErrors = opts.cliErrors === true;
+        traceEvent("client:ready");
+    }
+    observeNotice(raw) {
+        if (!raw)
+            return;
+        let n;
+        try {
+            n = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!n || typeof n.code !== "string")
+            return;
+        this.notice = n;
+        const key = `${n.code}|${n.effective_at ?? ""}`;
+        if (this.noticesSeen.has(key))
+            return;
+        this.noticesSeen.add(key);
+        if (this.onNotice)
+            this.onNotice(n);
+        else
+            process.emitWarning(`${n.message ?? n.code} ${n.fix ?? ""}`.trim(), { code: "PROMIGENCE_NOTICE" });
+    }
+    get apiKey() {
+        return this.#apiKey;
+    }
+    get authenticated() {
+        return typeof this.#apiKey === "string" && this.#apiKey.length > 0;
+    }
+    toJSON() {
+        return { apiUrl: this.apiUrl, authenticated: this.authenticated };
+    }
+    [inspect.custom](_depth, opts) {
+        return `PromigenceClient ${inspect(this.toJSON(), opts)}`;
+    }
+    get credentialsProblem() {
+        return this.#keyRefusal;
+    }
+    preconnect() {
+        try {
+            if (this.h2 === undefined)
+                return;
+            warmTls();
+            this.h2.preconnect(this.apiUrl);
+        }
+        catch {
+        }
+    }
+    requireKey() {
+        if (this.#keyRefusal)
+            throw this.#keyRefusal;
+        if (!this.#apiKey)
+            throw new AuthError();
+        return this.#apiKey;
+    }
+    bearer() {
+        const key = this.requireKey();
+        return (this.#bearer ??= `Bearer ${key}`);
+    }
+    refusalBackoff(status, retryAfterMs, code, attempt, replayable, signal) {
+        if (attempt >= this.maxRetries || signal?.aborted)
+            return undefined;
+        const gateway = (status === 502 || status === 504) && replayable && code === undefined;
+        if (status !== 429 && status !== 503 && !gateway)
+            return undefined;
+        if ((retryAfterMs ?? 0) > MAX_RETRY_SLEEP_MS)
+            return undefined;
+        if (status === 503 && !replayable && retryAfterMs === undefined && !REFUSED_503_CODES.has(code ?? ""))
+            return undefined;
+        const jitter = Math.random();
+        return retryAfterMs !== undefined
+            ? retryAfterMs + jitter * Math.min(250, this.retryBaseMs)
+            : Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt) * (0.5 + jitter * 0.5);
+    }
+    readExtras(opts) {
+        const waitMs = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(opts.waitMs, WAIT_MS_CAP) : 0;
+        return {
+            ...(waitMs > 0 ? { timeoutMs: waitMs + this.requestTimeoutMs } : {}),
+            ...(opts.onHeaders ? { onHeaders: opts.onHeaders } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        };
+    }
+    guardDispatcher() {
+        if (!this.ownFetch || customDispatcher())
+            return undefined;
+        return guardedFetchDispatcher();
+    }
+    dispatcherFor(timeoutMs) {
+        const guarded = this.guardDispatcher();
+        if (guarded !== undefined)
+            return longRequestDispatcher(timeoutMs, guarded) ?? guarded;
+        return longRequestDispatcher(timeoutMs);
+    }
+    async request(opts) {
+        const tr = traceBegin(opts.method, opts.path);
+        const url = `${this.apiUrl}${opts.path}`;
+        const headers = {
+            accept: "application/json",
+            "user-agent": this.userAgent,
+        };
+        const extra = opts.headers;
+        if (extra !== undefined && extra !== null) {
+            for (const k of Object.keys(extra)) {
+                const name = k.toLowerCase();
+                if (name !== "authorization")
+                    headers[name] = extra[k];
+            }
+        }
+        if (this.caller)
+            headers[CALLER_HEADER] = this.caller;
+        if (!opts.anonymous)
+            headers["authorization"] = this.bearer();
+        if (opts.body !== undefined)
+            headers["content-type"] = "application/json";
+        const keyedCreate = isKeyedCreate(opts.method, opts.path);
+        const idempotencyKey = opts.idempotencyKey ?? (keyedCreate ? newIdempotencyKey() : undefined);
+        if (idempotencyKey)
+            headers["idempotency-key"] = idempotencyKey;
+        const replayable = opts.method === "GET" || opts.method === "DELETE" || (keyedCreate && Boolean(idempotencyKey));
+        const again = async (attempt) => {
+            if (!keyedCreate || !idempotencyKey || attempt >= this.maxRetries || opts.signal?.aborted)
+                return false;
+            this.stats.retries++;
+            const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
+            await sleep(backoff * (0.5 + Math.random() * 0.5));
+            return true;
+        };
+        const timeoutMs = opts.timeoutMs ?? this.requestTimeoutMs;
+        const dispatcher = this.dispatcherFor(timeoutMs);
+        let resentDelete = false;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            this.stats.requests++;
+            const sentAt = performance.now();
+            try {
+                if (this.h2) {
+                    const init = { method: opts.method, headers, timeoutMs };
+                    if (opts.signal !== undefined)
+                        init.signal = opts.signal;
+                    if (opts.body !== undefined)
+                        init.body = JSON.stringify(opts.body);
+                    if (dispatcher !== undefined)
+                        init.dispatcher = dispatcher;
+                    if (tr !== undefined) {
+                        init.trace = tr;
+                        mark(tr, "init");
+                    }
+                    res = await this.h2.fetch(url, init, replayable);
+                }
+                else {
+                    const signals = [AbortSignal.timeout(timeoutMs)];
+                    if (opts.signal)
+                        signals.push(opts.signal);
+                    const init = {
+                        method: opts.method,
+                        headers,
+                        signal: signals.length === 1 ? signals[0] : AbortSignal.any(signals),
+                        ...(opts.body === undefined ? {} : { body: JSON.stringify(opts.body) }),
+                        ...(dispatcher === undefined ? {} : { dispatcher }),
+                    };
+                    if (tr !== undefined)
+                        mark(tr, "init");
+                    res = await this.fetchImpl(url, init);
+                }
+                if (tr !== undefined)
+                    mark(tr, "res");
+                this.lastTiming = {
+                    method: opts.method,
+                    path: opts.path,
+                    totalMs: performance.now() - sentAt,
+                    ourMs: serverAppMs(headerOf(res, "server-timing")),
+                };
+                this.onTiming?.(this.lastTiming);
+            }
+            catch (err) {
+                const e = err;
+                if (await again(attempt))
+                    continue;
+                const cutOff = e?.cause?.code === "UND_ERR_HEADERS_TIMEOUT" || e?.cause?.code === "UND_ERR_BODY_TIMEOUT";
+                const timedOut = e?.name === "TimeoutError" || e?.name === "AbortError" || cutOff;
+                if (!timedOut && replayable && attempt < this.maxRetries && !opts.signal?.aborted) {
+                    this.stats.retries++;
+                    if (opts.method === "DELETE")
+                        resentDelete = true;
+                    const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
+                    await sleep(backoff * (0.5 + Math.random() * 0.5));
+                    continue;
+                }
+                if (opts.signal?.aborted) {
+                    throw new TimeoutError(`request ${opts.method} ${opts.path} was aborted by the caller's signal`, "Nothing to fix: the caller aborted it.");
+                }
+                if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+                    throw new TimeoutError(`request ${opts.method} ${opts.path} timed out after ${timeoutMs} ms`, "Retry. To allow longer: promigence --request-timeout 120s <command>, " +
+                        "PROMIGENCE_REQUEST_TIMEOUT=120s, or requestTimeoutMs in the SDK. A --wait is bounded " +
+                        "by --wait-timeout and survives a slow request on its own.");
+                }
+                const code = e?.cause?.code;
+                if (code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_BODY_TIMEOUT") {
+                    throw new TimeoutError(`request ${opts.method} ${opts.path} was cut off by the HTTP client (${code}) inside its ${timeoutMs} ms bound`, "Raise headersTimeout and bodyTimeout on the undici dispatcher this process installed " +
+                        "to at least the request's bound, or retry.");
+                }
+                throw new UnreachableError(`cannot reach ${url}: ${transportDetail(e)}`);
+            }
+            const retryAfterMs = parseRetryAfter(headerOf(res, "retry-after"));
+            const gateway = (res.status === 502 || res.status === 504) && replayable;
+            let retryable = (res.status === 429 || res.status === 503 || gateway) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
+            let body;
+            if (retryable && res.status === 503 && !replayable && retryAfterMs === undefined) {
+                body = await res.text().catch(() => "");
+                retryable = REFUSED_503_CODES.has(errorCodeOf(body) ?? "");
+            }
+            if (retryable && gateway) {
+                body = await res.text().catch(() => "");
+                retryable = errorCodeOf(body) === undefined;
+            }
+            if (retryable && attempt < this.maxRetries) {
+                const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
+                const jitter = Math.random();
+                const waitMs = retryAfterMs !== undefined
+                    ? retryAfterMs + jitter * Math.min(250, this.retryBaseMs)
+                    : backoff * (0.5 + jitter * 0.5);
+                this.stats.retries++;
+                if (gateway && opts.method === "DELETE")
+                    resentDelete = true;
+                if (body === undefined)
+                    try {
+                        await res.text();
+                    }
+                    catch { }
+                await sleep(waitMs);
+                continue;
+            }
+            if (tr !== undefined)
+                mark(tr, "hdrs");
+            let text;
+            if (body !== undefined)
+                text = body;
+            else if (res.status === 204)
+                text = "";
+            else {
+                try {
+                    text = res instanceof H2Response ? res.textNow() : await res.text();
+                }
+                catch (err) {
+                    if (!res.ok)
+                        text = "";
+                    else {
+                        const e = err;
+                        const timedOut = e?.name === "TimeoutError" || e?.name === "AbortError";
+                        if (!timedOut && replayable && attempt < this.maxRetries && !opts.signal?.aborted) {
+                            this.stats.retries++;
+                            if (opts.method === "DELETE")
+                                resentDelete = true;
+                            const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
+                            await sleep(backoff * (0.5 + Math.random() * 0.5));
+                            continue;
+                        }
+                        if (timedOut) {
+                            throw new TimeoutError(`request ${opts.method} ${opts.path} timed out after ${timeoutMs} ms while its answer was arriving`, "Retry. To allow longer: promigence --request-timeout 120s <command>, " +
+                                "PROMIGENCE_REQUEST_TIMEOUT=120s, or requestTimeoutMs in the SDK.");
+                        }
+                        throw new UnreachableError(`the connection to ${url} was lost while the answer to ${opts.method} ${opts.path} was arriving: ${transportDetail(e)}`);
+                    }
+                }
+            }
+            if (tr !== undefined)
+                mark(tr, "txt");
+            let payload = {};
+            if (!res.ok) {
+                try {
+                    payload = text ? JSON.parse(text) : {};
+                }
+                catch { }
+            }
+            if (res.status === 409 && keyedCreate && payload.error?.code === "idempotency_key_in_use" &&
+                attempt < this.maxRetries && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS) {
+                this.stats.retries++;
+                await sleep((retryAfterMs ?? this.retryBaseMs) + Math.random() * Math.min(250, this.retryBaseMs));
+                continue;
+            }
+            opts.onHeaders?.(res.headers);
+            this.observeNotice(headerOf(res, NOTICE_HEADER));
+            if (res.status === 404 && opts.method === "DELETE" &&
+                (resentDelete || (res instanceof H2Response && res.replayed))) {
+                if (tr !== undefined)
+                    mark(tr, "ret");
+                return { ok: true, deleted: true, already_gone: true };
+            }
+            if (!res.ok) {
+                const code = payload.error?.code ?? codeForStatus(res.status);
+                const message = payload.error?.message ?? `HTTP ${res.status} from ${opts.method} ${opts.path}`;
+                const fix = payload.error?.fix ?? (code === "internal"
+                    ? "Not your fault. Re-run; if it repeats, include the request_id when reporting."
+                    : "See the API response for details.");
+                const extra = { status: res.status, ...bodyExtra(payload), cli: this.cliErrors };
+                const rid = headerOf(res, "request-id") ?? headerOf(res, "x-request-id");
+                if (rid)
+                    extra.requestId = rid;
+                if (retryAfterMs !== undefined)
+                    extra.retryAfterMs = retryAfterMs;
+                throw errorFor(code, message, fix, extra);
+            }
+            if (!text) {
+                if (tr !== undefined)
+                    mark(tr, "ret");
+                return undefined;
+            }
+            try {
+                const parsed = JSON.parse(text);
+                if (tr !== undefined)
+                    mark(tr, "ret");
+                return parsed;
+            }
+            catch {
+                throw new ApiError({
+                    code: "internal",
+                    message: `${opts.method} ${opts.path} returned non-JSON (${res.status})`,
+                    fix: "The API must answer JSON; check PROMIGENCE_API_URL points at /v1.",
+                    exitCode: 1,
+                    status: res.status,
+                });
+            }
+        }
+    }
+    async bytes(method, path, body, opts = {}) {
+        const url = `${this.apiUrl}${path}`;
+        const headers = {
+            accept: "application/octet-stream, application/json",
+            "user-agent": this.userAgent,
+            authorization: `Bearer ${this.requireKey()}`,
+        };
+        if (this.caller)
+            headers[CALLER_HEADER] = this.caller;
+        if (body !== undefined)
+            headers["content-type"] = "application/octet-stream";
+        const signals = [AbortSignal.timeout(opts.timeoutMs ?? FILE_TIMEOUT_MS)];
+        if (opts.signal)
+            signals.push(opts.signal);
+        const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+        const dispatcher = this.guardDispatcher();
+        for (let attempt = 0;; attempt++) {
+            let res;
+            this.stats.requests++;
+            try {
+                res = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    signal,
+                    ...(body === undefined ? {} : { body: body }),
+                    ...(dispatcher === undefined ? {} : { dispatcher }),
+                });
+            }
+            catch (err) {
+                const e = err;
+                if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+                    throw new TimeoutError(`${method} ${path} timed out after ${opts.timeoutMs ?? FILE_TIMEOUT_MS} ms`, "Retry; for a large artefact raise timeoutMs, or fetch it in ranges.");
+                }
+                throw new UnreachableError(`cannot reach ${url}: ${transportDetail(e)}`);
+            }
+            const buf = new Uint8Array(await res.arrayBuffer());
+            if (res.ok)
+                return buf;
+            let payload = {};
+            try {
+                payload = JSON.parse(new TextDecoder().decode(buf));
+            }
+            catch { }
+            const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+            const wait = this.refusalBackoff(res.status, retryAfterMs, payload.error?.code, attempt, method === "GET", opts.signal);
+            if (wait !== undefined) {
+                this.stats.retries++;
+                await sleep(wait);
+                continue;
+            }
+            const code = payload.error?.code ?? codeForStatus(res.status);
+            throw errorFor(code, payload.error?.message ?? `HTTP ${res.status} from ${method} ${path}`, payload.error?.fix ?? "See the API response for details.", {
+                status: res.status,
+                ...bodyExtra(payload),
+                ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+            });
+        }
+    }
+    async stream(path, onChunk, opts = {}) {
+        const url = `${this.apiUrl}${path}`;
+        const headers = {
+            accept: "application/octet-stream, application/json",
+            "user-agent": this.userAgent,
+            authorization: `Bearer ${this.requireKey()}`,
+        };
+        if (this.caller)
+            headers[CALLER_HEADER] = this.caller;
+        const signals = [AbortSignal.timeout(opts.timeoutMs ?? FILE_TIMEOUT_MS)];
+        if (opts.signal)
+            signals.push(opts.signal);
+        const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+        const timedOut = () => new TimeoutError(`GET ${path} timed out after ${opts.timeoutMs ?? FILE_TIMEOUT_MS} ms`, "Retry; for a large artefact raise timeoutMs.");
+        const dispatcher = this.guardDispatcher();
+        for (let attempt = 0;; attempt++) {
+            let res;
+            this.stats.requests++;
+            try {
+                res = await this.fetchImpl(url, { method: "GET", headers, signal, ...(dispatcher === undefined ? {} : { dispatcher }) });
+            }
+            catch (err) {
+                const e = err;
+                if (e?.name === "TimeoutError" || e?.name === "AbortError")
+                    throw timedOut();
+                throw new UnreachableError(`cannot reach ${url}: ${transportDetail(e)}`);
+            }
+            if (res.ok) {
+                let total = 0;
+                if (!res.body)
+                    return { bytes: 0 };
+                const reader = res.body.getReader();
+                try {
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        if (value && value.length) {
+                            total += value.length;
+                            await onChunk(value);
+                        }
+                    }
+                }
+                catch (err) {
+                    const e = err;
+                    if (e?.name === "TimeoutError" || e?.name === "AbortError")
+                        throw timedOut();
+                    throw new UnreachableError(`the download of ${path} broke off after ${total} bytes: ${transportDetail(err)}`);
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                return { bytes: total };
+            }
+            const buf = new Uint8Array(await res.arrayBuffer());
+            let payload = {};
+            try {
+                payload = JSON.parse(new TextDecoder().decode(buf));
+            }
+            catch { }
+            const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+            const wait = this.refusalBackoff(res.status, retryAfterMs, payload.error?.code, attempt, true, opts.signal);
+            if (wait !== undefined) {
+                this.stats.retries++;
+                await sleep(wait);
+                continue;
+            }
+            const code = payload.error?.code ?? codeForStatus(res.status);
+            throw errorFor(code, payload.error?.message ?? `HTTP ${res.status} from GET ${path}`, payload.error?.fix ?? "See the API response for details.", {
+                status: res.status,
+                ...bodyExtra(payload),
+                ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+            });
+        }
+    }
+    health(opts = {}) {
+        return this.request({
+            method: "GET",
+            path: "/health",
+            anonymous: true,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+        });
+    }
+    status(opts = {}) {
+        return this.request({
+            method: "GET",
+            path: "/status",
+            anonymous: true,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+        });
+    }
+    async pricing(opts = {}) {
+        if (opts.newAccount === true) {
+            throw new InvalidArgumentError("pricing({ newAccount: true }) is no longer supported: the price list needs a key", "Call pricing() with your API key for your organization's prices. The published list prices are on the pricing page, and `promigence pricing` prints them without a key.");
+        }
+        this.requireKey();
+        return this.request({
+            method: "GET",
+            path: "/pricing",
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+        });
+    }
+    templates = {
+        list: async (opts = {}) => {
+            const r = await this.request({
+                method: "GET",
+                path: "/templates",
+                anonymous: true,
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+            return r?.templates ?? [];
+        },
+        get: (name, opts = {}) => this.request({
+            method: "GET",
+            path: `/templates/${seg(name)}`,
+            anonymous: true,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        }),
+    };
+    me(opts = {}) {
+        return this.request({ method: "GET", path: "/me", ...(opts.signal ? { signal: opts.signal } : {}) });
+    }
+    outcomes(opts = {}) {
+        return this.request({ method: "GET", path: "/me/outcomes?period=month", ...(opts.signal ? { signal: opts.signal } : {}) });
+    }
+    billing = {
+        usage: () => this.request({ method: "GET", path: "/billing" }),
+        ledger: async (limit = 100) => (await this.billing.ledgerPage({ limit })).items,
+        ledgerPage: async (opts = {}) => {
+            const limit = opts.limit ?? 100;
+            const r = await this.request({ method: "GET", path: `/me/ledger?${pageQuery(limit, 1000, opts.cursor)}` });
+            return pageOf(r, "entries", limit);
+        },
+        historyPage: async (opts = {}) => {
+            const limit = opts.limit ?? 50;
+            const q = new URLSearchParams(pageQuery(limit, 100, opts.cursor));
+            if (opts.kind !== undefined && opts.kind !== "all")
+                q.set("kind", opts.kind);
+            const r = await this.request({ method: "GET", path: `/billing/history?${q.toString()}` });
+            return pageOf(r, "entries", limit);
+        },
+        checkout: () => this.request({ method: "POST", path: "/billing/checkout", body: {} }),
+        portal: () => this.request({ method: "POST", path: "/billing/portal", body: {} }),
+        referrals: () => this.request({ method: "GET", path: "/referrals" }),
+        applyReferral: (code) => this.request({ method: "POST", path: "/referrals/apply", body: { code } }),
+    };
+    keys = {
+        list: async (opts = {}) => {
+            const r = await this.request({ method: "GET", path: `/keys${opts.all ? "?all=1" : ""}` });
+            return r?.keys ?? [];
+        },
+        create: (opts = {}) => {
+            const body = { ...expiryFields(opts) };
+            if (opts.name !== undefined)
+                body["name"] = opts.name.slice(0, 64);
+            return this.request({ method: "POST", path: "/keys", body });
+        },
+        revoke: (keyId) => {
+            if (!keyId?.trim())
+                throw new InvalidArgumentError("keys.revoke needs a key id", "Pass a key_id from keys.list().");
+            return this.request({ method: "DELETE", path: `/keys/${encodeURIComponent(keyId)}` });
+        },
+    };
+    orgs = {
+        list: async () => {
+            const r = await this.request({ method: "GET", path: "/orgs" });
+            return r?.orgs ?? [];
+        },
+        setDefault: (org) => this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/default`, body: {} }),
+        createKey: (org, opts = {}) => {
+            const body = { ...expiryFields(opts) };
+            if (opts.name !== undefined)
+                body["name"] = opts.name.slice(0, 64);
+            if (opts.project !== undefined)
+                body["project"] = opts.project;
+            return this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/keys`, body });
+        },
+        members: async (org) => {
+            const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/members` });
+            return r?.members ?? [];
+        },
+        invites: async (org) => {
+            const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/invites` });
+            return r?.invites ?? [];
+        },
+        leave: (org) => this.request({ method: "DELETE", path: `/orgs/${orgSeg(org)}/members/me` }),
+        projects: {
+            list: async (org) => {
+                const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/projects` });
+                return r?.projects ?? [];
+            },
+            create: (org, name) => this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/projects`, body: { name } }),
+            rename: (org, project, name) => this.request({
+                method: "PATCH", path: `/orgs/${orgSeg(org)}/projects/${encodeURIComponent(project)}`, body: { name },
+            }),
+        },
+    };
+    credits = {
+        offer: () => this.request({ method: "GET", path: "/credits/offer" }),
+    };
+    github = {
+        status: () => this.request({ method: "GET", path: "/integrations/github" }),
+        connect: () => this.request({ method: "POST", path: "/integrations/github/connect", body: {} }),
+        ticket: () => this.request({ method: "POST", path: "/integrations/github/requests", body: {} }),
+        request: (requestId) => this.request({
+            method: "GET",
+            path: `/integrations/github/requests/${encodeURIComponent(requestId)}`,
+        }),
+        disconnect: (installationId) => this.request({
+            method: "DELETE",
+            path: `/integrations/github/installations/${encodeURIComponent(String(installationId))}`,
+        }),
+        repos: (opts = {}) => {
+            const q = new URLSearchParams();
+            if (opts.page !== undefined)
+                q.set("page", String(Math.max(1, Math.floor(opts.page))));
+            if (opts.perPage !== undefined)
+                q.set("per_page", String(Math.min(100, Math.max(1, Math.floor(opts.perPage)))));
+            const qs = q.toString();
+            return this.request({ method: "GET", path: `/integrations/github/repos${qs ? `?${qs}` : ""}` });
+        },
+        untrack: (trackId) => this.request({ method: "DELETE", path: `/integrations/github/tracks/${encodeURIComponent(trackId)}` }),
+    };
+    gitlab = {
+        status: () => this.request({ method: "GET", path: "/integrations/gitlab" }),
+        connect: () => this.request({ method: "POST", path: "/integrations/gitlab/connect", body: {} }),
+        ticket: () => this.request({ method: "POST", path: "/integrations/gitlab/requests", body: {} }),
+        request: (requestId) => this.request({
+            method: "GET",
+            path: `/integrations/gitlab/requests/${encodeURIComponent(requestId)}`,
+        }),
+        disconnect: (connectionId) => this.request({
+            method: "DELETE",
+            path: `/integrations/gitlab/connections/${encodeURIComponent(connectionId)}`,
+        }),
+        repos: (opts = {}) => {
+            const q = new URLSearchParams();
+            if (opts.page !== undefined)
+                q.set("page", String(Math.max(1, Math.floor(opts.page))));
+            if (opts.perPage !== undefined)
+                q.set("per_page", String(Math.min(100, Math.max(1, Math.floor(opts.perPage)))));
+            if (opts.connectionId !== undefined)
+                q.set("connection_id", opts.connectionId);
+            const qs = q.toString();
+            return this.request({ method: "GET", path: `/integrations/gitlab/repos${qs ? `?${qs}` : ""}` });
+        },
+        untrack: (trackId) => this.request({ method: "DELETE", path: `/integrations/gitlab/tracks/${encodeURIComponent(trackId)}` }),
+    };
+    runs = {
+        start: (opts) => {
+            if (!opts.snapshot)
+                throw new InvalidArgumentError("runs.start needs a snapshot", "Pass { snapshot: 'snap_… | alias | alias@commit7' }.");
+            if (!Number.isInteger(opts.count) || opts.count < 1)
+                throw new InvalidArgumentError("runs.start needs count >= 1", "Pass { count: 1 } or more.");
+            const body = { snapshot: opts.snapshot, count: opts.count };
+            if (opts.timeoutMs !== undefined)
+                body["timeout_ms"] = opts.timeoutMs;
+            if (opts.spendCap !== undefined)
+                body["spend_cap"] = checkSpendCap(opts.spendCap);
+            if (opts.allowPartial !== undefined)
+                body["allow_partial"] = opts.allowPartial;
+            if (opts.verifyEach !== undefined)
+                body["verify_each"] = opts.verifyEach;
+            if (opts.network !== undefined)
+                body["network"] = opts.network;
+            if (opts.optimizeFor !== undefined)
+                body["optimize_for"] = opts.optimizeFor;
+            if (opts.secrets?.length)
+                body["secrets"] = opts.secrets;
+            if (opts.labels && Object.keys(opts.labels).length)
+                body["labels"] = opts.labels;
+            if (opts.exec) {
+                const e = {};
+                if (opts.exec.argv)
+                    e["argv"] = opts.exec.argv;
+                if (opts.exec.sh)
+                    e["sh"] = opts.exec.sh;
+                if (opts.exec.cwd)
+                    e["cwd"] = opts.exec.cwd;
+                if (opts.exec.env)
+                    e["env"] = opts.exec.env;
+                const t = commandTimeoutMs(opts.exec.timeoutMs);
+                if (t !== undefined)
+                    e["timeout_ms"] = t;
+                if (opts.exec.maxOutputBytes !== undefined)
+                    e["max_output_bytes"] = opts.exec.maxOutputBytes;
+                e["kill_on_exit"] = opts.exec.killOnExit ?? true;
+                body["exec"] = e;
+            }
+            if (opts.grade) {
+                if (!opts.grade.cmd)
+                    throw new InvalidArgumentError("runs.start grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
+                const g = { cmd: opts.grade.cmd };
+                if (opts.grade.holdoutCmd)
+                    g["holdout_cmd"] = opts.grade.holdoutCmd;
+                if (opts.grade.timeoutMs !== undefined)
+                    g["timeout_ms"] = opts.grade.timeoutMs;
+                if (opts.grade.score !== undefined)
+                    g["score"] = opts.grade.score;
+                body["grade"] = g;
+            }
+            if (opts.gradeOutput !== undefined)
+                body["grade_output"] = opts.gradeOutput;
+            const waitMs = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(opts.waitMs, WAIT_MS_CAP) : 0;
+            const req = { method: "POST", path: `/runs${waitQuery(waitMs)}`, body };
+            if (waitMs > 0)
+                req.timeoutMs = waitMs + this.requestTimeoutMs;
+            if (opts.idempotencyKey)
+                req.idempotencyKey = opts.idempotencyKey;
+            if (opts.signal)
+                req.signal = opts.signal;
+            return this.request(req);
+        },
+        get: (runId, opts = {}) => this.request({
+            method: "GET",
+            path: `/runs/${encodeURIComponent(runId)}${waitQuery(opts.waitMs)}`,
+            ...this.readExtras(opts),
+        }),
+        list: async (limit = 20) => (await this.runs.listPage({ limit })).items,
+        listPage: async (opts = {}) => {
+            const limit = opts.limit ?? 20;
+            const r = await this.request({ method: "GET", path: `/runs?${pageQuery(limit, 500, opts.cursor)}` });
+            return pageOf(r, "runs", limit);
+        },
+        status: (runId, opts = {}) => this.runs.get(runId, opts),
+        sandboxes: async (runId, opts = {}) => {
+            const r = await this.runs.sandboxesWithCapacity(runId, opts);
+            return r.sandboxes;
+        },
+        sandboxesWithCapacity: async (runId, opts = {}) => {
+            const r = await this.request({
+                method: "GET",
+                path: `/runs/${encodeURIComponent(runId)}/sandboxes${waitQuery(opts.waitMs)}`,
+                ...this.readExtras(opts),
+            });
+            if (Array.isArray(r))
+                return { sandboxes: r };
+            const sandboxes = r?.sandboxes ?? [];
+            return r?.capacity ? { sandboxes, capacity: r.capacity } : { sandboxes };
+        },
+        report: (runId) => this.request({ method: "GET", path: `/runs/${encodeURIComponent(runId)}/report` }),
+        cancel: (runId) => this.request({ method: "POST", path: `/runs/${encodeURIComponent(runId)}/cancel`, body: {} }),
+        kill: (runId) => this.request({ method: "DELETE", path: `/runs/${encodeURIComponent(runId)}` }),
+        quote: (opts) => {
+            if (!opts.snapshot)
+                throw new InvalidArgumentError("runs.quote needs a snapshot", "Pass { snapshot: 'snap_… | alias | alias@commit7' }.");
+            if (!Number.isInteger(opts.count) || opts.count < 1)
+                throw new InvalidArgumentError("runs.quote needs count >= 1", "Pass { count: 1 } or more.");
+            const body = { snapshot: opts.snapshot, count: opts.count };
+            if (opts.timeoutMs !== undefined)
+                body["timeout_ms"] = opts.timeoutMs;
+            if (opts.tier !== undefined)
+                body["tier"] = opts.tier;
+            if (opts.spendCap !== undefined)
+                body["spend_cap"] = checkSpendCap(opts.spendCap);
+            return this.request({ method: "POST", path: "/runs/quote", body });
+        },
+        replay: (runId, sandboxIds, opts = {}) => this.request({
+            method: "POST",
+            path: `/runs/${encodeURIComponent(runId)}/replay`,
+            body: {
+                ...(sandboxIds?.length ? { sandbox_ids: sandboxIds } : {}),
+                ...(opts.env && Object.keys(opts.env).length ? { env: opts.env } : {}),
+            },
+        }),
+        captures: (runId) => this.request({
+            method: "GET",
+            path: `/runs/${encodeURIComponent(runId)}/captures`,
+        }),
+        open: (runId, opts = {}) => {
+            const body = {};
+            if (opts.sandboxId !== undefined)
+                body["sandbox_id"] = opts.sandboxId;
+            if (opts.spendCap !== undefined)
+                body["spend_cap"] = opts.spendCap;
+            if (opts.timeoutMs !== undefined)
+                body["timeout_ms"] = opts.timeoutMs;
+            return this.request({
+                method: "POST",
+                path: `/runs/${encodeURIComponent(runId)}/open`,
+                body,
+            });
+        },
+        waitReady: async (runId, opts = {}) => {
+            const seen = new Set();
+            const progress = opts.onReady !== undefined || opts.onCapacity !== undefined;
+            const r = await this.waitLoop(opts, progress ? PROGRESS_POLL_MS : LONG_POLL_MS, [], async (read) => {
+                const { sandboxes, capacity } = await this.runs.sandboxesWithCapacity(runId, read);
+                if (capacity)
+                    opts.onCapacity?.(capacity);
+                return sandboxes;
+            }, (sandboxes) => {
+                for (const s of sandboxes) {
+                    if (!isWaiting(s.state) && !seen.has(s.sandbox_id)) {
+                        seen.add(s.sandbox_id);
+                        opts.onReady?.(s);
+                    }
+                }
+                return sandboxes.length > 0 && sandboxes.every((s) => !isWaiting(s.state));
+            });
+            return { sandboxes: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
+        },
+        waitDone: async (runId, opts = {}) => {
+            const r = await this.waitLoop(opts, LONG_POLL_MS, { run_id: runId, state: "running" }, (read) => this.runs.get(runId, read), (run) => {
+                const terminal = run.state === "completed" || run.state === "cap_killed" || run.state === "aborted";
+                const allDone = Array.isArray(run.sandboxes) && run.sandboxes.length > 0 &&
+                    run.sandboxes.every((s) => s.state === "ended" || s.command_outcome != null);
+                return terminal || allDone;
+            });
+            return { run: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
+        },
+    };
+    async waitLoop(opts, maxWaitMs, empty, read, done) {
+        const bound = opts.waitTimeoutMs ?? WAIT_TIMEOUT_MS;
+        const started = Date.now();
+        let longPoll = opts.pollMs === undefined;
+        let unmarkedFast = 0;
+        let value = empty;
+        for (let i = 0;; i++) {
+            const waitMs = longPoll ? Math.max(0, Math.min(bound - (Date.now() - started), maxWaitMs)) : 0;
+            let parked;
+            const t0 = Date.now();
+            const readOpts = {
+                ...(waitMs > 0 ? { waitMs } : {}),
+                onHeaders: (h) => {
+                    const v = h.get(WAITED_HEADER);
+                    if (v !== null)
+                        parked = Number(v);
+                },
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            };
+            let timedOutRead = false;
+            let comeBackMs = 0;
+            try {
+                value = await keepingLoopAwake(waitMs > 0 ? PARKED_TICK_MS : POLLING_TICK_MS, () => read(readOpts));
+            }
+            catch (err) {
+                const elapsedNow = Date.now() - started;
+                const refused = err instanceof RateLimitError ||
+                    (err instanceof PromigenceError && err.status === 503 && REFUSED_503_CODES.has(err.code));
+                if (!(err instanceof TimeoutError || refused) || elapsedNow >= bound || opts.signal?.aborted)
+                    throw err;
+                timedOutRead = true;
+                if (refused)
+                    comeBackMs = err.retryAfterMs ?? 0;
+            }
+            const roundTripMs = Date.now() - t0;
+            if (!timedOutRead && done(value))
+                return { value, timedOut: false, waitedMs: Date.now() - started };
+            const elapsed = Date.now() - started;
+            if (elapsed >= bound || opts.signal?.aborted)
+                return { value, timedOut: true, waitedMs: elapsed };
+            if (timedOutRead) {
+                await sleep(Math.min(Math.max(comeBackMs, opts.pollMs ?? pollInterval(i)), Math.max(1, bound - elapsed)));
+                continue;
+            }
+            if (waitMs > 0 && parked === undefined && roundTripMs < waitMs / 2 && ++unmarkedFast >= 2) {
+                longPoll = false;
+            }
+            const served = parked !== undefined && parked >= Math.min(Math.floor(waitMs), WAIT_MS_CAP);
+            if (served)
+                continue;
+            await sleep(Math.min(opts.pollMs ?? pollInterval(i), Math.max(1, bound - elapsed)));
+        }
+    }
+    sandboxes = {
+        exec: (sandboxId, opts) => {
+            if (!opts.argv?.length && !opts.sh) {
+                throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['bun','typecheck'] } or { sh: 'bun typecheck' }.");
+            }
+            const body = {};
+            if (opts.argv?.length)
+                body["argv"] = opts.argv;
+            if (opts.sh)
+                body["sh"] = opts.sh;
+            if (opts.cwd)
+                body["cwd"] = opts.cwd;
+            if (opts.env)
+                body["env"] = opts.env;
+            if (opts.user)
+                body["user"] = opts.user;
+            if (opts.secrets?.length)
+                body["secrets"] = opts.secrets;
+            if (opts.terminal)
+                body["terminal"] = true;
+            if (opts.killOnExit !== undefined)
+                body["kill_on_exit"] = opts.killOnExit;
+            const timeoutMs = commandTimeoutMs(opts.timeoutMs) ?? 15 * 60_000;
+            body["timeout_ms"] = timeoutMs;
+            body["max_output_bytes"] = opts.maxOutputBytes ?? MAX_OUTPUT_BYTES_DEFAULT;
+            if (opts.encoding === "base64")
+                body["encoding"] = "base64";
+            const req = {
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
+                body,
+                timeoutMs: timeoutMs + 30_000,
+            };
+            if (opts.idempotencyKey)
+                req.idempotencyKey = opts.idempotencyKey;
+            if (opts.signal)
+                req.signal = opts.signal;
+            return this.request(req);
+        },
+        execStream: async (sandboxId, opts, on = {}) => {
+            if (!opts.argv?.length && !opts.sh) {
+                throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['bun','typecheck'] } or { sh: 'bun typecheck' }.");
+            }
+            if (opts.idempotencyKey) {
+                throw new InvalidArgumentError("a streamed exec cannot take an idempotencyKey (its output cannot be replayed)", "Use sandboxes.exec (buffered) or sandboxes.execBackground with the key, or stream without one.");
+            }
+            const body = {};
+            if (opts.argv?.length)
+                body["argv"] = opts.argv;
+            if (opts.sh)
+                body["sh"] = opts.sh;
+            if (opts.cwd)
+                body["cwd"] = opts.cwd;
+            if (opts.env)
+                body["env"] = opts.env;
+            if (opts.user)
+                body["user"] = opts.user;
+            if (opts.secrets?.length)
+                body["secrets"] = opts.secrets;
+            if (opts.terminal)
+                body["terminal"] = true;
+            if (opts.killOnExit !== undefined)
+                body["kill_on_exit"] = opts.killOnExit;
+            body["timeout_ms"] = commandTimeoutMs(opts.timeoutMs) ?? 15 * 60_000;
+            body["max_output_bytes"] = opts.maxOutputBytes ?? MAX_OUTPUT_BYTES_DEFAULT;
+            const url = `${this.apiUrl}/sandboxes/${encodeURIComponent(sandboxId)}/execs`;
+            const idle = new AbortController();
+            let silent = false;
+            let reader;
+            let timer;
+            const arm = () => {
+                clearTimeout(timer);
+                timer = setTimeout(() => {
+                    silent = true;
+                    idle.abort();
+                    reader?.cancel().catch(() => { });
+                }, STREAM_IDLE_MS);
+            };
+            let stream;
+            const bearer = `Bearer ${this.requireKey()}`;
+            const dispatcher = this.guardDispatcher();
+            for (let attempt = 0; stream === undefined; attempt++) {
+                let r;
+                this.stats.requests++;
+                arm();
+                try {
+                    r = await this.fetchImpl(url, {
+                        method: "POST",
+                        headers: {
+                            accept: "text/event-stream",
+                            "content-type": "application/json",
+                            "user-agent": this.userAgent,
+                            authorization: bearer,
+                            ...(this.caller ? { [CALLER_HEADER]: this.caller } : {}),
+                        },
+                        body: JSON.stringify(body),
+                        signal: opts.signal ? AbortSignal.any([opts.signal, idle.signal]) : idle.signal,
+                        ...(dispatcher === undefined ? {} : { dispatcher }),
+                    });
+                }
+                catch (err) {
+                    clearTimeout(timer);
+                    const e = err;
+                    const why = silent ? `no answer in ${STREAM_IDLE_MS / 1000} s` : transportDetail(e);
+                    throw new UnreachableError(`cannot reach ${url}: ${why}`);
+                }
+                if (r.ok && r.body) {
+                    stream = r.body;
+                    break;
+                }
+                clearTimeout(timer);
+                const text = await r.text().catch(() => "");
+                let payload = {};
+                try {
+                    payload = text ? JSON.parse(text) : {};
+                }
+                catch { }
+                const retryAfterMs = parseRetryAfter(r.headers.get("retry-after"));
+                const wait = this.refusalBackoff(r.status, retryAfterMs, payload.error?.code, attempt, false, opts.signal);
+                if (wait !== undefined) {
+                    this.stats.retries++;
+                    await sleep(wait);
+                    continue;
+                }
+                const code = payload.error?.code ?? codeForStatus(r.status);
+                throw errorFor(code, payload.error?.message ?? `HTTP ${r.status} from POST /sandboxes/${sandboxId}/execs`, payload.error?.fix ?? "See the API response for details.", {
+                    status: r.status,
+                    ...bodyExtra(payload),
+                    ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                });
+            }
+            const out = [];
+            const errOut = [];
+            let exit;
+            let failure;
+            const dec = new TextDecoder();
+            let buf = "";
+            const lost = (how) => new UnreachableError(`the exec stream for sandbox ${sandboxId} ${how}`, "The connection dropped before the command finished; its result is unknown. " +
+                `Read it by id (\`promigence exec output <exec_id> --sandbox ${hintArg(sandboxId)}\`) or re-run.`);
+            reader = stream.getReader();
+            try {
+                for (;;) {
+                    arm();
+                    let chunk;
+                    try {
+                        chunk = await reader.read();
+                    }
+                    catch (err) {
+                        if (opts.signal?.aborted)
+                            throw err;
+                        if (silent)
+                            throw lost(`was silent for ${STREAM_IDLE_MS / 1000} s`);
+                        const e = err;
+                        throw lost(`was cut off (${e?.cause?.code ?? e?.message ?? "connection lost"})`);
+                    }
+                    if (chunk.done)
+                        break;
+                    const value = chunk.value;
+                    buf += dec.decode(value, { stream: true });
+                    let sep;
+                    while ((sep = buf.indexOf("\n\n")) >= 0) {
+                        const block = buf.slice(0, sep);
+                        buf = buf.slice(sep + 2);
+                        let event = "";
+                        let data = "";
+                        for (const line of block.split("\n")) {
+                            if (line.startsWith("event:"))
+                                event = line.slice(6).trim();
+                            else if (line.startsWith("data:"))
+                                data = line.slice(5).replace(/^ /, "");
+                        }
+                        if (!event)
+                            continue;
+                        if (event === "heartbeat") {
+                            on.heartbeat?.();
+                            continue;
+                        }
+                        if (event === "reconnect") {
+                            reader.cancel().catch(() => { });
+                            throw new ServiceRestartError(`a service restart stopped the command on sandbox ${sandboxId} while its output was streaming`, "Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe.");
+                        }
+                        let parsed = {};
+                        try {
+                            parsed = JSON.parse(data);
+                        }
+                        catch { }
+                        if (event === "stdout" || event === "stderr") {
+                            const bytes = b64ToBytes(String(parsed["data"] ?? ""));
+                            if (event === "stdout") {
+                                out.push(bytes);
+                                on.stdout?.(bytes);
+                            }
+                            else {
+                                errOut.push(bytes);
+                                on.stderr?.(bytes);
+                            }
+                        }
+                        else if (event === "exit") {
+                            exit = { ...(exit ?? {}), ...parsed };
+                        }
+                        else if (event === "error") {
+                            failure = parsed;
+                        }
+                    }
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (failure) {
+                throw errorFor(failure.code ?? "internal", failure.message ?? "the exec stream failed", failure.fix ?? "Re-run; if it repeats, include the exec_id.", { status: 200, ...bodyExtra({ error: failure }) });
+            }
+            if (!exit && silent)
+                throw lost(`was silent for ${STREAM_IDLE_MS / 1000} s`);
+            if (!exit) {
+                throw lost("ended without an exit event");
+            }
+            const rawCode = exit["exit_code"];
+            const signal = exit["signal"];
+            const exitCode = typeof rawCode === "number" && Number.isFinite(rawCode)
+                ? rawCode
+                : typeof signal === "number" && signal > 0 ? 128 + signal : null;
+            const join = (parts) => {
+                const n = parts.reduce((a, p) => a + p.length, 0);
+                const all = new Uint8Array(n);
+                let at = 0;
+                for (const p of parts) {
+                    all.set(p, at);
+                    at += p.length;
+                }
+                return new TextDecoder().decode(all);
+            };
+            return {
+                exec_id: String(exit["exec_id"] ?? ""),
+                sandbox_id: sandboxId,
+                exit_code: exitCode,
+                stdout: join(out),
+                stderr: join(errOut),
+                truncated: Boolean(exit["truncated"] ?? false),
+                ...(exit["timed_out"] === true ? { timed_out: true } : {}),
+                ...(exit["oom_killed"] === true ? { oom_killed: true } : {}),
+                ...(typeof exit["reason"] === "string" ? { reason: exit["reason"] } : {}),
+                ...(typeof signal === "number" ? { signal } : {}),
+            };
+        },
+        execBackground: (sandboxId, opts) => {
+            if (!opts.argv?.length && !opts.sh) {
+                throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['npm','run','dev'] } or { sh: 'npm run dev' }.");
+            }
+            const body = { background: true };
+            if (opts.argv?.length)
+                body["argv"] = opts.argv;
+            if (opts.sh)
+                body["sh"] = opts.sh;
+            if (opts.cwd)
+                body["cwd"] = opts.cwd;
+            if (opts.env)
+                body["env"] = opts.env;
+            if (opts.user)
+                body["user"] = opts.user;
+            if (opts.secrets?.length)
+                body["secrets"] = opts.secrets;
+            if (opts.stdin)
+                body["stdin"] = true;
+            if (opts.follow)
+                body["follow"] = true;
+            const timeoutMs = commandTimeoutMs(opts.timeoutMs);
+            if (timeoutMs !== undefined)
+                body["timeout_ms"] = timeoutMs;
+            if (opts.maxOutputBytes !== undefined)
+                body["max_output_bytes"] = opts.maxOutputBytes;
+            return this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
+                body,
+                ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+            });
+        },
+        execs: {
+            list: async (sandboxId) => {
+                const r = await this.request({
+                    method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
+                });
+                return r.execs ?? [];
+            },
+            get: (sandboxId, execId, opts = {}) => {
+                const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
+                return this.request({
+                    method: "GET",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}${wait ? `?wait_ms=${wait}` : ""}`,
+                    ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
+                    ...(opts.signal ? { signal: opts.signal } : {}),
+                });
+            },
+            read: async (sandboxId, execId, stream, opts = {}) => {
+                const q = [`stream=${stream}`, `offset=${Math.max(0, Math.floor(opts.offset ?? 0))}`];
+                if (opts.len !== undefined)
+                    q.push(`len=${Math.max(0, Math.floor(opts.len))}`);
+                const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
+                if (wait)
+                    q.push(`wait_ms=${wait}`);
+                if (wait && opts.untilOutput)
+                    q.push("until=output");
+                const r = await this.request({
+                    method: "GET",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}?${q.join("&")}`,
+                    ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
+                    ...(opts.signal ? { signal: opts.signal } : {}),
+                });
+                return { data: b64ToBytes(r.data ?? ""), offset: r.offset ?? opts.offset ?? 0, eof: Boolean(r.eof), skipped: r.skipped ?? 0, record: r };
+            },
+            stdin: (sandboxId, execId, opts = {}) => {
+                if (opts.data === undefined && !opts.eof) {
+                    throw new InvalidArgumentError("execs.stdin needs data, eof, or both", "Pass { data: 'y\\n' } to write, { eof: true } to close, or both to do each in one call.");
+                }
+                const bytes = typeof opts.data === "string" ? new TextEncoder().encode(opts.data) : opts.data;
+                return this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}/stdin`,
+                    body: {
+                        ...(bytes === undefined ? {} : { data: bytesToB64(bytes) }),
+                        ...(opts.eof ? { eof: true } : {}),
+                    },
+                });
+            },
+            signal: (sandboxId, execId, signal = "SIGTERM") => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}/signal`,
+                body: { signal },
+            }),
+            forget: (sandboxId, execId) => this.request({
+                method: "DELETE",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}`,
+            }),
+        },
+        ports: {
+            expose: (sandboxId, port) => {
+                if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                    throw new InvalidArgumentError(`port must be an integer 1..65535, got ${port}`, "Pass the port your process listens on inside the sandbox, e.g. 3000.");
+                }
+                return withPreviewsFix(this.request({
+                    method: "POST", path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports`, body: { port },
+                }), sandboxId, port);
+            },
+            list: async (sandboxId) => {
+                const r = await withPreviewsFix(this.request({
+                    method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports`,
+                }), sandboxId);
+                return r.ports ?? [];
+            },
+            revoke: (sandboxId, tokenOrPort) => this.request({
+                method: "DELETE",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/${encodeURIComponent(String(tokenOrPort))}`,
+            }),
+        },
+        ssh: {
+            open: (sandboxId, opts) => {
+                if (!opts.publicKey?.trim()) {
+                    throw new InvalidArgumentError("publicKey is required", "Pass the contents of an ssh-ed25519 .pub file, or use `promigence sandbox ssh <id>`, which makes one.");
+                }
+                return this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh`,
+                    body: {
+                        public_key: opts.publicKey.trim(),
+                        ...(opts.ttlS === undefined ? {} : { ttl_s: Math.floor(opts.ttlS) }),
+                        ...(opts.idleTimeoutS === undefined
+                            ? {}
+                            : { idle_timeout_s: Math.floor(opts.idleTimeoutS) }),
+                    },
+                });
+            },
+            list: (sandboxId) => this.request({
+                method: "GET",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh`,
+            }),
+            revoke: (sandboxId, keyIdOrFingerprint) => this.request({
+                method: "DELETE",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh/${encodeURIComponent(keyIdOrFingerprint)}`,
+            }),
+            connect: (sandboxId, opts) => connectSshTunnel({
+                url: `${this.apiUrl}/sandboxes/${encodeURIComponent(sandboxId)}/ssh/connect`,
+                token: opts.token ?? this.requireKey(),
+                userAgent: this.userAgent,
+                ...(this.caller ? { caller: this.caller } : {}),
+                onData: opts.onData,
+                onClose: opts.onClose,
+                ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                refuse: (status, text) => {
+                    let payload = {};
+                    try {
+                        payload = text ? JSON.parse(text) : {};
+                    }
+                    catch { }
+                    const code = payload.error?.code ?? (status === 0 ? "unreachable" : codeForStatus(status));
+                    return errorFor(code, payload.error?.message ?? `HTTP ${status} from the SSH tunnel`, payload.error?.fix ?? "See the API response for details.", { status, ...bodyExtra(payload) });
+                },
+            }),
+        },
+        pty: (sandboxId, opts = {}) => {
+            const q = [];
+            if (opts.cols !== undefined)
+                q.push(`cols=${Math.floor(opts.cols)}`);
+            if (opts.rows !== undefined)
+                q.push(`rows=${Math.floor(opts.rows)}`);
+            const path = `/sandboxes/${encodeURIComponent(sandboxId)}/pty${q.length ? `?${q.join("&")}` : ""}`;
+            const open = () => connectPty({
+                url: `${this.apiUrl}${path}`,
+                apiKey: this.requireKey(),
+                userAgent: this.userAgent,
+                ...(this.caller ? { caller: this.caller } : {}),
+                ...(opts.cmd ? { command: opts.cmd } : {}),
+                ...(opts.secrets?.length ? { secrets: opts.secrets } : {}),
+                ...(opts.onData ? { onData: opts.onData } : {}),
+                ...(opts.onExit ? { onExit: opts.onExit } : {}),
+                ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+                ...(opts.reconnect === undefined ? {} : { reconnect: opts.reconnect }),
+                ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
+                refuse: (status, text, retryAfter) => {
+                    let payload = {};
+                    try {
+                        payload = text ? JSON.parse(text) : {};
+                    }
+                    catch { }
+                    const code = payload.error?.code ?? (status === 0 ? "unreachable" : codeForStatus(status));
+                    const retryAfterMs = parseRetryAfter(retryAfter ?? null);
+                    return errorFor(code, payload.error?.message ?? `HTTP ${status} from GET ${path}`, payload.error?.fix ?? "See the API response for details.", {
+                        status,
+                        ...bodyExtra(payload),
+                        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                    });
+                },
+            });
+            return (async () => {
+                for (let attempt = 0;; attempt++) {
+                    try {
+                        return await open();
+                    }
+                    catch (err) {
+                        const e = err instanceof PromigenceError ? err : undefined;
+                        const wait = e ? this.refusalBackoff(e.status, e.retryAfterMs, e.code, attempt, false) : undefined;
+                        if (wait === undefined)
+                            throw err;
+                        this.stats.retries++;
+                        await sleep(wait);
+                    }
+                }
+            })();
+        },
+        get: (sandboxId) => {
+            checkSandboxId(sandboxId, "sandboxes.get");
+            return this.request({ method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}` });
+        },
+        pause: (sandboxId) => this.request({
+            method: "POST",
+            path: `/sandboxes/${encodeURIComponent(sandboxId)}/pause`,
+            body: {},
+            timeoutMs: 10 * 60_000,
+        }),
+        resume: (sandboxId, opts = {}) => this.request({
+            method: "POST",
+            path: `/sandboxes/${encodeURIComponent(sandboxId)}/resume`,
+            body: {
+                ...(opts.optimizeFor === undefined ? {} : { optimize_for: opts.optimizeFor }),
+                ...(opts.spendCap === undefined ? {} : { spend_cap: checkSpendCap(opts.spendCap) }),
+            },
+        }),
+        snapshot: (sandboxId, opts = {}) => this.request({
+            method: "POST",
+            path: `/sandboxes/${encodeURIComponent(sandboxId)}/snapshot`,
+            body: {
+                ...(opts.alias === undefined ? {} : { alias: opts.alias }),
+                ...(opts.force === undefined ? {} : { force: opts.force }),
+                ...(opts.moveAlias === undefined ? {} : { move_alias: opts.moveAlias }),
+            },
+            timeoutMs: 10 * 60_000,
+        }),
+        list: async (opts = 50) => (await this.sandboxes.listPage(opts)).items,
+        listPage: async (opts = 50) => {
+            const o = typeof opts === "number" ? { limit: opts } : opts;
+            const q = new URLSearchParams({ limit: String(Math.max(1, Math.trunc(o.limit ?? 50))) });
+            const pairs = Object.entries(o.labels ?? {});
+            if (pairs.length)
+                q.set("labels", pairs.map(([k, v]) => `${k}=${v}`).join(","));
+            if (o.state?.length)
+                q.set("state", o.state.join(","));
+            if (o.cursor)
+                q.set("cursor", o.cursor);
+            const r = await this.request({
+                method: "GET",
+                path: `/sandboxes?${q.toString()}`,
+            });
+            return { items: r.sandboxes ?? [], nextCursor: r.next_cursor ?? null, limit: r.limit ?? (o.limit ?? 50) };
+        },
+        probe: (sandboxId, opts = {}) => this.request({
+            method: "POST",
+            path: `/sandboxes/${encodeURIComponent(sandboxId)}/probe`,
+            body: opts.paths?.length ? { paths: opts.paths } : {},
+        }),
+        kill: (sandboxId) => this.request({ method: "DELETE", path: `/sandboxes/${encodeURIComponent(sandboxId)}` }),
+        network: (sandboxId) => this.request({ method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/network` }),
+        setNetworkNone: (sandboxId) => this.request({
+            method: "POST",
+            path: `/sandboxes/${encodeURIComponent(sandboxId)}/network`,
+            body: { network: "none" },
+        }),
+        patch: (sandboxId, opts) => {
+            const body = {};
+            if (opts.timeoutMs !== undefined) {
+                if (!Number.isInteger(opts.timeoutMs) || opts.timeoutMs <= 0) {
+                    throw new InvalidArgumentError("sandboxes.patch needs a positive timeoutMs", "Pass { timeoutMs: 1_800_000 }.");
+                }
+                body["timeout_ms"] = opts.timeoutMs;
+            }
+            if (opts.autoPauseS !== undefined) {
+                if (!Number.isInteger(opts.autoPauseS) || opts.autoPauseS < 0) {
+                    throw new InvalidArgumentError("sandboxes.patch needs a non-negative whole number of seconds for autoPauseS", "Pass { autoPauseS: 900 } to pause it after 15 idle minutes, or { autoPauseS: 0 } to turn that off.");
+                }
+                body["auto_pause_s"] = opts.autoPauseS;
+            }
+            if (opts.autoPauseMode !== undefined) {
+                if (opts.autoPauseMode !== "requests" && opts.autoPauseMode !== "activity") {
+                    throw new InvalidArgumentError(`sandboxes.patch: autoPauseMode must be "requests" or "activity", got ${JSON.stringify(opts.autoPauseMode)}`, 'Pass { autoPauseMode: "activity" } for an agent that runs inside the sandbox.');
+                }
+                body["auto_pause_mode"] = opts.autoPauseMode;
+            }
+            if (Object.keys(body).length === 0) {
+                throw new InvalidArgumentError("sandboxes.patch was given nothing to change", "Pass { timeoutMs } to extend it, { autoPauseS } to set its idle rule, or both.");
+            }
+            return this.request({
+                method: "PATCH",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}`,
+                body,
+            });
+        },
+        files: {
+            list: (sandboxId, path = "/", opts = {}) => {
+                const q = [`path=${encodeURIComponent(path)}`];
+                if (opts.recursive)
+                    q.push("recursive=1");
+                if (opts.depth !== undefined)
+                    q.push(`depth=${Math.max(0, Math.floor(opts.depth))}`);
+                if (opts.limit !== undefined)
+                    q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
+                if (opts.hidden === false)
+                    q.push("hidden=0");
+                return this.request({
+                    method: "GET",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/list?${q.join("&")}`,
+                });
+            },
+            search: (sandboxId, path, opts = {}) => {
+                if (!opts.pattern && !opts.contains) {
+                    throw new InvalidArgumentError("files.search needs `pattern`, `contains`, or both", "Pass { pattern: '*.py' } for a name glob, { contains: 'TODO' } for text inside files.");
+                }
+                const q = [`path=${encodeURIComponent(path)}`];
+                if (opts.pattern)
+                    q.push(`pattern=${encodeURIComponent(opts.pattern)}`);
+                if (opts.contains)
+                    q.push(`contains=${encodeURIComponent(opts.contains)}`);
+                if (opts.ignoreCase)
+                    q.push("ignore_case=1");
+                if (opts.limit !== undefined)
+                    q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
+                if (opts.hidden === false)
+                    q.push("hidden=0");
+                return this.request({
+                    method: "GET",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/search?${q.join("&")}`,
+                });
+            },
+            mkdir: (sandboxId, path, opts = {}) => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/mkdir`,
+                body: {
+                    path,
+                    ...(opts.mode === undefined ? {} : { mode: modeParam(opts.mode) }),
+                    ...(opts.parents === undefined ? {} : { parents: opts.parents }),
+                },
+            }),
+            move: (sandboxId, from, to, opts = {}) => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/move`,
+                body: { from, to, ...(opts.overwrite === undefined ? {} : { overwrite: opts.overwrite }) },
+            }),
+            copy: (sandboxId, from, to, opts = {}) => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/copy`,
+                body: {
+                    from, to,
+                    ...(opts.recursive === undefined ? {} : { recursive: opts.recursive }),
+                    ...(opts.overwrite === undefined ? {} : { overwrite: opts.overwrite }),
+                },
+            }),
+            chmod: (sandboxId, path, opts) => {
+                if (opts.mode === undefined && opts.uid === undefined && opts.gid === undefined) {
+                    throw new InvalidArgumentError("files.chmod needs one of mode, uid or gid", "Pass { mode: 0o755 }, { uid: 1000 }, { gid: 1000 }, or any combination.");
+                }
+                return this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/chmod`,
+                    body: {
+                        path,
+                        ...(opts.mode === undefined ? {} : { mode: modeParam(opts.mode) }),
+                        ...(opts.uid === undefined ? {} : { uid: opts.uid }),
+                        ...(opts.gid === undefined ? {} : { gid: opts.gid }),
+                        ...(opts.recursive === undefined ? {} : { recursive: opts.recursive }),
+                    },
+                });
+            },
+            archive: (sandboxId, path, opts = {}) => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/archive`,
+                body: {
+                    path,
+                    ...(opts.out === undefined ? {} : { out: opts.out }),
+                    ...(opts.exclude?.length ? { exclude: opts.exclude } : {}),
+                },
+            }),
+            extract: (sandboxId, archive, into, opts = {}) => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/extract`,
+                body: { archive, into, ...(opts.strip === undefined ? {} : { strip: Math.max(0, Math.floor(opts.strip)) }) },
+            }),
+            stat: (sandboxId, path) => this.request({
+                method: "GET",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/stat?path=${encodeURIComponent(path)}`,
+            }),
+            get: (sandboxId, path, opts = {}) => this.bytes("GET", `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, undefined, opts),
+            download: (sandboxId, path, onChunk, opts = {}) => this.stream(`/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, onChunk, opts),
+            text: async (sandboxId, path, opts = {}) => new TextDecoder().decode(await this.sandboxes.files.get(sandboxId, path, opts)),
+            put: async (sandboxId, path, data, opts = {}) => {
+                const body = typeof data === "string" ? new TextEncoder().encode(data) : data;
+                return this.sandboxes.files.putFrom(sandboxId, path, {
+                    size: body.length,
+                    read: (offset, len) => body.subarray(offset, offset + len),
+                }, opts);
+            },
+            putFrom: async (sandboxId, path, source, opts = {}) => {
+                const mode = opts.mode === undefined ? "" : `&mode=${opts.mode.toString(8)}`;
+                const base = `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}${mode}`;
+                let sent = 0;
+                let chunks = 0;
+                let last;
+                do {
+                    const slice = await source.read(sent, Math.min(FILE_PUT_CHUNK_BYTES, source.size - sent));
+                    if (slice.length === 0 && sent < source.size) {
+                        throw new InvalidArgumentError(`the source of ${path} ended at ${sent} of ${source.size} bytes`, "The file shrank while it was being sent; send it again once nothing is writing it.");
+                    }
+                    const raw = await this.bytes("PUT", sent === 0 ? base : `${base}&offset=${sent}`, slice, opts);
+                    last = JSON.parse(new TextDecoder().decode(raw));
+                    sent += slice.length;
+                    chunks += 1;
+                } while (sent < source.size);
+                return { ...last, bytes: source.size, chunks };
+            },
+            delete: (sandboxId, path, opts = {}) => this.request({
+                method: "DELETE",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`
+                    + (opts.recursive ? "&recursive=1" : ""),
+            }),
+        },
+        output: async (execId, opts = {}) => {
+            if (!execId)
+                throw new InvalidArgumentError("exec output needs an exec_id", "Pass the `exec_id` the exec envelope printed.");
+            let runId = opts.runId;
+            const fromSandbox = async (sid) => {
+                const rec = await this.request({
+                    method: "GET", path: `/sandboxes/${encodeURIComponent(sid)}`,
+                });
+                const hit = (rec?.execs ?? []).find((e) => e.exec_id === execId);
+                if (hit && rec?.run_id)
+                    runId ??= rec.run_id;
+                return hit;
+            };
+            let found;
+            let sandboxId = opts.sandboxId;
+            let routeMissing = false;
+            try {
+                found = await this.request({ method: "GET", path: `/execs/${encodeURIComponent(execId)}` });
+            }
+            catch (err) {
+                if (!(err instanceof NotFoundError))
+                    throw err;
+                found = undefined;
+                routeMissing = true;
+            }
+            if (found && opts.runId && found.run_id && found.run_id !== opts.runId)
+                found = undefined;
+            let otherSandbox = false;
+            if (found && opts.sandboxId && found.sandbox_id && found.sandbox_id !== opts.sandboxId) {
+                found = undefined;
+                otherSandbox = true;
+            }
+            if (found)
+                runId ??= found.run_id;
+            if (!found && (routeMissing || otherSandbox) && opts.sandboxId) {
+                try {
+                    found = await fromSandbox(opts.sandboxId);
+                }
+                catch (err) {
+                    if (!(err instanceof NotFoundError))
+                        throw err;
+                    found = undefined;
+                }
+            }
+            sandboxId ??= found?.sandbox_id;
+            if (!found) {
+                throw new NotFoundError(`exec ${execId} not found${sandboxId ? ` in sandbox ${sandboxId}` : opts.runId ? ` in run ${opts.runId}` : ""}`, "Check the `exec_id` from the exec envelope, and that the sandbox it ran in still exists (`promigence run report <run_id>`).");
+            }
+            return sliceOutput(found, sandboxId, runId, opts.range);
+        },
+    };
+    sandbox(id) {
+        return {
+            id,
+            exec: (opts) => this.sandboxes.exec(id, opts).then(toCommandResult),
+            get: () => this.sandboxes.get(id),
+            kill: () => this.sandboxes.kill(id),
+            pause: () => this.sandboxes.pause(id),
+            resume: (opts) => this.sandboxes.resume(id, opts),
+            patch: (opts) => this.sandboxes.patch(id, opts),
+            files: {
+                get: (path) => this.sandboxes.files.get(id, path),
+                text: (path) => this.sandboxes.files.text(id, path),
+                put: (path, data, opts) => this.sandboxes.files.put(id, path, data, opts ?? {}),
+                stat: (path) => this.sandboxes.files.stat(id, path),
+                delete: (path) => this.sandboxes.files.delete(id, path),
+            },
+            probe: (opts = {}) => this.sandboxes.probe(id, opts),
+        };
+    }
+    secrets = {
+        set: (name, value, opts = {}) => {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name ?? "")) {
+                throw new InvalidArgumentError(`secrets.set: ${JSON.stringify(name ?? null)} is not usable as an environment variable`, "Use letters, digits and underscores, not starting with a digit: OPENAI_API_KEY.");
+            }
+            if (!value) {
+                throw new InvalidArgumentError(`secrets.set: ${name} has an empty value`, `To remove it, call secrets.delete(${JSON.stringify(name)}).`);
+            }
+            const body = { name, value };
+            if (opts.hosts !== undefined)
+                body.hosts = opts.hosts;
+            if (opts.headers !== undefined)
+                body.headers = opts.headers;
+            if (opts.raw !== undefined)
+                body.raw = opts.raw;
+            if (opts.scanResponses !== undefined)
+                body.scan_responses = opts.scanResponses;
+            return this.request({ method: "POST", path: "/secrets", body });
+        },
+        list: () => this.request({ method: "GET", path: "/secrets" }),
+        delete: (name) => this.request({
+            method: "DELETE",
+            path: `/secrets/${encodeURIComponent(name)}`,
+        }),
+    };
+    images = {
+        resolve: (image, opts = {}) => {
+            if (!image?.trim()) {
+                throw new InvalidArgumentError("images.resolve needs an image reference", "Pass a name like 'python:3.12' or 'ghcr.io/org/app:v1'.");
+            }
+            const body = { image: image.trim() };
+            if (opts.registrySecret)
+                body["registry_secret"] = opts.registrySecret;
+            return this.request({ method: "POST", path: "/images/resolve", body });
+        },
+    };
+    captures = {
+        delete: (snapshotId) => this.request({
+            method: "DELETE",
+            path: `/captures/${encodeURIComponent(snapshotId)}`,
+        }),
+    };
+    snapshots = {
+        create: (opts) => {
+            const body = snapshotCreateBody(opts);
+            return this.request({
+                method: "POST", path: "/snapshots", body,
+                ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+            });
+        },
+        status: (buildId, opts = {}) => this.request({
+            method: "GET",
+            path: `/snapshots/builds/${encodeURIComponent(buildId)}${waitQuery(opts.waitMs)}`,
+            ...this.readExtras(opts),
+        }),
+        buildLog: async (buildId, tail = 200) => {
+            const r = await this.request({
+                method: "GET",
+                path: `/snapshots/builds/${encodeURIComponent(buildId)}/build-log?tail=${Math.max(1, Math.floor(tail))}`,
+            });
+            return r?.log ?? [];
+        },
+        builds: async (limit = 20) => (await this.snapshots.buildsPage({ limit })).items,
+        buildsPage: async (opts = {}) => {
+            const limit = opts.limit ?? 20;
+            const r = await this.request({ method: "GET", path: `/snapshots/builds?${pageQuery(limit, 500, opts.cursor)}` });
+            return pageOf(r, "builds", limit);
+        },
+        get: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}` }),
+        list: async (opts = {}) => (await this.snapshots.listPage(opts)).items,
+        listPage: async (opts = {}) => {
+            const q = new URLSearchParams();
+            if (opts.limit !== undefined)
+                q.set("limit", String(Math.max(1, Math.trunc(opts.limit))));
+            if (opts.cursor)
+                q.set("cursor", opts.cursor);
+            const qs = q.toString();
+            const r = await this.request({
+                method: "GET", path: `/snapshots${qs ? `?${qs}` : ""}`, ...(this.authenticated ? {} : { anonymous: true }),
+            });
+            if (Array.isArray(r))
+                return { items: r, nextCursor: null, limit: opts.limit ?? r.length };
+            return { items: r?.snapshots ?? [], nextCursor: r?.next_cursor ?? null, limit: r?.limit ?? (opts.limit ?? 0) };
+        },
+        public: async (limit = 20) => {
+            const r = await this.request({
+                method: "GET",
+                path: `/snapshots?limit=${Math.max(1, Math.floor(limit))}`,
+                anonymous: true,
+            });
+            const all = Array.isArray(r) ? r : (r?.snapshots ?? []);
+            return all.filter((s) => s.visibility === undefined || s.visibility === "public").slice(0, limit);
+        },
+        delete: (idOrAlias) => {
+            if (!idOrAlias)
+                throw new InvalidArgumentError("snapshots.delete needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
+            return this.request({ method: "DELETE", path: `/snapshots/${seg(idOrAlias)}` });
+        },
+        alias: (idOrAlias, alias) => this.request({
+            method: "PUT",
+            path: `/snapshots/${seg(idOrAlias)}/alias`,
+            body: { alias },
+        }),
+        waitBuild: async (buildId, opts = {}) => {
+            const r = await this.waitLoop(opts, BUILD_POLL_MS, { build_id: buildId, state: "running" }, (read) => this.snapshots.status(buildId, read), (b) => b.state !== "running" && b.state !== "queued");
+            return { build: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
+        },
+        verify: (id, opts = {}) => {
+            if (!id)
+                throw new InvalidArgumentError("snapshots.verify needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
+            const body = {};
+            if (opts.timeoutMs !== undefined)
+                body["timeout_ms"] = opts.timeoutMs;
+            if (opts.spendCap !== undefined)
+                body["spend_cap"] = opts.spendCap;
+            return this.request({
+                method: "POST",
+                path: `/snapshots/${encodeURIComponent(id)}/verify`,
+                body,
+            });
+        },
+        manifest: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}/manifest` }),
+        bundle: async (idOrAlias, opts = {}) => {
+            const [record, m] = await Promise.all([
+                this.snapshots.get(idOrAlias).catch(() => undefined),
+                this.snapshots.manifest(idOrAlias),
+            ]);
+            if (!m?.manifest || typeof m.manifest !== "object") {
+                throw new NotFoundError(`snapshot ${idOrAlias} has no manifest to export`, "Only a verified snapshot has one: check 'promigence snapshot inspect' first.");
+            }
+            const alias = opts.alias ?? record?.alias ?? undefined;
+            const bundle = buildBundle(m.manifest, { ...(alias ? { alias } : {}) });
+            return { bundle, served_by: "client", ...(record ? { record } : {}) };
+        },
+    };
+}
+const POLL_LADDER_MS = [10, 25, 25, 25, 25, 25, 25, 25, 25, 50, 50, 50, 100, 100, 100, 200];
+function pollInterval(iteration) {
+    const step = POLL_LADDER_MS[iteration];
+    if (step !== undefined)
+        return step;
+    if (iteration < 30)
+        return 500;
+    return 1000;
+}
+function sliceOutput(e, sandboxId, runId, range) {
+    const enc = new TextEncoder();
+    const dec = new TextDecoder();
+    const cut = (text) => {
+        const all = enc.encode(text);
+        if (!range)
+            return { text, total: all.length, bytes: all.length };
+        const from = Math.max(0, Math.min(range.from ?? 0, all.length));
+        const to = Math.min(all.length - 1, range.to ?? all.length - 1);
+        const part = to < from ? new Uint8Array(0) : all.subarray(from, to + 1);
+        return { text: dec.decode(part), total: all.length, bytes: part.length };
+    };
+    const out = cut(e.stdout ?? "");
+    const err = cut(e.stderr ?? "");
+    return {
+        exec_id: e.exec_id,
+        ...(sandboxId ?? e.sandbox_id ? { sandbox_id: (sandboxId ?? e.sandbox_id) } : {}),
+        ...(runId ?? e.run_id ? { run_id: (runId ?? e.run_id) } : {}),
+        ...(e.argv ? { argv: e.argv } : {}),
+        exit_code: e.exit_code ?? null,
+        stdout: out.text,
+        stderr: err.text,
+        truncated: e.truncated ?? false,
+        bytes: out.bytes + err.bytes,
+        total_bytes: out.total + err.total,
+        ...(range ? { range: { from: range.from ?? 0, to: range.to ?? Math.max(0, out.total - 1) } } : {}),
+    };
+}
+export function toCommandResult(r) {
+    const signal = r["signal"];
+    return {
+        exitCode: r.exit_code ?? (typeof signal === "number" && signal > 0 ? 128 + signal : -1),
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? "",
+        ...(r.truncated === undefined ? {} : { truncated: r.truncated }),
+        ...(r.exec_id === undefined ? {} : { execId: r.exec_id }),
+    };
+}