promigence 0.1.0-beta.12

package/dist/commands.js

@@ -0,0 +1,2675 @@
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { DEFAULT_API_URL, DEFAULT_SNAPSHOT, ERRORS_DOCS_URL, MAX_OUTPUT_BYTES_DEFAULT, CONTEXT_GIT_RE, PromigenceClient, checkRepoUrl, withoutPin, PromigenceError, SpendCapError, TimeoutError, checkImageRef, contextRelative, credentialsPath, FILE_PUT_CHUNK_BYTES, imageSnapshot, isWaiting, execOutputBytes, listContext, packContext, readCredentials, } from "./sdk/index.js";
+import { fmtMs, recordTiming } from "./timing.js";
+import { capacityLine, queuedClause, queuedLines, statusLine } from "./capacity.js";
+import { DevcontainerError, detectOne, load, planJson, planLines, planSetup, resolveGiven, snapshotEnv, snapshotUsers, translate, workspaceRootFor, wrapCommand, } from "./devcontainer.js";
+import { detect, ecosystemOfCommands, imageCreateCommand, readConfig } from "./init.js";
+import { CREDENTIAL_REMEDY, confirmOverride, credentialRefusal, emitUploadList, localTarNoMetadataArgs } from "./uploadguard.js";
+import { emit, errorEnvelope, errorTextLines, exitWith, forkLine, forkSummary, gradeLine, ms, noCommandFix, okEnvelope, parseMaxOutput, recordNotice, sandboxGrade, parseCommandTimeout, parseCount, parseDuration, parseUsd, pickExit, reportSummaryLines, toPromigenceError, totalsLine, usageError, write, writeBytes, } from "./io.js";
+import { buildPrice, buildPriceWords } from "./pricing.js";
+import { DOCS_URL, WAIT_TIMEOUT_DEFAULT } from "./surface.js";
+import { escapeLine, fieldForTerminal, forTerminal, jsonLine, sh, shellArg } from "./term.js";
+import { snapshotArg } from "./bundle.js";
+import { loginMintedKey, revokeReplacedKey, storeCredentials, storedWhere } from "./credfile.js";
+import { isSecureUrl, tlsChecksOff } from "./login.js";
+import { duration, reportLines, reproCommand, sandboxLines } from "./report.js";
+import { ERROR_BY_CODE } from "./generated.js";
+import { lookupError } from "./guide.js";
+import { usd as moneyUsd } from "./money.js";
+import { execBackground } from "./live.js";
+import { dirSnapshotCreate } from "./dirsnap.js";
+import { githubCreate } from "./github.js";
+import { untarSafe, UnsafeArchiveError } from "./untar.js";
+export function str(ctx, name) {
+    const v = ctx.flags.get(name);
+    if (!v || v.length === 0)
+        return undefined;
+    const last = v[v.length - 1];
+    if (last === true) {
+        throw usageError(`${name} needs a value`, `Pass ${name} <value> — or ${name}=<value> if the value starts with '--'; see 'promigence ${ctx.cmd.name} --help'.`);
+    }
+    return last;
+}
+export function list(ctx, name) {
+    return (ctx.flags.get(name) ?? []).filter((v) => typeof v === "string");
+}
+export function bool(ctx, name) {
+    return ctx.flags.has(name);
+}
+export function required(ctx, name, hint) {
+    const v = str(ctx, name);
+    if (v === undefined)
+        throw usageError(`${name} is required`, hint);
+    return v;
+}
+export function clientOpts(ctx) {
+    return {
+        cliErrors: true,
+        ...(ctx.apiKey === undefined ? {} : { apiKey: ctx.apiKey }),
+        ...(ctx.requestTimeoutMs === undefined ? {} : { requestTimeoutMs: ctx.requestTimeoutMs }),
+    };
+}
+export function client(ctx) {
+    return new PromigenceClient({ ...clientOpts(ctx), onNotice: recordNotice, onTiming: recordTiming });
+}
+export async function serverLocation(ctx) {
+    const h = await client(ctx).health({ timeoutMs: 3000 }).catch(() => undefined);
+    return typeof h?.location === "string" && h.location !== "" ? h.location : undefined;
+}
+export const nexts = (...items) => items.map(([cmd, why]) => ({ cmd, why }));
+export const KEPT_BY_HOLDERS = "sandboxes that were already given its value keep it until they end; it stays masked in their output";
+export function waitBound(ctx) {
+    const v = str(ctx, "--wait-timeout") ?? WAIT_TIMEOUT_DEFAULT;
+    return parseDuration(v, "--wait-timeout");
+}
+export async function spendCap(ctx, c) {
+    const flag = str(ctx, "--cap");
+    if (flag !== undefined)
+        return parseUsd(flag, "--cap");
+    const env = process.env["PROMIGENCE_SPEND_CAP"];
+    if (env !== undefined && env !== "")
+        return parseUsd(env, "PROMIGENCE_SPEND_CAP");
+    const me = await c.me();
+    if (typeof me.default_spend_cap === "number" && me.default_spend_cap > 0)
+        return me.default_spend_cap;
+    throw usageError("no spend cap: every run is capped before it starts", "Pass --cap USD (e.g. --cap 1), set PROMIGENCE_SPEND_CAP, or ask for an org default_spend_cap (promigence me).");
+}
+function autoIdempotencyKey(ctx) {
+    if (bool(ctx, "--fresh"))
+        return undefined;
+    const explicit = str(ctx, "--idempotency-key");
+    if (explicit !== undefined)
+        return explicit;
+    const h = createHash("sha256");
+    h.update(process.argv.slice(2).join(" "));
+    h.update(process.cwd());
+    try {
+        h.update(readFileSync("promigence.toml"));
+    }
+    catch {
+        h.update("");
+    }
+    h.update(ctx.apiKey ?? process.env["PROMIGENCE_API_KEY"] ?? readCredentials().api_key ?? "");
+    h.update(String(Math.floor(Date.now() / 600_000)));
+    return `hk-cli-${h.digest("hex").slice(0, 32)}`;
+}
+export function replayNote(started, explicitKey) {
+    if (started.idempotent_replay !== true)
+        return undefined;
+    const age = started.idempotent_replay_age_s;
+    const when = age === undefined ? "earlier"
+        : age < 60 ? `${age}s ago`
+            : `${Math.round(age / 60)} min ago`;
+    return explicitKey
+        ? `same --idempotency-key as ${when}: returning that run's sandboxes (a new key starts new ones)`
+        : `same command as ${when}: returning that run's sandboxes (pass --fresh for new ones)`;
+}
+export function buildReplayNote(started, explicitKey) {
+    if (started.idempotent_replay !== true)
+        return undefined;
+    const age = started.idempotent_replay_age_s;
+    const when = age === undefined ? "earlier" : age < 60 ? `${age}s ago` : `${Math.round(age / 60)} min ago`;
+    return explicitKey
+        ? `same --idempotency-key as ${when}: reusing build ${started.build_id ?? "?"} (nothing charged; a new key starts a new build)`
+        : `same command as ${when}: reusing build ${started.build_id ?? "?"} (nothing charged; pass --fresh for a new build)`;
+}
+function replayFields(started) {
+    if (started.idempotent_replay === undefined)
+        return {};
+    return {
+        idempotent_replay: started.idempotent_replay,
+        ...(started.idempotent_replay ? { replayed: true } : {}),
+        ...(started.idempotent_replay_age_s === undefined ? {} : { idempotent_replay_age_s: started.idempotent_replay_age_s }),
+    };
+}
+export function optimizeForFlag(ctx) {
+    const v = str(ctx, "--optimize-for");
+    if (v === undefined)
+        return undefined;
+    if (v !== "start" && v !== "compute") {
+        throw usageError(`--optimize-for: '${v}' is not a choice`, "Pass --optimize-for start | compute (default start).");
+    }
+    return v;
+}
+async function runStartOpts(ctx, c, resolved) {
+    const snapshot = resolved ?? await snapshotArg(ctx, c);
+    const count = parseCount(required(ctx, "--count", "Pass --count N (number of sandboxes to fork)."), "--count");
+    const opts = { snapshot, count, spendCap: await spendCap(ctx, c) };
+    const timeout = str(ctx, "--timeout");
+    opts.timeoutMs = timeout === undefined ? 15 * 60_000 : parseDuration(timeout, "--timeout");
+    if (bool(ctx, "--allow-partial"))
+        opts.allowPartial = true;
+    if (bool(ctx, "--verify-each"))
+        opts.verifyEach = true;
+    const optimizeFor = optimizeForFlag(ctx);
+    if (optimizeFor !== undefined)
+        opts.optimizeFor = optimizeFor;
+    const network = str(ctx, "--network");
+    const allow = list(ctx, "--allow").flatMap((h) => h.split(",")).map((h) => h.trim()).filter(Boolean);
+    if (network !== undefined) {
+        if (network !== "none" && network !== "egress") {
+            throw usageError(`--network: '${network}' is not a mode`, "Pass --network none | egress (default egress), or --allow HOST to name what the sandbox may reach.");
+        }
+        opts.network = network;
+    }
+    if (allow.length) {
+        if (network !== undefined && network !== "egress") {
+            throw usageError(`--allow cannot be combined with --network ${network}`, "Use --allow HOST on its own: it already runs the sandbox behind an outbound allow-list.");
+        }
+        opts.network = { allow };
+    }
+    const secrets = list(ctx, "--secret");
+    if (secrets.length)
+        opts.secrets = secrets;
+    const labels = {};
+    for (const l of list(ctx, "--label")) {
+        const i = l.indexOf("=");
+        if (i < 1)
+            throw usageError(`--label: '${l}' is not NAME=VALUE`, "Pass --label name=value (repeatable).");
+        labels[l.slice(0, i)] = l.slice(i + 1);
+    }
+    if (Object.keys(labels).length)
+        opts.labels = labels;
+    const grade = gradeOpts(ctx);
+    if (grade)
+        opts.grade = grade;
+    if (bool(ctx, "--grade-output"))
+        opts.gradeOutput = true;
+    return opts;
+}
+export function gradeOpts(ctx) {
+    const cmd = str(ctx, "--grade");
+    const holdout = str(ctx, "--holdout");
+    const score = str(ctx, "--grade-score");
+    const timeout = str(ctx, "--grade-timeout");
+    if (cmd === undefined) {
+        if (holdout !== undefined || score !== undefined || timeout !== undefined) {
+            throw usageError("--holdout / --grade-score / --grade-timeout need --grade", "Pass --grade 'pytest -q tests/' alongside them.");
+        }
+        return undefined;
+    }
+    const out = { cmd };
+    if (holdout !== undefined)
+        out.holdoutCmd = holdout;
+    if (timeout !== undefined)
+        out.timeoutMs = parseDuration(timeout, "--grade-timeout");
+    if (score !== undefined) {
+        if (score !== "exit" && score !== "last_line_json" && score !== "tap") {
+            throw usageError(`--grade-score: '${score}' is not a mode`, "Pass --grade-score exit | last_line_json | tap (default exit).");
+        }
+        out.score = score;
+    }
+    return out;
+}
+function reportExits(report) {
+    const t = report.totals;
+    const codes = [];
+    if (!t)
+        return codes;
+    if (t.env_failed > 0 || (t.grader_failed ?? 0) > 0)
+        codes.push(3);
+    if (t.not_started > 0 || t.cap_killed > 0 || t.expired > 0 || (t.stopped_by_support ?? 0) > 0)
+        codes.push(12);
+    if (t.task_failed > 0 || t.snapshot_failed > 0)
+        codes.push(4);
+    return codes;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+const authLogin = async (ctx) => {
+    const fromEnv = str(ctx, "--from-env");
+    const onArgv = str(ctx, "--api-key");
+    const warnings = [];
+    let key;
+    if (onArgv !== undefined) {
+        key = onArgv;
+        warnings.push("--api-key puts the key on argv, where `ps` and shell history can read it; prefer --from-env VAR or stdin.");
+    }
+    else if (fromEnv !== undefined) {
+        key = process.env[fromEnv];
+        if (!key) {
+            throw usageError(`--from-env ${fromEnv}: the variable is empty or unset`, `Export it first: export ${fromEnv}=prom_api_... && ${sh `promigence auth login --from-env ${fromEnv}`}.`);
+        }
+    }
+    else {
+        if (process.stdin.isTTY) {
+            throw usageError("no key given and stdin is a TTY (promigence never prompts)", 'Pipe it: printf %s "$PROMIGENCE_API_KEY" | promigence auth login, or use --from-env PROMIGENCE_API_KEY.');
+        }
+        key = (await readStdin()).trim();
+        if (!key)
+            throw usageError("stdin was empty", 'Pipe the key: printf %s "$PROMIGENCE_API_KEY" | promigence auth login.');
+    }
+    key = key.trim();
+    const path = credentialsPath();
+    const existing = readCredentials();
+    const previous = loginMintedKey();
+    const body = { api_key: key };
+    const apiUrl = process.env["PROMIGENCE_API_URL"] || existing.api_url;
+    const bound = apiUrl && apiUrl.replace(/\/+$/, "") !== DEFAULT_API_URL.replace(/\/+$/, "") ? apiUrl : undefined;
+    if (bound && !isSecureUrl(bound)) {
+        const from = process.env["PROMIGENCE_API_URL"] ? "PROMIGENCE_API_URL" : `the api_url in ${path}`;
+        await write(process.stderr, `promigence auth login: warning: ${bound} (from ${from}) is not https; every request `
+            + "will carry this key in the clear. Use the https URL unless this is a private benchmark network.\n");
+    }
+    const revokes = previous !== undefined && previous.apiKey !== key;
+    if (bound)
+        body["api_url"] = bound;
+    const stored = storeCredentials(body);
+    warnings.push(...stored.warnings);
+    let revoked;
+    if (previous && revokes && tlsChecksOff()) {
+        warnings.push(`the key this replaced (${previous.keyId}) was not revoked: TLS certificate checks are off `
+            + `(NODE_TLS_REJECT_UNAUTHORIZED), so it was not sent; revoke it with \`${sh `promigence keys revoke ${previous.keyId}`}\` once they are on`);
+    }
+    else if (previous && revokes) {
+        const r = await revokeReplacedKey(previous, "this replaced", key);
+        revoked = r.revoked;
+        if (r.warning)
+            warnings.push(r.warning);
+    }
+    const next = nexts(["promigence me", "confirm the key, org limits and default spend cap"], ["promigence examples", "what you can fork with no build (the built-in base)"]);
+    const fields = {
+        credentials: path, store: stored.store, mode: stored.store === "file" ? "0600" : null, replaced: Boolean(existing.api_key),
+        api_url: (bound ?? DEFAULT_API_URL).replace(/\/+$/, ""), revoked_key_id: revoked ?? null,
+    };
+    if (stored.note)
+        fields["store_note"] = stored.note;
+    if (warnings.length)
+        fields["warnings"] = warnings;
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, fields, next), [
+        `promigence auth login: key stored in ${storedWhere(stored)}, sent only to ${(bound ?? DEFAULT_API_URL).replace(/\/+$/, "")}`,
+        ...(stored.note ? [`  note: ${stored.note}`] : []),
+        ...(revoked ? [`  replaced key ${revoked} revoked`] : []),
+        ...warnings.map((w) => `  warning: ${w}`),
+        `  next: ${next[0].cmd}`,
+    ], 0, ctx.pointer);
+};
+const secretsSet = async (ctx) => {
+    const c = client(ctx);
+    if (bool(ctx, "--list")) {
+        const { secrets } = await c.secrets.list();
+        const next = nexts(["promigence run --count 1 --cap 1 --secret NAME -- CMD", "use one in a run"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { secrets }, next), [
+            `promigence secrets: ${secrets.length} stored`,
+            ...secrets.flatMap(secretListLines),
+        ], 0, false);
+    }
+    const name = positional(ctx, "a secret name", "promigence secrets set OPENAI_API_KEY --from-env OPENAI_API_KEY");
+    if (ctx.args.length > 1) {
+        throw usageError("a value on the command line is refused (it would be kept in your shell history)", `Use --from-env VAR, --from-file PATH, or pipe it on stdin: printf %s "$KEY" | ${sh `promigence secrets set ${name}`}.`);
+    }
+    if (bool(ctx, "--delete")) {
+        const res = await c.secrets.delete(name);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { name: res.name, deleted: res.deleted, note: KEPT_BY_HOLDERS }, []), [`${sh `promigence secrets set ${name} --delete`}: removed`, KEPT_BY_HOLDERS], 0, false);
+    }
+    const fromEnv = str(ctx, "--from-env");
+    const fromFile = str(ctx, "--from-file");
+    if (fromEnv !== undefined && fromFile !== undefined) {
+        throw usageError("--from-env and --from-file are alternatives", "Pick one source for the value.");
+    }
+    let value;
+    let source;
+    if (fromEnv !== undefined) {
+        value = process.env[fromEnv];
+        source = `env:${fromEnv}`;
+        if (!value) {
+            throw usageError(`--from-env ${fromEnv}: the variable is empty or unset`, `Export it first: export ${fromEnv}=... && ${sh `promigence secrets set ${name} --from-env ${fromEnv}`}.`);
+        }
+    }
+    else if (fromFile !== undefined) {
+        source = `file:${fromFile}`;
+        try {
+            value = readFileSync(fromFile, "utf8");
+        }
+        catch (err) {
+            throw usageError(`--from-file ${fromFile}: ${err?.message ?? "cannot read"}`, "Point it at a readable file containing only the value.");
+        }
+    }
+    else {
+        source = "stdin";
+        if (process.stdin.isTTY) {
+            throw usageError("no value given and stdin is a TTY (promigence never prompts)", `Pipe it: printf %s "$OPENAI_API_KEY" | ${sh `promigence secrets set ${name}`}, or use --from-env OPENAI_API_KEY.`);
+        }
+        value = await readStdin();
+        if (!value.trim()) {
+            throw usageError("stdin was empty", `Pipe the value: printf %s "$KEY" | ${sh `promigence secrets set ${name}`}.`);
+        }
+    }
+    value = value.replace(/\r?\n$/, "");
+    const hosts = list(ctx, "--host");
+    const headers = list(ctx, "--header");
+    const noRaw = bool(ctx, "--no-raw");
+    const opts = {
+        ...(hosts.length ? { hosts } : {}),
+        ...(headers.length ? { headers } : {}),
+        ...(noRaw ? { raw: "refused" } : {}),
+    };
+    const res = await c.secrets.set(name, value, opts);
+    const next = nexts([`${sh `promigence run --count 1 --cap 1 --secret ${name}`} -- CMD`, "give it to every sandbox of a run"], ["promigence secrets set --list", "what this org has stored"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+        name: res.name, bytes: res.bytes, created: res.created ?? true, source,
+        ...(res.hosts?.length
+            ? {
+                hosts: res.hosts, placeholder: res.placeholder, raw: res.raw,
+                ...(res.urls?.length ? { urls: res.urls } : {}),
+                ...(res.env && Object.keys(res.env).length ? { env: res.env } : {}),
+            }
+            : {}),
+    }, next), [
+        `${sh `promigence secrets set ${name}`}: stored ${res.bytes} bytes from ${source}`,
+        ...(res.hosts?.length
+            ? [
+                `  bound to ${res.hosts.join(", ")}: the value stays out of the sandbox unless a run asks for it (the variable holds ${res.placeholder ?? "something else"})`,
+                ...boundUseLines(res),
+                ...(res.raw === "refused" ? ["  its value can never be given to a sandbox"] : []),
+            ]
+            : ["  the value is encrypted at rest and redacted wherever it appears verbatim in logs, reports and command output",
+                "  redaction is best effort (an encoded or altered value prints in clear): never print a secret"]),
+        `  next: ${next[0].cmd}`,
+    ], 0, false);
+};
+function boundUseLines(res) {
+    const hosts = res.hosts ?? [];
+    const urls = res.urls ?? [];
+    if (urls.length !== hosts.length)
+        return [];
+    const lines = [
+        "  requests the sandbox sends to this address are authenticated with it:",
+        ...urls.map((u) => `    ${urlLine(u, res.env)}`),
+        `  a request sent straight to ${hosts.map((h) => `https://${h}`).join(" or ")} is not authenticated: send it to the address above`,
+        ...(res.scan_responses === true ? ["  the host's answers never show the value: an echo service shows asterisks instead"] : []),
+    ];
+    return lines;
+}
+function urlLine(u, env) {
+    const vars = Object.entries(env ?? {})
+        .filter(([, v]) => v === u || v.startsWith(`${u}/`))
+        .map(([k]) => k);
+    return `${u}/<path>${vars.length ? `  (${vars.join(", ")} in the sandbox already points here)` : ""}`;
+}
+export function secretListLines(s) {
+    return [
+        `  ${s.name} (${s.bytes} bytes, updated ${s.updated_at ?? "?"})${boundTo(s)}`,
+        ...(s.urls ?? []).map((u) => `    in requests sent to ${urlLine(u, s.env)}`),
+    ];
+}
+function boundTo(s) {
+    if (!s.hosts?.length)
+        return "";
+    return ` → bound to ${s.hosts.join(", ")}${s.raw === "refused" ? ", value never given" : ""}`;
+}
+function buildFields(b) {
+    const out = { build_id: b.build_id, state: b.state };
+    if (b.snapshot_id)
+        out["snapshot_id"] = b.snapshot_id;
+    if (b.alias)
+        out["alias"] = b.alias;
+    if (b.snapshot_deleted === true)
+        out["snapshot_deleted"] = true;
+    if (b.tier_assigned)
+        out["tier_assigned"] = b.tier_assigned;
+    if (b.verification)
+        out["verification"] = b.verification;
+    if (b.error)
+        out["error_detail"] = b.error;
+    if (b.deduped)
+        out["deduped"] = true;
+    if (b.joined)
+        out["joined"] = true;
+    if (b.warnings?.length)
+        out["warnings"] = b.warnings;
+    if (b.source)
+        out["source"] = b.source;
+    if (typeof b.verified === "boolean")
+        out["verified"] = b.verified;
+    for (const k of ["build_price", "per_second_usd", "max_seconds", "billable_seconds", "cost_usd"]) {
+        if (typeof b[k] === "number")
+            out[k] = b[k];
+    }
+    const ab = b;
+    if (ab.alias_requested !== undefined)
+        out["alias_requested"] = ab.alias_requested;
+    if (ab.alias_applied !== undefined)
+        out["alias_applied"] = ab.alias_applied;
+    return out;
+}
+function isBuilding(b) {
+    return b.state === "queued" || b.state === "running";
+}
+export function buildPriceOf(b) {
+    return typeof b.build_price === "number" && typeof b.per_second_usd === "number" && typeof b.max_seconds === "number"
+        ? { most_usd: b.build_price, per_second_usd: b.per_second_usd, max_s: b.max_seconds }
+        : undefined;
+}
+function buildExit(b) {
+    if (b.state === "verified" || b.state === "built")
+        return 0;
+    if (b.state === "rejected")
+        return 6;
+    if (b.state === "failed")
+        return 3;
+    return 0;
+}
+export function verifyTiming(v) {
+    if (!v)
+        return undefined;
+    const cold = typeof v["verify_cold_ms"] === "number" && v["verify_cold_ms"] > 0 ? v["verify_cold_ms"] : undefined;
+    const warmRaw = v["verify_warm_builder"]?.median_ms;
+    const warm = typeof warmRaw === "number" && warmRaw > 0 ? warmRaw : undefined;
+    const parts = [
+        ...(cold === undefined ? [] : [`cold ${ms(cold)}`]),
+        ...(warm === undefined ? [] : [`warm ${ms(warm)}`]),
+    ];
+    return parts.length ? parts.join(" · ") : undefined;
+}
+function buildLines(b) {
+    const note = b.deduped ? " (deduped: an identical build already ran)"
+        : b.idempotent_replay === true ? " (reused: the same request already built it)" : "";
+    const unverified = b.state === "built" || (b.state === "verified" && b.verified === false);
+    const shown = unverified ? "built (no --verify: not verified)" : b.state;
+    const lines = [`build ${b.build_id}: ${shown}${note}`];
+    if (b.snapshot_id)
+        lines.push(`  snapshot ${b.snapshot_id}${b.snapshot_deleted === true ? " (deleted)" : b.alias ? ` (alias ${b.alias})` : ""} · tier ${b.tier_assigned ?? "?"}`);
+    if (b.source?.kind === "image")
+        lines.push(`  image ${b.source.image ?? b.source.digest ?? "?"}`);
+    const timing = verifyTiming(b.verification);
+    if (timing)
+        lines.push(`  verify: ${timing}`);
+    const cost = typeof b.cost_usd === "number" && !isBuilding(b) ? b.cost_usd : undefined;
+    const ran = typeof b.billable_seconds === "number" ? ` for the ${b.billable_seconds} s it ran` : "";
+    if (b.error) {
+        lines.push(`  ${b.error.guard ? `guard ${b.error.guard}: ` : ""}${b.error.message ?? b.error.code ?? "rejected"}`);
+        const stored = `nothing was stored${b.error.stored === false ? "" : "?"}`;
+        lines.push(cost !== undefined && cost > 0 ? `  ${stored}; billed ${usd(cost)}${ran}` : `  ${stored} and nothing was charged`);
+    }
+    else if (cost !== undefined && cost > 0) {
+        lines.push(`  billed ${usd(cost)}${ran}`);
+    }
+    for (const w of b.warnings ?? [])
+        lines.push(`  warning: ${w}`);
+    if (unverified)
+        lines.push("  add --verify CMD to have the build check the environment, and a fork re-check it on demand (snapshot verify)");
+    return lines;
+}
+async function emitBuild(ctx, b, extra = {}, more = []) {
+    const exit = buildExit(b);
+    const next = b.snapshot_deleted === true
+        ? nexts(["promigence snapshot list", "this build's snapshot was deleted; the snapshots you have now"])
+        : b.snapshot_id && (b.state === "verified" || b.state === "built" || (!isBuilding(b) && b.state !== "rejected" && b.state !== "failed"))
+            ? nexts([sh `promigence run --snapshot ${b.snapshot_id} --count 2 --cap 1 -- CMD`, "fork it and run a command in every sandbox"], [sh `promigence snapshot inspect ${b.snapshot_id}`, "the manifest: provenance and verification"])
+            : b.state === "running"
+                ? nexts([sh `promigence snapshot status ${b.build_id} --wait`, "keep waiting; the build is untouched"])
+                : nexts([sh `promigence snapshot status ${b.build_id} --log 80`, "the tail of the build log that failed: fix what it names, then build again"]);
+    const want = b.alias_requested;
+    if (b.alias_applied === false && want && b.snapshot_id) {
+        next.unshift({ cmd: sh `promigence snapshot alias ${b.snapshot_id} ${want}`, why: `the alias ${want} was not applied: move it to this snapshot` });
+    }
+    const env = { ...okEnvelope(ctx.cmd.name, { ...buildFields(b), ...extra }, next), ok: exit === 0 };
+    if (exit !== 0) {
+        const code = b.error?.code ?? (b.state === "rejected" ? "snapshot_rejected" : "build_failed");
+        env.error = {
+            code,
+            message: `build ${b.build_id} ${b.state}: ${b.error?.guard ? `guard ${b.error.guard}: ` : ""}${b.error?.message ?? "no snapshot was stored"}`,
+            fix: `Read the log (${sh `promigence snapshot status ${b.build_id} --log 80`}), fix what it names, and build again.`,
+            docs: DOCS_URL,
+            guide: sh `promigence agent-guide --section errors --code ${code}`,
+        };
+    }
+    return emit(ctx.mode, env, [...buildLines(b), ...more, ...(env.error ? [`  fix: ${env.error.fix}`] : []), `  next: ${next[0].cmd}`], exit, ctx.pointer);
+}
+export function buildLogLines(log, state) {
+    if (log === undefined)
+        return ["  log: could not be read right now; try again in a moment"];
+    if (log.length === 0) {
+        return [state === "queued" ? "  log: none yet, the build has not started" : "  log: no output of your own was kept for this build"];
+    }
+    return [`  log (your build's own output, last ${log.length} line${log.length === 1 ? "" : "s"}):`, ...log.map((l) => `    ${l}`)];
+}
+function buildWaitExpired(ctx, b, boundMs) {
+    const next = nexts([sh `promigence snapshot status ${b.build_id} --wait`, "keep waiting; the build is untouched"], [sh `promigence snapshot status ${b.build_id} --log 80`, "what the builder is doing right now"]);
+    const err = new TimeoutError(`wait of ${boundMs}ms expired; the build is still running and nothing was cancelled`, `Run the id-based command: ${sh `promigence snapshot status ${b.build_id} --wait`}.`);
+    const env = errorEnvelope(ctx.cmd.name, err, next);
+    env["build_id"] = b.build_id;
+    env["state"] = b.state;
+    env["cancelled"] = false;
+    return emit(ctx.mode, env, errorTextLines(ctx.cmd.name, err, 11, next), 11, ctx.pointer);
+}
+function devcontainerPlan(ctx, form) {
+    const flag = ctx.flags.get("--devcontainer");
+    const asked = flag !== undefined && flag.length > 0;
+    const given = asked ? flag[flag.length - 1] : undefined;
+    if (bool(ctx, "--no-devcontainer")) {
+        if (asked)
+            throw usageError("--devcontainer and --no-devcontainer contradict each other", "Pass one of them.");
+        return undefined;
+    }
+    if (!asked && form !== "repo")
+        return undefined;
+    try {
+        const file = given === undefined || given === true ? detectOne(process.cwd(), asked) : resolveGiven(given);
+        if (file === undefined)
+            return undefined;
+        const loaded = load(file);
+        const override = str(ctx, "--image");
+        if (override !== undefined)
+            checkImageRef(override);
+        return translate(loaded, { workspaceRoot: workspaceRootFor(file), imageOverride: override, allowLocalEnv: bool(ctx, "--devcontainer-local-env") });
+    }
+    catch (e) {
+        if (e instanceof DevcontainerError) {
+            throw usageError(`devcontainer (${e.kind}): ${e.message}`, `${e.fix} Or pass --no-devcontainer to ignore the file.`);
+        }
+        throw e;
+    }
+}
+const CONFIG_FILE = "promigence.toml";
+function configFlags(ctx) {
+    const sourced = ["--image", "--dockerfile", "--repo", "--commit", "--devcontainer"].some((f) => ctx.flags.has(f));
+    if (sourced || !existsSync(CONFIG_FILE))
+        return false;
+    let cfg;
+    try {
+        cfg = readConfig(readFileSync(CONFIG_FILE, "utf8"));
+    }
+    catch (e) {
+        throw usageError(`${CONFIG_FILE}: ${e.message}`, "Fix that line (`promigence init --force` rewrites the file), or pass the source yourself: --repo U --commit SHA --verify CMD --tier T.");
+    }
+    const set = (flag, v) => {
+        if (v === undefined || ctx.flags.has(flag))
+            return;
+        ctx.flags.set(flag, typeof v === "string" ? [v] : [...v]);
+    };
+    set("--repo", cfg.repo);
+    set("--commit", cfg.commit);
+    if (cfg.setup?.length)
+        set("--setup", cfg.setup);
+    set("--verify", cfg.verify);
+    set("--tier", cfg.tier);
+    set("--alias", cfg.alias);
+    return true;
+}
+function snapshotForm(ctx) {
+    if (ctx.flags.has("--devcontainer") && ctx.flags.has("--dockerfile")) {
+        throw usageError("--devcontainer and --dockerfile name the same thing twice", "The devcontainer already says which Dockerfile builds it: pass --devcontainer alone, or --dockerfile alone.");
+    }
+    if (ctx.flags.has("--devcontainer") && !ctx.flags.has("--image") && !ctx.flags.has("--repo") && !ctx.flags.has("--commit")) {
+        return "image";
+    }
+    const forms = [
+        ["--image", ctx.flags.has("--image")],
+        ["--dockerfile", ctx.flags.has("--dockerfile")],
+        ["--repo/--commit", ctx.flags.has("--repo") || ctx.flags.has("--commit")],
+    ].filter(([, present]) => present).map(([n]) => n);
+    if (forms.length > 1) {
+        throw usageError(`snapshot create takes one of --image, --dockerfile or --repo/--commit, got ${forms.join(" + ")}`, "Image: promigence snapshot create --image REF@sha256:<digest> [--setup CMD] [--verify CMD]. " +
+            "Dockerfile: promigence snapshot create --dockerfile ./Dockerfile [--context DIR|URL@SHA]. " +
+            "Repo: promigence snapshot create --repo U --commit SHA --verify CMD --tier T.");
+    }
+    if (forms.length === 0) {
+        throw usageError(`snapshot create needs --image, --dockerfile or --repo/--commit (or a ${CONFIG_FILE} here)`, "Pass --image registry/name@sha256:<digest>, --dockerfile ./Dockerfile, or --repo https://github.com/org/app --commit <40-char sha>; or run `promigence init` in the repo first.");
+    }
+    const form = forms[0] === "--image" ? "image" : forms[0] === "--dockerfile" ? "dockerfile" : "repo";
+    if (form === "repo" && !ctx.flags.has("--devcontainer") && ctx.flags.has("--start")) {
+        throw usageError("--start needs --image or --dockerfile", "A start process is part of an image snapshot: pass --image REF@sha256:<digest> or --dockerfile ./Dockerfile.");
+    }
+    if (form !== "dockerfile" && ctx.flags.has("--context")) {
+        throw usageError("--context needs --dockerfile", "A build context belongs to a Dockerfile: pass --dockerfile ./Dockerfile --context DIR.");
+    }
+    return form;
+}
+function alsoRepos(ctx) {
+    const pin = /^(.*)@([0-9a-f]{40})$/i;
+    return list(ctx, "--also-repo").map((raw) => {
+        const token = raw.trim();
+        const cut = token.lastIndexOf(":");
+        let head = token;
+        let path;
+        if (cut > 0 && pin.test(token.slice(0, cut))) {
+            head = token.slice(0, cut);
+            path = token.slice(cut + 1);
+        }
+        const m = pin.exec(head);
+        if (!m || !m[1]) {
+            throw usageError(`--also-repo must be URL@<40-char sha>[:PATH], got ${JSON.stringify(raw)}`, "A branch or a short sha is not a pin, and a world that cannot be rebuilt is not " +
+                "reproducible: pass --also-repo https://github.com/org/lib@$(git -C ../lib rev-parse HEAD). " +
+                "Add :/work/lib or :vendor/lib to choose where it lands.");
+        }
+        return { repo: m[1], commit: m[2].toLowerCase(), ...(path ? { path } : {}) };
+    });
+}
+function refuseRepoCredentials(ctx) {
+    checkRepoUrl(str(ctx, "--repo"), "--repo");
+    const pin = /^(.*)@([0-9a-f]{40})$/i;
+    for (const raw of list(ctx, "--also-repo")) {
+        const token = raw.trim();
+        const cut = token.lastIndexOf(":");
+        const head = cut > 0 && pin.test(token.slice(0, cut)) ? token.slice(0, cut) : token;
+        checkRepoUrl(withoutPin(head), "--also-repo");
+    }
+    const context = str(ctx, "--context")?.trim();
+    if (context !== undefined && (context.includes("://") || /^[^/:]*@[^/:]*:/.test(context))) {
+        checkRepoUrl(withoutPin(context), "--context");
+    }
+}
+async function packedContext(ctx, dir, path) {
+    const listed = listContext(dir, { dockerfile: path });
+    if (bool(ctx, "--list-files")) {
+        return emitUploadList(ctx, {
+            kind: "dockerfile", root: dir, paths: listed.paths, files: listed.files, bytes: listed.bytes,
+            secrets: listed.secrets, notes: listed.notes, ignoreFile: listed.ignoreFile,
+        });
+    }
+    if (listed.notes.length) {
+        await write(process.stderr, ctx.mode === "json"
+            ? jsonLine(process.stderr, { hint: "context", notes: listed.notes })
+            : listed.notes.map((n) => fieldForTerminal(process.stderr, `  note: ${n}`)).join("\n") + "\n");
+    }
+    if (listed.secrets.length && !bool(ctx, "--allow-secrets"))
+        throw credentialRefusal(listed.secrets, CREDENTIAL_REMEDY.dockerfile);
+    const secretsAllowed = await confirmOverride(ctx, {
+        flag: "--allow-secrets", what: "files that look like credentials", items: listed.secrets,
+    });
+    return { context: packContext(dir, { dockerfile: path, allowSecrets: true }), secretsAllowed };
+}
+async function dockerfileOpts(ctx) {
+    const df = required(ctx, "--dockerfile", "Pass --dockerfile ./Dockerfile.");
+    const context = str(ctx, "--context");
+    if (context !== undefined && CONTEXT_GIT_RE.test(context.trim())) {
+        if (df.startsWith("/") || df.split("/").includes("..")) {
+            throw usageError(`--dockerfile must be a path inside the repository, got ${JSON.stringify(df)}`, "With --context URL@SHA the Dockerfile is read from that repository: pass --dockerfile Dockerfile or --dockerfile ci/Dockerfile.");
+        }
+        return { context: context.trim(), path: df };
+    }
+    if (context !== undefined && /^(?:https?:\/\/|ssh:\/\/|git:\/\/|git@)/i.test(context.trim())) {
+        throw usageError(`--context ${JSON.stringify(context)} is a URL but is not pinned to a full 40-character sha`, "A branch or a tag is not a pin, and a snapshot that cannot be rebuilt is not reproducible: " +
+            "pass --context URL@<40-char sha> (git rev-parse HEAD).");
+    }
+    const dir = context ?? (dirname(df) || ".");
+    let path;
+    try {
+        path = contextRelative(dir, df);
+    }
+    catch (e) {
+        throw usageError(`--dockerfile ${JSON.stringify(df)} is not inside --context ${JSON.stringify(dir)}`, `${e instanceof Error ? e.message : String(e)}. Pass --context DIR with the Dockerfile underneath it.`);
+    }
+    if (!existsSync(df)) {
+        throw usageError(`no Dockerfile at ${JSON.stringify(df)}`, "Pass --dockerfile with the path to your Dockerfile, or --context URL@SHA to build one from a repository.");
+    }
+    const packed = await packedContext(ctx, dir, path);
+    return { context: packed.context, path, ...(packed.secretsAllowed.length ? { secretsAllowed: packed.secretsAllowed } : {}) };
+}
+async function devcontainerCreate(ctx, plan) {
+    let source;
+    let label;
+    let secretsAllowed = [];
+    const localEnvBaked = await confirmOverride(ctx, {
+        flag: "--devcontainer-local-env", what: "values from your environment, baked into the snapshot",
+        items: plan.localEnvBaked ?? [],
+    });
+    if (plan.source.kind === "image") {
+        source = { image: plan.source.image };
+        label = plan.source.image;
+    }
+    else {
+        if (!existsSync(plan.source.dockerfile)) {
+            throw usageError(`the devcontainer names a Dockerfile that is not here: ${plan.source.dockerfile}`, "Check `build.dockerfile` and `build.context` in the devcontainer.json, relative to the file itself.");
+        }
+        const path = contextRelative(plan.source.context, plan.source.dockerfile);
+        const packed = await packedContext(ctx, plan.source.context, path);
+        source = { dockerfile: { context: packed.context, path } };
+        secretsAllowed = packed.secretsAllowed;
+        label = `${path} in ${plan.source.context}`;
+    }
+    const repo = str(ctx, "--repo");
+    const commit = str(ctx, "--commit");
+    if (repo !== undefined && commit === undefined) {
+        throw usageError("--repo needs --commit", "Pass --commit <40-char sha> (git rev-parse HEAD) — a branch is not a pin.");
+    }
+    if (commit !== undefined && !/^[0-9a-f]{40}$/i.test(commit)) {
+        throw usageError(`--commit must be a full 40-character sha, got ${JSON.stringify(commit)}`, "A branch is not a pin: pass --commit $(git rev-parse HEAD).");
+    }
+    const setup = planSetup(plan, { repo, commit, userSetup: list(ctx, "--setup") });
+    const env = snapshotEnv(plan);
+    const users = snapshotUsers(plan);
+    const opts = {
+        ...source, ...(setup.length ? { setup } : {}), ...(env ? { env } : {}), ...(users ?? {}),
+    };
+    const verify = str(ctx, "--verify");
+    if (verify !== undefined)
+        opts.verify = { cmd: wrapCommand(plan, verify) };
+    const start = str(ctx, "--start");
+    if (start !== undefined)
+        opts.start = wrapCommand(plan, start);
+    const tier = str(ctx, "--tier") ?? plan.tier;
+    if (tier !== undefined)
+        opts.tier = tier;
+    const json = planJson(plan, setup);
+    const submitted = {
+        build_price: null,
+        devcontainer: json,
+        ...(repo === undefined ? {} : { repo, commit }),
+        ...(tier === undefined ? {} : { requested_tier: tier }),
+        ...(secretsAllowed.length ? { secret_files_allowed: secretsAllowed } : {}),
+        ...(localEnvBaked.length ? { local_env_baked: localEnvBaked } : {}),
+    };
+    const lines = planLines(plan, setup);
+    if (repo !== undefined && commit !== undefined) {
+        lines.splice(1, 0, `  repo      ${repo}@${commit.slice(0, 7)} → ${plan.workspaceFolder}`);
+    }
+    return { opts, label, submitted, tier, lines, json };
+}
+const snapshotCreate = async (ctx) => {
+    if (bool(ctx, "--dir"))
+        return dirSnapshotCreate(ctx);
+    if (configFlags(ctx)) {
+        await write(process.stderr, ctx.mode === "json"
+            ? jsonLine(process.stderr, { hint: "config", file: CONFIG_FILE })
+            : `building what ${CONFIG_FILE} describes (flags you pass win)\n`);
+    }
+    refuseRepoCredentials(ctx);
+    const gh = await githubCreate(ctx);
+    const form = gh ? "repo" : snapshotForm(ctx);
+    const plan = gh ? undefined : devcontainerPlan(ctx, form);
+    const setup = list(ctx, "--setup");
+    const alias = str(ctx, "--alias");
+    let opts;
+    let label;
+    let submitted;
+    let tier;
+    if (gh !== undefined) {
+        ({ opts, label, submitted, tier } = gh);
+    }
+    else if (plan !== undefined) {
+        const built = await devcontainerCreate(ctx, plan);
+        opts = built.opts;
+        label = built.label;
+        submitted = built.submitted;
+        tier = built.tier;
+        await write(process.stderr, ctx.mode === "json"
+            ? jsonLine(process.stderr, { hint: "devcontainer", devcontainer: built.json })
+            : built.lines.join("\n") + "\n");
+    }
+    else if (form === "repo") {
+        const repo = required(ctx, "--repo", "Pass --repo https://github.com/org/app.");
+        const commit = required(ctx, "--commit", "Pass --commit <40-char sha> (git rev-parse HEAD) — a branch is not a pin.");
+        const verify = required(ctx, "--verify", "Pass --verify 'bun typecheck' — the command that must exit 0 or nothing is stored.");
+        tier = required(ctx, "--tier", "Pass --tier xsmall|small|medium|large-16|large|xlarge|2xlarge (see 'promigence agent-guide --section cost').");
+        opts = { repo, commit, setup, verify: { cmd: verify }, tier: tier };
+        label = `${repo}@${commit.slice(0, 7)}`;
+        submitted = { build_price: null, repo, commit, requested_tier: tier };
+    }
+    else {
+        let source;
+        if (form === "image") {
+            const image = required(ctx, "--image", "Pass --image python:3.12 or registry/name@sha256:<digest>.");
+            checkImageRef(image);
+            source = { image };
+            label = image;
+            submitted = { build_price: null, image };
+        }
+        else {
+            const { secretsAllowed, ...dockerfile } = await dockerfileOpts(ctx);
+            source = { dockerfile };
+            const where = dockerfile.context.startsWith("tar;") ? (str(ctx, "--context") ?? dirname(str(ctx, "--dockerfile") ?? ".")) : dockerfile.context;
+            label = `${dockerfile.path ?? "Dockerfile"} in ${where}`;
+            submitted = {
+                build_price: null, dockerfile: { path: dockerfile.path ?? "Dockerfile", context: where },
+                ...(secretsAllowed?.length ? { secret_files_allowed: secretsAllowed } : {}),
+            };
+        }
+        const verify = str(ctx, "--verify");
+        const start = str(ctx, "--start");
+        tier = str(ctx, "--tier");
+        opts = { ...source, ...(setup.length ? { setup } : {}) };
+        if (verify !== undefined)
+            opts.verify = { cmd: verify };
+        if (start !== undefined)
+            opts.start = start;
+        if (tier !== undefined)
+            opts.tier = tier;
+        if (tier !== undefined)
+            submitted["requested_tier"] = tier;
+    }
+    const sources = alsoRepos(ctx);
+    if (sources.length) {
+        if (opts.repo === undefined) {
+            throw usageError("--also-repo needs --repo/--commit", "An image or a Dockerfile already carries its tree and may not have git in it: clone " +
+                "the extra repository in a --setup step, or build from --repo U --commit SHA --also-repo …");
+        }
+        opts.sources = sources;
+        submitted["sources"] = sources;
+    }
+    const c = client(ctx);
+    if (alias !== undefined)
+        opts.alias = alias;
+    const grade = gradeOpts(ctx);
+    if (grade)
+        opts.grade = grade;
+    if (bool(ctx, "--grade-output")) {
+        if (!grade) {
+            throw usageError("--grade-output needs --grade", "Pass --grade 'pytest -q tests/' alongside it: it keeps what that grader prints.");
+        }
+        opts.gradeOutput = true;
+    }
+    const key = autoIdempotencyKey(ctx);
+    if (key !== undefined)
+        opts.idempotencyKey = key;
+    let started;
+    try {
+        started = await c.snapshots.create(opts);
+    }
+    catch (e) {
+        if (plan?.source.kind === "dockerfile" && form === "repo" && e instanceof PromigenceError &&
+            e.code === "usage" && (e.message.includes("from a Dockerfile") || e.message.includes("Dockerfile builds"))) {
+            const repo = str(ctx, "--repo") ?? "<url>";
+            const commit = str(ctx, "--commit") ?? "<sha>";
+            const verify = str(ctx, "--verify") ?? "<test>";
+            const cmd = "promigence snapshot create --no-devcontainer --image <an image with git and your toolchain> "
+                + sh `--setup ${`git clone ${repo} /work/repo && git -C /work/repo checkout ${commit}`} --verify ${`cd /work/repo && ${verify}`}`;
+            throw usageError(e.message, `${e.fix} Or build it without the devcontainer's Dockerfile, from an image: ${cmd}`);
+        }
+        if (form === "repo" && plan === undefined && e instanceof PromigenceError && e.code === "usage" &&
+            /from a git repository[\s\S]*switched off/i.test(e.message)) {
+            const cmd = imageCreateCommand({
+                repo: str(ctx, "--repo"), commit: str(ctx, "--commit"), setup, verify: str(ctx, "--verify"), tier,
+            }, ecosystemOfCommands([...setup, str(ctx, "--verify") ?? ""]) ?? detect(process.cwd()).ecosystem);
+            const err = usageError("building a snapshot straight from a repository is not open in this beta; nothing was built or charged", `Build it from an image instead, with the clone as the first setup step: ${cmd}`);
+            const next = nexts([cmd, "build and verify the same environment from an image"]);
+            return emit(ctx.mode, errorEnvelope(ctx.cmd.name, err, next), errorTextLines(ctx.cmd.name, err, 2, next), 2, ctx.pointer);
+        }
+        throw e;
+    }
+    const reused = started.deduped === true;
+    const joinedBuild = started.joined === true;
+    const replay = buildReplayNote(started, str(ctx, "--idempotency-key") !== undefined);
+    const free = reused || joinedBuild || replay !== undefined;
+    const builtAt = tier ?? (typeof started["tier"] === "string" ? started["tier"] : undefined);
+    const perSecond = buildPriceOf(started);
+    const flat = !free && perSecond === undefined && typeof started.build_price === "number" ? started.build_price : undefined;
+    const said = free || flat !== undefined ? perSecond : (perSecond ?? await buildPrice(c, builtAt));
+    const charged = free ? 0 : flat ?? said?.most_usd ?? 0;
+    submitted["build_price"] = charged;
+    if (!free && said !== undefined)
+        Object.assign(submitted, { per_second_usd: said.per_second_usd, max_seconds: said.max_s });
+    if (free)
+        submitted["charged"] = false;
+    Object.assign(submitted, replayFields(started));
+    await write(process.stderr, ctx.mode === "json"
+        ? JSON.stringify({
+            hint: "build_price", build_price: charged, unit: "USD", ...(tier === undefined ? {} : { tier }),
+            ...(!free && said !== undefined ? { per_second_usd: said.per_second_usd, max_seconds: said.max_s } : {}),
+            ...(reused ? { deduped: true } : {}), ...(joinedBuild ? { joined: true } : {}),
+            ...(replay === undefined ? {} : { replayed: true }),
+        }) + "\n"
+        : replay !== undefined
+            ? `build_price: $0.00 - ${replay}\n`
+            : reused
+                ? `build_price: $0.00 - an identical build already ran (${started.build_id}); reusing it, nothing charged\n`
+                : joinedBuild
+                    ? `build_price: $0.00 - joining an identical build already running (${started.build_id}); it is charged once\n`
+                    : flat !== undefined
+                        ? `build_price: $${flat.toFixed(2)} (tier ${tier ?? "default"}) - building ${label}\n`
+                        : `build_price: ${buildPriceWords(said, builtAt ?? "default")} - building ${label}\n`);
+    if (sources.length && ctx.mode !== "json" && !reused) {
+        await write(process.stderr, sources
+            .map((s) => `  also      ${s.repo}@${s.commit.slice(0, 7)} -> ${s.path ?? "beside the workspace, under its own name"}`)
+            .join("\n") + "\n");
+    }
+    if (started.deduped || started.state === "verified" || started.state === "built" || (started.snapshot_id && !isBuilding(started))) {
+        return emitBuild(ctx, started, submitted);
+    }
+    const joined = started.joined === true;
+    const what = joined
+        ? `build ${started.build_id}: joined an identical build in progress (${label}, tier ${tier ?? "default"})`
+        : replay !== undefined
+            ? `build ${started.build_id}: started by the same request earlier, ${started.state} (${label}, tier ${tier ?? "default"})`
+            : `build ${started.build_id} started (${label}, tier ${tier ?? "default"})`;
+    const warned = (started.warnings ?? []).map((w) => `  warning: ${w}`);
+    if (!bool(ctx, "--wait")) {
+        const next = nexts([sh `promigence snapshot status ${started.build_id} --wait`, "wait for the build (bounded; nothing is cancelled on expiry)"], [sh `promigence snapshot status ${started.build_id} --log 80`, "the tail of the build log"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...buildFields(started), ...submitted }, next), [what, ...warned, `  next: ${next[0].cmd}`], 0, ctx.pointer);
+    }
+    await write(process.stderr, ctx.mode === "json"
+        ? jsonLine(process.stderr, { hint: joined ? "joined" : "build started", build_id: started.build_id, ...(warned.length ? { warnings: started.warnings } : {}) })
+        : [what, ...warned, `  waiting; Ctrl-C stops the wait, not the build (${sh `promigence snapshot status ${started.build_id} --wait`})`]
+            .map((l) => fieldForTerminal(process.stderr, l)).join("\n") + "\n");
+    const interrupted = (sig) => {
+        const follow = sh `promigence snapshot status ${started.build_id} --wait`;
+        const err = new PromigenceError({
+            code: "aborted_by_client",
+            message: `interrupted by ${sig}; build ${started.build_id} goes on and nothing was cancelled (it is billed per second until it ends)`,
+            fix: `Follow it: ${follow}.`,
+            exitCode: 130,
+        });
+        const next = nexts([follow, "keep waiting for the build"], [sh `promigence snapshot status ${started.build_id} --log 80`, "what the builder is doing"]);
+        const env = errorEnvelope(ctx.cmd.name, err, next);
+        env["build_id"] = started.build_id;
+        env["cancelled"] = false;
+        void emit(ctx.mode, env, errorTextLines(ctx.cmd.name, err, 130, next), 130, false);
+    };
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+        process.once(sig, () => interrupted(sig));
+    const bound = waitBound(ctx);
+    const waited = await c.snapshots.waitBuild(started.build_id, { waitTimeoutMs: bound });
+    if (waited.timedOut)
+        return buildWaitExpired(ctx, waited.build, bound);
+    const done = replay === undefined ? waited.build : { ...waited.build, idempotent_replay: true };
+    return emitBuild(ctx, done, { ...submitted, waited_ms: waited.waitedMs, ...(joined ? { joined: true } : {}) });
+};
+const snapshotStatus = async (ctx) => {
+    const buildId = positional(ctx, "a build id", "promigence snapshot status bld_01 --wait");
+    const logLines = str(ctx, "--log");
+    const logCount = logLines === undefined ? undefined : parseCount(logLines, "--log");
+    const c = client(ctx);
+    let build = await c.snapshots.status(buildId);
+    let waitedMs;
+    if (bool(ctx, "--wait") && (build.state === "running" || build.state === "queued")) {
+        const bound = waitBound(ctx);
+        const waited = await c.snapshots.waitBuild(buildId, { waitTimeoutMs: bound });
+        if (waited.timedOut)
+            return buildWaitExpired(ctx, waited.build, bound);
+        build = waited.build;
+        waitedMs = waited.waitedMs;
+    }
+    const extra = {};
+    if (waitedMs !== undefined)
+        extra["waited_ms"] = waitedMs;
+    let more = [];
+    if (logCount !== undefined) {
+        const log = await c.snapshots.buildLog(buildId, logCount).catch(() => undefined);
+        extra["log"] = log ?? [];
+        more = buildLogLines(log, build.state);
+    }
+    return emitBuild(ctx, build, extra, more);
+};
+export function snapshotSource(s) {
+    const live = s.verification?.["from_live_sandbox"];
+    if (typeof live === "string" && live !== "")
+        return `live snapshot of ${live}`;
+    const repo = s.repo ?? "";
+    const commit = (s.commit ?? "").slice(0, 7);
+    if (repo === "" && commit === "")
+        return "-";
+    return commit === "" ? repo : `${repo}@${commit}`;
+}
+const snapshotList = async (ctx) => {
+    const snapshots = await client(ctx).snapshots.list();
+    const next = snapshots.length
+        ? nexts([sh `promigence snapshot inspect ${snapshots[0].snapshot_id}`, "the manifest of the newest one"])
+        : nexts(["promigence snapshot create --image IMAGE:TAG --verify CMD --alias NAME --wait", "build your first snapshot from an image of your choice (a paid build: `promigence pricing`; add --setup steps)"]);
+    const lines = snapshots.length
+        ? snapshots.map((s) => `  ${s.snapshot_id}  ${s.alias ?? "-"}  ${s.tier ?? "?"}  ${snapshotSource(s)}${s.unavailable ? "  UNAVAILABLE" : ""}`)
+        : ["  (no snapshots yet)"];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { snapshots }, next), [`snapshots: ${snapshots.length}`, ...lines], 0, ctx.pointer);
+};
+const snapshotInspect = async (ctx) => {
+    const id = positional(ctx, "a snapshot id or alias", "promigence snapshot inspect snap_01");
+    const c = client(ctx);
+    const snapshot = await c.snapshots.get(id);
+    const base = snapshot.source?.kind === "base";
+    const integrity = base ? undefined : await c.snapshots.manifest(id).then((m) => m.integrity).catch(() => undefined);
+    const unavailable = typeof snapshot.unavailable === "string" && snapshot.unavailable !== "" ? snapshot.unavailable : undefined;
+    const next = unavailable
+        ? nexts([sh `promigence snapshot delete ${snapshot.snapshot_id}`, "remove it: it cannot be started again"], ["promigence sandbox snapshot <sandbox_id>", "take a new snapshot of a running sandbox"])
+        : nexts([sh `promigence run --snapshot ${snapshot.snapshot_id} --count 2 --cap 1 -- CMD`, "fork it"], [`promigence snapshot list`, "every snapshot in your org"]);
+    const timing = verifyTiming(snapshot.verification);
+    const lines = base ? [
+        `snapshot ${snapshot.snapshot_id} · tier ${snapshot.tier ?? "?"}`,
+        `  ${String(snapshot.source?.["description"] ?? "the built-in base")}`,
+        "  every sandbox created without --snapshot starts from it",
+    ] : [
+        `snapshot ${snapshot.snapshot_id}${snapshot.alias ? ` (alias ${snapshot.alias})` : ""}`,
+        `  ${snapshotSource(snapshot)} · tier ${snapshot.tier ?? "?"} · verified ${snapshot.verified === false ? "no" : "yes"}`,
+        ...(snapshot.verify?.cmd ? [`  verify: ${snapshot.verify.cmd}${timing ? ` · ${timing}` : ""}`] : []),
+        ...(snapshot.build_id ? [`  build ${snapshot.build_id}`] : []),
+        ...(integrity?.summary ? [`  integrity: ${integrity.summary}`] : []),
+        ...(unavailable ? [`  UNAVAILABLE: ${unavailable}`] : []),
+    ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { snapshot, ...(integrity ? { integrity } : {}) }, next), lines, 0, ctx.pointer);
+};
+const fork = async (ctx) => {
+    const c = client(ctx);
+    const opts = await runStartOpts(ctx, c, str(ctx, "--snapshot") === undefined ? DEFAULT_SNAPSHOT : undefined);
+    const key = autoIdempotencyKey(ctx);
+    if (key !== undefined)
+        opts.idempotencyKey = key;
+    const streaming = wantsStream(ctx);
+    const execSpec = opts.exec;
+    if (streaming)
+        delete opts.exec;
+    const started = await c.runs.start(opts);
+    const runId = started.run_id;
+    ctx.startedRunId = runId;
+    const replayed = replayNote(started, str(ctx, "--idempotency-key") !== undefined);
+    const only = started.sandboxes.length === 1 ? started.sandboxes[0].sandbox_id : undefined;
+    const execNext = nexts(only !== undefined
+        ? [sh `promigence exec --sandbox ${only} -- CMD`, "run a command in the sandbox"]
+        : [sh `promigence exec --run ${runId} --all -- CMD`, "run a command in every ready sandbox"], [sh `promigence run report ${runId} --json`, "the validity report (env vs task failures)"], [sh `promigence run kill ${runId}`, "kill every sandbox of this run"]);
+    if (bool(ctx, "--no-wait")) {
+        const env = okEnvelope(ctx.cmd.name, {
+            run_id: runId,
+            requested: { snapshot: opts.snapshot, count: opts.count, spend_cap: opts.spendCap },
+            sandboxes: started.sandboxes,
+            waited: false,
+            ...replayFields(started),
+        }, execNext);
+        return emit(ctx.mode, env, [
+            ...(replayed ? [replayed] : []),
+            `run ${runId}: ${started.sandboxes.length} sandboxes ${replayed ? "" : "queued "}(--no-wait)`,
+            ...queuedLines(started.sandboxes),
+            ...sandboxIdLines(started.sandboxes),
+            `  next: ${execNext[0].cmd}`,
+        ], 0, ctx.pointer);
+    }
+    const bound = waitBound(ctx);
+    const status = ctx.mode === "text" ? statusLine() : undefined;
+    const total = started.sandboxes.length;
+    let readyCount = 0;
+    let lastCapacity;
+    const paint = () => {
+        const line = capacityLine(lastCapacity, readyCount, total);
+        if (line)
+            status?.set(line);
+        else if (readyCount >= total)
+            status?.clear();
+    };
+    status?.set(`capacity requested: ${total} sandbox${total === 1 ? "" : "es"}`);
+    const waited = await c.runs.waitReady(runId, {
+        waitTimeoutMs: bound,
+        ...(status ? {
+            onCapacity: (cap) => { lastCapacity = cap; paint(); },
+            onReady: () => { readyCount += 1; paint(); },
+        } : {}),
+    });
+    status?.clear();
+    if (waited.timedOut)
+        return waitExpired(ctx, runId, bound, waited.sandboxes);
+    const report = await c.runs.report(runId).catch(() => undefined);
+    const up = waited.sandboxes.filter((s) => s.state === "ready" || s.state === "running").length;
+    const fields = {
+        run_id: runId,
+        requested: { snapshot: opts.snapshot, count: opts.count, spend_cap: opts.spendCap },
+        up,
+        sandboxes: waited.sandboxes,
+        waited_ms: waited.waitedMs,
+    };
+    Object.assign(fields, replayFields(started));
+    if (report) {
+        fields["fork"] = forkSummary(report.fork);
+        fields["totals"] = report.totals;
+    }
+    const exit = report ? pickExit(reportExits(report)) : 0;
+    const env = { ...okEnvelope(ctx.cmd.name, fields, execNext), ok: exit === 0 };
+    const failure = report ? runError(report, exit) : undefined;
+    if (failure)
+        env.error = failure;
+    return emit(ctx.mode, env, [
+        ...(replayed ? [replayed] : []),
+        `${up} of ${opts.count} sandbox${opts.count === 1 ? "" : "es"} ready in ${readyLine(report?.fork?.ready_ms?.p50, waited.waitedMs)} (run ${runId})`,
+        ...sandboxIdLines(waited.sandboxes),
+        ...(report && bool(ctx, "--verbose") ? [`  ${forkLine(report.fork)}`, `  ${totalsLine(report.totals)}`] : []),
+        ...(report && exit !== 0 ? failureLines(report, new Map(), false) : []),
+        `  next: ${execNext[0].cmd}`,
+    ], exit, ctx.pointer);
+};
+export function readyLine(ourMs, totalMs) {
+    return ourMs === undefined ? `${totalMs} ms` : `${fmtMs(ourMs)} on our side · ${fmtMs(totalMs)} total`;
+}
+export function sandboxIdLines(sandboxes, cap = 10) {
+    const lines = sandboxes.slice(0, cap).map((s) => `  ${s.sandbox_id} ${s.state}`);
+    if (sandboxes.length > cap)
+        lines.push(`  … ${sandboxes.length - cap} more`);
+    return lines;
+}
+function waitExpired(ctx, runId, boundMs, sandboxes) {
+    const next = nexts([sh `promigence run status ${runId} --wait`, "keep waiting; the run is untouched"], [sh `promigence run report ${runId} --json`, "the validity report so far"], [sh `promigence run kill ${runId}`, "kill the run yourself (we did not)"]);
+    const why = queuedClause(sandboxes);
+    const running = ctx.cmd.name === "run" && sandboxes.some((s) => s.state !== "ended");
+    const err = running
+        ? new TimeoutError(`run ${runId} is still going after the ${duration(boundMs)} wait (--wait-timeout); nothing was stopped${why ? `. ${why}` : ""}`, `It goes on, and bills, until each sandbox's command ends or reaches its --timeout. Follow it: ` +
+            `${sh `promigence run status ${runId} --wait`}, then ${sh `promigence run report ${runId}`}; ` +
+            `or wait longer in one call with --wait-timeout (e.g. 20m).`)
+        : new TimeoutError(`wait of ${boundMs}ms expired; nothing was killed${why ? `. ${why}` : ""}`, `Run the id-based command: ${sh `promigence run status ${runId} --wait`} (or ${sh `promigence run report ${runId}`}).`);
+    const env = errorEnvelope(ctx.cmd.name, err, next);
+    env["run_id"] = runId;
+    env["sandboxes"] = sandboxes;
+    env["killed"] = false;
+    if (running)
+        env["still_running"] = true;
+    return emit(ctx.mode, env, errorTextLines(ctx.cmd.name, err, 11, next), 11, ctx.pointer);
+}
+export function envError(code, message, fix) {
+    return { code, message, fix, docs: `${ERRORS_DOCS_URL}#${code}`, guide: sh `promigence agent-guide --section errors --code ${code}` };
+}
+export function execOutcome(res, sandboxId, timeoutMs, words = "cli") {
+    const sig = res["signal"];
+    const signal = typeof sig === "number" && sig > 0 ? sig : undefined;
+    const timedOut = res.timed_out === true || res.reason === "timeout";
+    const oom = res.oom_killed === true || res.reason === "out_of_memory";
+    const own = typeof res.exit_code === "number" ? res.exit_code : undefined;
+    const exitCode = own ?? (signal !== undefined ? 128 + signal : null);
+    const fields = { exit_code: exitCode };
+    if (signal !== undefined)
+        fields["signal"] = signal;
+    if (timedOut)
+        fields["timed_out"] = true;
+    if (oom)
+        fields["oom_killed"] = true;
+    if (res.reason !== undefined)
+        fields["reason"] = res.reason;
+    for (const k of ["wall_ms", "cpu_ms"]) {
+        const v = res[k];
+        if (typeof v === "number" && Number.isFinite(v))
+            fields[k] = Math.round(v);
+    }
+    if (exitCode === 0 && !timedOut && !oom)
+        return { exitCode, fields };
+    const code = timedOut ? "task_timeout" : oom ? "oom_over_tier" : "nonzero_exit";
+    const bound = timeoutMs === undefined ? "" : words === "mcp" ? ` (timeout_s ${Math.round(timeoutMs / 1000)})` : ` (--timeout ${duration(timeoutMs)})`;
+    const message = timedOut
+        ? `the command was killed at its timeout${bound}`
+        : oom ? "the command was killed for running out of memory"
+            : own === undefined && signal !== undefined ? `the command was killed by signal ${signal}`
+                : exitCode === null ? "the command ended without an exit code"
+                    : `the command exited ${exitCode}`;
+    const fix = code === "nonzero_exit"
+        ? `The environment was verified; the command failed. Read its stdout and stderr${res.exec_id ? ` (again: ${sh `promigence exec output ${res.exec_id} --sandbox ${sandboxId}`})` : ""}.`
+        : code === "task_timeout"
+            ? `Pass a longer ${words === "mcp" ? "timeout_s" : "--timeout"} (billed per second used, so a longer bound only costs what runs), or shorten the command.`
+            : ERROR_BY_CODE[code]?.fix ?? "";
+    return { exitCode, fields, error: envError(code, message, fix) };
+}
+function execArgv(ctx) {
+    if (ctx.cmdTail.length === 0) {
+        const example = ctx.cmd.name === "run"
+            ? "promigence run --count 2 --cap 1 -- python3 -c 'print(6*7)'"
+            : "promigence exec --sandbox sbx_01 -- bun typecheck";
+        throw usageError("no command: everything after `--` is the command to run", noCommandFix(`Write the command after --, e.g. ${example}.`));
+    }
+    return ctx.cmdTail;
+}
+function wantsStream(ctx) {
+    if (bool(ctx, "--no-stream"))
+        return false;
+    if (bool(ctx, "--stream"))
+        return true;
+    return Boolean(process.stdout.isTTY);
+}
+let followKill;
+const FOLLOW_MAX_OUTPUT = 8 * 1024 * 1024;
+const FOLLOW_RECONNECT_MS = 10 * 60_000;
+async function followExec(c, sandboxId, execOpts) {
+    let rec;
+    try {
+        rec = await c.sandboxes.execBackground(sandboxId, {
+            argv: execOpts.argv,
+            ...(execOpts.secrets ? { secrets: execOpts.secrets } : {}),
+            ...(execOpts.timeoutMs === undefined ? {} : { timeoutMs: execOpts.timeoutMs }),
+            maxOutputBytes: execOpts.maxOutputBytes ?? FOLLOW_MAX_OUTPUT,
+            follow: true,
+        });
+    }
+    catch (err) {
+        const e = toPromigenceError(err);
+        if (e.code === "usage" && /follow/.test(e.message))
+            return undefined;
+        throw err;
+    }
+    const eid = rec.exec_id;
+    followKill = () => Promise.race([
+        c.sandboxes.execs.forget(sandboxId, eid).then(() => undefined, () => undefined),
+        new Promise((r) => setTimeout(r, 2000)),
+    ]);
+    const offset = { stdout: 0, stderr: 0 };
+    let last = rec;
+    let lostAt;
+    const say = (s) => write(process.stderr, s);
+    const pump = async (fd) => {
+        for (let backoff = 500;;) {
+            try {
+                const r = await c.sandboxes.execs.read(sandboxId, eid, fd, { offset: offset[fd], waitMs: 25_000, untilOutput: true });
+                if (lostAt !== undefined) {
+                    lostAt = undefined;
+                    await say("promigence: reconnected; the command's output continues from where it was\n");
+                }
+                backoff = 500;
+                if (r.skipped > 0) {
+                    await say(`\npromigence: ${r.skipped} bytes of the command's ${fd} were not kept while this connection was down (the newest 8 MiB are)\n`);
+                }
+                if (r.data.length)
+                    await writeBytes(fd === "stdout" ? process.stdout : process.stderr, r.data);
+                offset[fd] = r.offset + r.skipped + r.data.length;
+                last = r.record;
+                if (r.eof || (r.record.state !== "running" && r.data.length === 0))
+                    return;
+            }
+            catch (err) {
+                const e = toPromigenceError(err);
+                if (e.code !== "unreachable" && e.code !== "timeout")
+                    throw err;
+                if (lostAt === undefined) {
+                    lostAt = Date.now();
+                    await say(`\npromigence: connection lost; the command keeps running in the sandbox. Reconnecting… ` +
+                        `(or later: ${sh `promigence exec output ${eid} --sandbox ${sandboxId} --follow`})\n`);
+                }
+                else if (Date.now() - lostAt > FOLLOW_RECONNECT_MS) {
+                    throw err;
+                }
+                await new Promise((r) => setTimeout(r, backoff));
+                backoff = Math.min(backoff * 2, 5_000);
+            }
+        }
+    };
+    try {
+        await Promise.all([pump("stdout"), pump("stderr")]);
+    }
+    finally {
+        followKill = undefined;
+    }
+    const fin = last.state === "running" || !last.exit ? await c.sandboxes.execs.get(sandboxId, eid, { waitMs: 5_000 }) : last;
+    await c.sandboxes.execs.forget(sandboxId, eid).catch(() => undefined);
+    const x = fin.exit;
+    const signal = typeof x?.signal === "number" ? x.signal : undefined;
+    return {
+        exec_id: eid,
+        exit_code: x?.exit_code ?? null,
+        ...(signal === undefined ? {} : { signal }),
+        ...(x?.oom_killed ? { reason: "out_of_memory" } : signal !== undefined ? { reason: "signal" } : {}),
+        ...(typeof x?.wall_ms === "number" ? { wall_ms: x.wall_ms } : {}),
+        ...(typeof x?.cpu_ms === "number" ? { cpu_ms: x.cpu_ms } : {}),
+        truncated: false,
+    };
+}
+async function streamExec(ctx, c, sandboxId, execOpts) {
+    const ndjson = ctx.mode === "json";
+    const dec = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+    const out = (fd, text) => {
+        void write(process.stdout, jsonLine(process.stdout, { stream: fd, data: text }));
+    };
+    const raw = (fd, b) => {
+        void writeBytes(fd === "stdout" ? process.stdout : process.stderr, b);
+    };
+    try {
+        return await c.sandboxes.execStream(sandboxId, execOpts, {
+            stdout: (b) => (ndjson ? out("stdout", dec.stdout.decode(b, { stream: true })) : raw("stdout", b)),
+            stderr: (b) => (ndjson ? out("stderr", dec.stderr.decode(b, { stream: true })) : raw("stderr", b)),
+        });
+    }
+    finally {
+        if (ndjson) {
+            for (const fd of ["stdout", "stderr"]) {
+                const tail = dec[fd].decode();
+                if (tail)
+                    out(fd, tail);
+            }
+        }
+    }
+}
+function asText(res) {
+    const out = { ...res };
+    for (const fd of ["stdout", "stderr"]) {
+        const k = `${fd}_b64`;
+        if (typeof res[k] !== "string")
+            continue;
+        const bytes = execOutputBytes(res, fd);
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            delete out[k];
+        }
+        catch {
+            text = new TextDecoder().decode(bytes);
+        }
+        out[fd] = text;
+    }
+    return out;
+}
+async function emitChild(res, exit, notice) {
+    if (typeof res.stdout_b64 === "string" || typeof res.stderr_b64 === "string") {
+        await writeBytes(process.stdout, execOutputBytes(res, "stdout"));
+        await writeBytes(process.stderr, execOutputBytes(res, "stderr"));
+        if (notice)
+            await write(process.stderr, notice);
+        return exitWith(exit);
+    }
+    if (res.stdout)
+        await write(process.stdout, res.stdout.endsWith("\n") ? res.stdout : res.stdout + "\n");
+    if (res.stderr)
+        await write(process.stderr, res.stderr.endsWith("\n") ? res.stderr : res.stderr + "\n");
+    if (notice)
+        await write(process.stderr, notice);
+    return exitWith(exit);
+}
+export function execTimingLine(exitCode, wallMs, totalMs, isTTY = Boolean(process.stderr.isTTY), env = process.env) {
+    if (!isTTY || env["PROMIGENCE_QUIET"] === "1" || typeof wallMs !== "number" || !Number.isFinite(wallMs))
+        return "";
+    return `promigence: exit ${exitCode ?? "none"} · ran ${fmtMs(wallMs)} on our side · ${fmtMs(totalMs)} round trip\n`;
+}
+export function endNotice(res, timeoutMs) {
+    const sig = typeof res["signal"] === "number" ? ` (signal ${res["signal"]})` : "";
+    switch (res.reason) {
+        case "timeout": return `promigence exec: the command was killed at its timeout (--timeout ${timeoutMs === undefined ? "15m" : duration(timeoutMs)})\n`;
+        case "out_of_memory": return "promigence exec: the command was killed: out of memory (a larger --tier has more)\n";
+        case "signal": return `promigence exec: the command was killed by a signal${sig}\n`;
+        default: return "";
+    }
+}
+export const MAX_OUTPUT_BYTES_PIPED = 32 * 1024 * 1024;
+function endsWithNewline(res) {
+    if (typeof res.stdout_b64 === "string") {
+        const b = execOutputBytes(res, "stdout");
+        return b.length === 0 || b[b.length - 1] === 0x0a;
+    }
+    const t = res.stdout ?? "";
+    return t === "" || t.endsWith("\n");
+}
+export function truncationNotice(kept, maxOutputBytes) {
+    return `promigence exec: output cut to the ${kept} ${bytes(maxOutputBytes ?? MAX_OUTPUT_BYTES_DEFAULT)} ` +
+        "(--max-output; at most 32m); re-run with a larger --max-output, " +
+        "or write it to a file in the sandbox and `promigence files get` it\n";
+}
+async function stdinHasData(waitMs = 150) {
+    if (process.stdin.isTTY)
+        return false;
+    let st;
+    try {
+        st = fstatSync(0);
+    }
+    catch {
+        return false;
+    }
+    if (st.isFile())
+        return st.size > 0;
+    if (!st.isFIFO() && !st.isSocket())
+        return false;
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        const done = (v) => {
+            clearTimeout(timer);
+            stdin.off("data", onData);
+            stdin.off("end", onEnd);
+            stdin.pause();
+            if (!v)
+                stdin.destroy();
+            resolve(v);
+        };
+        const onData = (d) => done(d.length > 0);
+        const onEnd = () => done(false);
+        const timer = setTimeout(() => done(false), waitMs);
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+        stdin.resume();
+    });
+}
+const exec = async (ctx) => {
+    if (bool(ctx, "--background"))
+        return execBackground(ctx);
+    const sandboxId = str(ctx, "--sandbox");
+    const runId = str(ctx, "--run");
+    if (sandboxId === undefined && runId === undefined) {
+        throw usageError("exec needs --sandbox SID or --run ID --all", "One sandbox: promigence exec --sandbox <sid> -- CMD. Every sandbox of a run: promigence exec --run <run_id> --all -- CMD.");
+    }
+    if (sandboxId !== undefined && runId !== undefined) {
+        throw usageError("exec takes --sandbox or --run, not both", "Pick one target.");
+    }
+    const argv = execArgv(ctx);
+    if (await stdinHasData()) {
+        throw usageError("exec does not pass this command's standard input to the sandbox (it would be dropped)", `Start it with stdin open: ${sh `promigence exec --sandbox ${sandboxId ?? "<sid>"} --background --stdin --`} ${argv.map(shellArg).join(" ")}, then send the input with \`promigence exec stdin <exec_id> --sandbox <sid> --data … --eof\`; or \`promigence files put\` it and read the file in the command.`);
+    }
+    const maxOutput = str(ctx, "--max-output");
+    const timeout = str(ctx, "--timeout");
+    const secrets = list(ctx, "--secret");
+    const idemKey = str(ctx, "--idempotency-key");
+    const execOpts = {
+        argv,
+        ...(secrets.length ? { secrets } : {}),
+        ...(maxOutput === undefined ? {} : { maxOutputBytes: parseMaxOutput(maxOutput) }),
+        ...(timeout === undefined ? {} : { timeoutMs: parseCommandTimeout(timeout, "--timeout") }),
+        ...(idemKey === undefined ? {} : { idempotencyKey: idemKey }),
+    };
+    const c = client(ctx);
+    if (sandboxId !== undefined) {
+        const streaming = wantsStream(ctx) && idemKey === undefined;
+        if (ctx.mode === "text" && !process.stdout.isTTY && execOpts.maxOutputBytes === undefined) {
+            execOpts.maxOutputBytes = MAX_OUTPUT_BYTES_PIPED;
+        }
+        const interrupted = (sig) => {
+            const ending = followKill?.() ?? Promise.resolve();
+            void ending.finally(() => interruptedEnvelope(sig));
+        };
+        const interruptedEnvelope = (sig) => {
+            const err = new PromigenceError({
+                code: "aborted_by_client",
+                message: `interrupted by ${sig}; the command in the sandbox ends with this connection`,
+                fix: "Nothing to fix; billed for the seconds used. The sandbox itself is still running.",
+                exitCode: 130,
+            });
+            const next = nexts([sh `promigence sandbox info ${sandboxId}`, "the sandbox and the execs it has run"]);
+            const env = errorEnvelope(ctx.cmd.name, err, next);
+            env["sandbox_id"] = sandboxId;
+            void emit(ctx.mode, env, [`promigence exec: interrupted by ${sig} (exit 130)`], 130, false);
+        };
+        for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+            process.once(sig, () => interrupted(sig));
+        const execStarted = performance.now();
+        const followed = streaming && ctx.mode === "text" && process.env["PROMIGENCE_EXEC_FOLLOW"] !== "0"
+            ? await followExec(c, sandboxId, execOpts)
+            : undefined;
+        const res = followed ?? (streaming
+            ? await streamExec(ctx, c, sandboxId, execOpts)
+            : asText(await c.sandboxes.exec(sandboxId, { ...execOpts, encoding: "base64" })));
+        const execTotalMs = performance.now() - execStarted;
+        const outcome = execOutcome(res, sandboxId, execOpts.timeoutMs);
+        const passthrough = !bool(ctx, "--no-passthrough");
+        let exit = passthrough ? (outcome.exitCode ?? 4) : (outcome.exitCode === 0 ? 0 : 4);
+        if (ctx.mode === "text") {
+            if (res.truncated && exit === 0)
+                exit = 12;
+            const notice = (res.truncated ? truncationNotice(streaming ? "first" : "last", execOpts.maxOutputBytes) : "")
+                + endNotice(res, execOpts.timeoutMs);
+            const raw = streaming || typeof res.stdout_b64 === "string";
+            const timed = execTimingLine(outcome.exitCode, res.wall_ms, execTotalMs);
+            const all = notice + timed;
+            const gap = all && raw && process.stdout.isTTY && !endsWithNewline(res) ? "\n" : "";
+            if (streaming) {
+                if (all)
+                    await write(process.stderr, gap + all);
+                return exitWith(exit);
+            }
+            return emitChild(res, exit, all ? gap + all : undefined);
+        }
+        const next = nexts(...(res.truncated
+            ? [[`${sh `promigence exec --sandbox ${sandboxId} --max-output 32m --`} ${argv.map(shellArg).join(" ")}`, "re-run with a larger --max-output"]]
+            : []), [sh `promigence sandbox kill ${sandboxId}`, "end the sandbox when you are done"]);
+        const env = okEnvelope(ctx.cmd.name, {
+            sandbox_id: sandboxId,
+            exec_id: res.exec_id,
+            argv,
+            ...outcome.fields,
+            stdout: res.stdout ?? "",
+            stderr: res.stderr ?? "",
+            truncated: res.truncated ?? false,
+            ...(res.stdout_b64 === undefined ? {} : { stdout_b64: res.stdout_b64 }),
+            ...(res.stderr_b64 === undefined ? {} : { stderr_b64: res.stderr_b64 }),
+            ...(res["idempotent_replay"] === true ? { idempotent_replay: true } : {}),
+        }, next);
+        if (outcome.error) {
+            env.ok = false;
+            env.error = outcome.error;
+        }
+        return emit(ctx.mode, env, [], exit, false);
+    }
+    const id = runId;
+    if (!bool(ctx, "--all")) {
+        throw usageError("--run needs --all", `Target every ready sandbox: ${sh `promigence exec --run ${id} --all -- CMD`}.`);
+    }
+    let sandboxes = await c.runs.sandboxes(id);
+    if (bool(ctx, "--wait")) {
+        const bound = waitBound(ctx);
+        const waited = await c.runs.waitReady(id, { waitTimeoutMs: bound });
+        if (waited.timedOut)
+            return waitExpired(ctx, id, bound, waited.sandboxes);
+        sandboxes = waited.sandboxes;
+    }
+    const targets = sandboxes.filter((s) => s.state === "ready" || s.state === "running" || s.state === "paused");
+    const skipped = sandboxes
+        .filter((s) => isWaiting(s.state) || s.state === "ended")
+        .map((s) => ({
+        sandbox_id: s.sandbox_id,
+        state: s.state,
+        reason: typeof s.queued_message === "string" && s.queued_message !== ""
+            ? `queued: ${s.queued_message} (pass --wait)`
+            : s.state === "awaiting_capacity"
+                ? "still waiting for capacity being added (pass --wait)"
+                : s.state === "queued" ? "not ready (pass --wait)" : "ended",
+    }));
+    const rows = await Promise.all(targets.map(async (s) => {
+        try {
+            const res = await c.sandboxes.exec(s.sandbox_id, execOpts);
+            const o = execOutcome(res, s.sandbox_id, execOpts.timeoutMs);
+            return {
+                sandbox_id: s.sandbox_id, exec_id: res.exec_id, ...o.fields, exit_code: o.exitCode,
+                stdout: res.stdout ?? "", stderr: res.stderr ?? "", truncated: res.truncated ?? false,
+                ...(o.error ? { error: o.error } : {}),
+            };
+        }
+        catch (err) {
+            const e = toPromigenceError(err);
+            return { sandbox_id: s.sandbox_id, error: e.toJSON(), exit: e.cliExit };
+        }
+    }));
+    const codes = [];
+    for (const r of rows) {
+        if (!("exec_id" in r))
+            codes.push(r.exit);
+        else if (r.exit_code !== 0)
+            codes.push(4);
+    }
+    if (skipped.length)
+        codes.push(12);
+    const exit = pickExit(codes);
+    const next = nexts([sh `promigence run report ${id} --json`, "the validity report for this run"], [sh `promigence run kill ${id}`, "kill every sandbox of this run"]);
+    const env = {
+        ...okEnvelope(ctx.cmd.name, { run_id: id, argv, sandboxes: rows, ...(skipped.length ? { skipped } : {}) }, next),
+        ok: exit === 0,
+    };
+    if (exit !== 0) {
+        const first = exit === 12 && skipped.length ? undefined
+            : rows.find((r) => (!("exec_id" in r) ? r.exit === exit : r.exit_code !== 0 && exit === 4))
+                ?? rows.find((r) => r.error !== undefined);
+        const ended = skipped.filter((k) => k.state === "ended").length;
+        const waiting = skipped.length - ended;
+        const of = `of ${sandboxes.length} sandbox${sandboxes.length === 1 ? "" : "es"}`;
+        env.error = first?.error ?? envError("not_started", [
+            ...(waiting ? [`${waiting} ${of} ${waiting === 1 ? "was" : "were"} not ready yet`] : []),
+            ...(ended ? [`${ended} ${waiting ? "had" : `${of} had`} ended`] : []),
+        ].join(" and ") + " and did not run the command", waiting
+            ? `Pass --wait to wait for the ones not ready: ${sh `promigence exec --run ${id} --all --wait --`} ${argv.map(shellArg).join(" ")}.`
+            : `An ended sandbox runs nothing again; start new ones (${sh `promigence run report ${id}`} says why these ended).`);
+    }
+    if (ctx.mode === "text") {
+        const out = [];
+        const errOut = [];
+        for (const r of rows) {
+            if (!("exec_id" in r))
+                continue;
+            out.push(...tagLines(r.sandbox_id, r.stdout, Boolean(process.stdout.isTTY)));
+            errOut.push(...tagLines(r.sandbox_id, r.stderr, Boolean(process.stderr.isTTY)));
+        }
+        if (out.length)
+            await write(process.stdout, out.join("\n") + "\n");
+        if (errOut.length)
+            await write(process.stderr, errOut.join("\n") + "\n");
+    }
+    const lines = rows.map((r) => (!("exec_id" in r)
+        ? `  ${r.sandbox_id}: ${r.error.code}: ${r.error.message}`
+        : `  ${r.sandbox_id}: exit ${r.exit_code}${r.error && r.error.code !== "nonzero_exit" ? ` (${r.error.message})` : ""}${r.truncated ? " (output cut to the last --max-output bytes; re-run with a larger --max-output)" : ""}`));
+    for (const k of skipped)
+        lines.push(`  ${k.sandbox_id}: skipped, ${k.reason}`);
+    return emit(ctx.mode, env, [`${sh `promigence exec --run ${id} --all`}: ${rows.length} sandbox${rows.length === 1 ? "" : "es"}`, ...lines], exit, false, "stderr");
+};
+export function tagLines(sandboxId, text, escape = false) {
+    if (!text)
+        return [];
+    const body = text.endsWith("\n") ? text.slice(0, -1) : text;
+    return body.split("\n").map((l) => `${sandboxId}: ${escape ? escapeLine(l) : l}`);
+}
+async function runImageSnapshot(ctx, c) {
+    if (!ctx.flags.has("--image"))
+        return undefined;
+    if (ctx.flags.has("--snapshot")) {
+        throw usageError("run takes --snapshot or --image, not both", "An existing snapshot: promigence run --snapshot H --count N -- CMD. An image: promigence run --image REF@sha256:<digest> --count N -- CMD.");
+    }
+    const image = required(ctx, "--image", "Pass --image python:3.12 or registry/name@sha256:<digest>.");
+    checkImageRef(image);
+    const count = parseCount(required(ctx, "--count", "Pass --count N (number of sandboxes to fork)."), "--count");
+    const cap = await spendCap(ctx, c);
+    const most = await buildPrice(c);
+    const price = most.most_usd;
+    const timeout = str(ctx, "--timeout");
+    const quoted = await c.runs.quote({
+        snapshot: DEFAULT_SNAPSHOT, count, ...(timeout === undefined ? {} : { timeoutMs: parseDuration(timeout, "--timeout") }),
+    }).then((q) => q.max_cost).catch(() => undefined);
+    const needed = Math.ceil((price + (quoted ?? 0)) * 100) / 100;
+    if (cap < price + (quoted ?? 0)) {
+        const existing = (quoted ?? 0) <= cap ? await existingImageSnapshot(c, image) : undefined;
+        throw new SpendCapError(`a new image's snapshot build can cost up to ${moneyUsd(price)} on top of the run` +
+            `${quoted === undefined ? "" : ` (about ${moneyUsd(quoted)})`}, over --cap ${moneyUsd(cap)}; nothing was built or started`, (existing === undefined ? "" : `This image already has snapshot ${existing}: run it under this cap with ${sh `promigence run --snapshot ${existing}`} instead of --image (any start command or settings it was made with come with it). Or `) +
+            `${existing === undefined ? "Pass" : "pass"} --cap ${needed.toFixed(2)} or more (a build is billed per second while it runs, only when this image has no snapshot yet, and reused free after), ` +
+            `or build it first, ${sh `promigence snapshot create --image ${image} --wait`}, and run its snapshot with --snapshot.`);
+    }
+    await write(process.stderr, ctx.mode === "json"
+        ? jsonLine(process.stderr, { hint: "image snapshot", image })
+        : `image ${image}: creating or reusing its snapshot (a first build takes minutes)\n`);
+    let charged = 0;
+    let perSecond = false;
+    let buildId;
+    const buildOpts = { image, allowBuild: true };
+    const snapshotId = await imageSnapshot(c, buildOpts, {
+        onBuild: async (b) => {
+            const free = b.deduped === true || b.joined === true || b.idempotent_replay === true || b.state === "verified" || b.state === "built";
+            const said = buildPriceOf(b);
+            perSecond = !free && said !== undefined;
+            charged = free ? 0 : (typeof b.build_price === "number" ? b.build_price : price);
+            buildId = b.build_id;
+            await write(process.stderr, ctx.mode === "json"
+                ? jsonLine(process.stderr, {
+                    hint: "build_price", build_price: charged, unit: "USD", image,
+                    ...(perSecond && said ? { per_second_usd: said.per_second_usd, max_seconds: said.max_s } : {}),
+                    ...(b.build_id ? { build_id: b.build_id } : {}), ...(free ? { charged: false } : {}),
+                })
+                : free
+                    ? `build_price: $0.00 - this image's snapshot already exists; reusing it, nothing charged\n`
+                    : perSecond && said
+                        ? `build_price: ${buildPriceWords(said)} - building ${image}'s snapshot (billed per second while it builds; counted in --cap)\n`
+                        : `build_price: $${charged.toFixed(2)} - building ${image}'s snapshot (charged once it verifies; counted in --cap)\n`);
+        },
+    });
+    if (perSecond && buildId !== undefined) {
+        const done = await c.snapshots.status(buildId).catch(() => undefined);
+        if (done !== undefined && typeof done.cost_usd === "number" && !isBuilding(done))
+            charged = done.cost_usd;
+    }
+    await write(process.stderr, ctx.mode === "json"
+        ? jsonLine(process.stderr, { hint: "image snapshot ready", image, snapshot_id: snapshotId })
+        : fieldForTerminal(process.stderr, `image ${image}: snapshot ${snapshotId}`) + "\n");
+    return { snapshotId, charged, ...(buildId === undefined ? {} : { buildId }) };
+}
+async function existingImageSnapshot(c, image) {
+    try {
+        const r = await c.images.resolve(image);
+        const digests = new Set([r.digest, r.platform_digest].filter((d) => typeof d === "string" && d !== ""));
+        let cursor;
+        for (let page = 0; page < 5; page++) {
+            const p = await c.snapshots.listPage({ limit: 100, ...(cursor === undefined ? {} : { cursor }) });
+            const hit = p.items.find((s) => s.source?.kind === "image" && typeof s.source.digest === "string" && digests.has(s.source.digest) &&
+                s.source["from_sandbox"] === undefined && !s.unavailable && !(s.setup?.length) && !s.verify?.cmd &&
+                (s.tier === undefined || s.tier === "small"));
+            if (hit)
+                return hit.snapshot_id;
+            if (!p.nextCursor)
+                return undefined;
+            cursor = p.nextCursor;
+        }
+    }
+    catch {
+    }
+    return undefined;
+}
+const runComposite = async (ctx) => {
+    const argv = execArgv(ctx);
+    const c = client(ctx);
+    const built = await runImageSnapshot(ctx, c);
+    const opts = await runStartOpts(ctx, c, built?.snapshotId ?? (str(ctx, "--snapshot") === undefined ? DEFAULT_SNAPSHOT : undefined));
+    if (built !== undefined && built.charged > 0 && opts.spendCap !== undefined) {
+        opts.spendCap = Math.max(0, Math.round((opts.spendCap - built.charged) * 1e9) / 1e9);
+    }
+    const keep = bool(ctx, "--keep");
+    const maxOutput = str(ctx, "--max-output");
+    opts.exec = {
+        argv,
+        killOnExit: !keep,
+        ...(maxOutput === undefined ? {} : { maxOutputBytes: parseMaxOutput(maxOutput) }),
+        ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+    };
+    const explicitKey = str(ctx, "--idempotency-key");
+    if (explicitKey !== undefined)
+        opts.idempotencyKey = explicitKey;
+    const failOn = str(ctx, "--fail-on") ?? "task";
+    if (failOn !== "task" && failOn !== "env" && failOn !== "none") {
+        throw usageError(`--fail-on: '${failOn}' is not a mode`, "Pass --fail-on task | env | none (default task).");
+    }
+    const streaming = wantsStream(ctx);
+    const execSpec = opts.exec;
+    if (streaming)
+        delete opts.exec;
+    const started = await c.runs.start(opts);
+    const runId = started.run_id;
+    ctx.startedRunId = runId;
+    const replayed = replayNote(started, true);
+    const waitingWhy = queuedLines(started.sandboxes);
+    await write(process.stderr, ctx.mode === "json"
+        ? jsonLine(process.stderr, { hint: "run started", run_id: runId, sandboxes: started.sandboxes.length, ...replayFields(started) })
+        : `${replayed ? `${fieldForTerminal(process.stderr, replayed)}\n` : ""}`
+            + `${fieldForTerminal(process.stderr, `run ${runId} started: ${started.sandboxes.length} sandbox${started.sandboxes.length === 1 ? "" : "es"} - report: ${sh `promigence run report ${runId}`}`)}\n`
+            + waitingWhy.map((l) => `${fieldForTerminal(process.stderr, l)}\n`).join(""));
+    let interrupted = false;
+    let interruptP;
+    const yieldToSignal = async () => { if (interruptP)
+        await interruptP; };
+    const onSignal = (sig) => {
+        if (interrupted)
+            return;
+        interrupted = true;
+        interruptP = (async () => {
+            let killed = false;
+            if (!keep) {
+                try {
+                    await c.runs.kill(runId);
+                    killed = true;
+                }
+                catch {
+                    killed = false;
+                }
+            }
+            const next = keep || killed
+                ? nexts([sh `promigence run report ${runId}`, "what the sandboxes did"])
+                : nexts([sh `promigence run kill ${runId}`, "the kill did not complete; kill the run yourself"]);
+            const err = new PromigenceError({
+                code: "aborted_by_client",
+                message: `interrupted by ${sig}; ${keep ? "--keep: sandboxes left running" : killed ? "sandboxes killed" : "the kill did not complete"}`,
+                fix: keep || killed ? "Nothing to fix; billed for the seconds used." : `Kill the run yourself: ${sh `promigence run kill ${runId}`}.`,
+                exitCode: 130,
+            });
+            const env = errorEnvelope(ctx.cmd.name, err, next);
+            env["run_id"] = runId;
+            env["killed"] = killed;
+            return emit(ctx.mode, env, [`promigence run: interrupted by ${sig} (exit 130)`, `  killed: ${killed}`, `  next: ${next[0].cmd}`], 130, false);
+        })();
+    };
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"])
+        process.on(sig, () => onSignal(sig));
+    const bound = waitBound(ctx);
+    const waitStarted = Date.now();
+    const status = ctx.mode === "text" ? statusLine() : undefined;
+    const watch = (total) => {
+        let readyCount = 0;
+        let last;
+        const paint = () => {
+            const line = capacityLine(last, readyCount, total);
+            if (line)
+                status?.set(line);
+            else if (readyCount >= total)
+                status?.clear();
+        };
+        status?.set(`capacity requested: ${total} sandbox${total === 1 ? "" : "es"}`);
+        return status
+            ? {
+                onCapacity: (cap) => { last = cap; paint(); },
+                onReady: () => { readyCount += 1; paint(); },
+            }
+            : {};
+    };
+    if (streaming) {
+        const ready = await c.runs.waitReady(runId, {
+            waitTimeoutMs: bound,
+            ...watch(started.sandboxes.length),
+        });
+        status?.clear();
+        await yieldToSignal();
+        if (ready.timedOut)
+            return waitExpired(ctx, runId, bound, ready.sandboxes);
+        const targets = ready.sandboxes.filter((s) => s.state === "ready" || s.state === "running");
+        const many = targets.length > 1;
+        const sink = (sid, fd) => {
+            const dec = new TextDecoder();
+            let partial = "";
+            const put = (text, last) => {
+                if (ctx.mode === "json") {
+                    if (text || !last)
+                        void write(process.stdout, jsonLine(process.stdout, { stream: fd, sandbox_id: sid, data: text }));
+                    return;
+                }
+                const target = fd === "stdout" ? process.stdout : process.stderr;
+                if (!many) {
+                    void write(target, text);
+                    return;
+                }
+                const line = target.isTTY ? escapeLine : (l) => l;
+                partial += text;
+                let nl;
+                while ((nl = partial.indexOf("\n")) >= 0) {
+                    void write(target, `${sid}: ${line(partial.slice(0, nl))}\n`);
+                    partial = partial.slice(nl + 1);
+                }
+                if (last && partial) {
+                    void write(target, `${sid}: ${line(partial)}\n`);
+                    partial = "";
+                }
+            };
+            return {
+                feed: (b) => put(dec.decode(b, { stream: true }), false),
+                end: () => put(dec.decode(), true),
+            };
+        };
+        await Promise.all(targets.map(async (s) => {
+            const out = sink(s.sandbox_id, "stdout");
+            const errOut = sink(s.sandbox_id, "stderr");
+            let failed;
+            try {
+                await c.sandboxes.execStream(s.sandbox_id, {
+                    ...execSpec,
+                    terminal: true,
+                    killOnExit: !keep,
+                }, { stdout: out.feed, stderr: errOut.feed });
+            }
+            catch (err) {
+                failed = toPromigenceError(err);
+            }
+            out.end();
+            errOut.end();
+            if (failed)
+                await write(process.stderr, forTerminal(process.stderr, `${s.sandbox_id}: ${failed.code}: ${failed.message}`) + "\n");
+        }));
+    }
+    if (!streaming) {
+        const ready = await c.runs.waitReady(runId, {
+            waitTimeoutMs: bound,
+            ...watch(started.sandboxes.length),
+        });
+        status?.clear();
+        await yieldToSignal();
+        if (ready.timedOut)
+            return waitExpired(ctx, runId, bound, ready.sandboxes);
+    }
+    const waited = await c.runs.waitDone(runId, { waitTimeoutMs: bound });
+    await yieldToSignal();
+    if (waited.timedOut)
+        return waitExpired(ctx, runId, bound, waited.run.sandboxes ?? []);
+    const { report, settled } = await settledReport(c, runId, keep, Math.max(0, bound - (Date.now() - waitStarted)));
+    await yieldToSignal();
+    const codes = reportExits(report);
+    const filtered = failOn === "none" ? [] : failOn === "env" ? codes.filter((x) => x !== 4) : codes;
+    const exit = pickExit(filtered);
+    const kept = keep ? (report.sandboxes ?? []).filter((s) => s.state !== "ended").map((s) => s.sandbox_id) : [];
+    const capPaused = (report.sandboxes ?? []).find((s) => limitPauseOf(s));
+    const next = nexts(...(capPaused
+        ? [limitPauseOf(capPaused) === "spend_cap"
+                ? [sh `promigence sandbox resume ${capPaused.sandbox_id} --cap USD`, "go on: a cap above the run's (its files and state are kept)"]
+                : ["promigence billing card", `add a card, then ${sh `promigence sandbox resume ${capPaused.sandbox_id}`}`]]
+        : []), [sh `promigence run report ${runId} --json`, "the full validity report (per-sandbox evidence)"], ...((report.totals?.env_failed ?? 0) > 0
+        ? [[sh `promigence run replay ${runId}`, "re-fork the env failures (a replay is a new sandbox, billed like any other)"]]
+        : []), ...(kept.length
+        ? [[sh `promigence run kill ${runId}`, "end the kept sandboxes: they bill until killed or their --timeout"]]
+        : []));
+    const outputs = streaming ? new Map() : await outputTails(c, report.sandboxes ?? []);
+    const firstExec = (report.sandboxes ?? []).find((s) => s.execs?.length);
+    if (firstExec) {
+        const eid = firstExec.execs[firstExec.execs.length - 1].exec_id;
+        next.push(...nexts([sh `promigence exec output ${eid} --sandbox ${firstExec.sandbox_id}`, "one sandbox's full command output"]));
+    }
+    const fields = {
+        run_id: runId,
+        state: report.state,
+        snapshot: opts.snapshot,
+        count: opts.count,
+        argv,
+        fork: forkSummary(report.fork),
+        totals: report.totals,
+        sandboxes: (report.sandboxes ?? []).map((s) => ({
+            sandbox_id: s.sandbox_id,
+            outcome: s.outcome,
+            ...(limitPauseOf(s) ? { state: s.state, pause_reason: limitPauseOf(s) } : {}),
+            ...(s.execs?.length ? { exec: s.execs[s.execs.length - 1] } : {}),
+            ...(outputs.has(s.sandbox_id) ? { output: outputs.get(s.sandbox_id) } : {}),
+            ...(s.failure ? { failure: s.failure } : {}),
+            ...(s.warnings?.length ? { warnings: s.warnings } : {}),
+            ...gradeFields(s),
+        })),
+        exit,
+    };
+    if (report.cost) {
+        fields["cost"] = settled
+            ? { ...report.cost, final: true }
+            : { ...report.cost, final: false, not_final: settledWhy(report, keep) };
+    }
+    if (built !== undefined) {
+        fields["build"] = { snapshot_id: built.snapshotId, charged: built.charged, ...(built.buildId ? { build_id: built.buildId } : {}) };
+    }
+    if (report.grade)
+        fields["grade"] = report.grade;
+    if (keep)
+        fields["kept"] = kept;
+    Object.assign(fields, replayFields(started));
+    await yieldToSignal();
+    const env = { ...okEnvelope(ctx.cmd.name, fields, next), ok: exit === 0 };
+    const failure = runError(report, exit);
+    if (failure)
+        env.error = failure;
+    const keptLine = kept.length
+        ? [`  --keep: ${kept.length} sandbox${kept.length === 1 ? "" : "es"} left running (${kept.join(", ")}), billed until killed or --timeout`]
+        : [];
+    const grade = gradeLine(report.grade);
+    const printed = !streaming && ctx.mode === "text" ? commandOutputLines(report, outputs) : [];
+    const lines = [
+        ...printed,
+        settled ? runHeadline(report, opts.count) : runHeadline(report, opts.count).replace(/ · charged (\$[0-9.]+)$/, " · charged $1 so far"),
+        ...(settled ? [] : [`  cost not final: ${settledWhy(report, keep)} (${sh `promigence run report ${runId}`} has the final amount)`]),
+        ...(built !== undefined && built.charged > 0 ? [`  snapshot build: ${moneyUsd(built.charged)} (${built.buildId ?? built.snapshotId}), within --cap`] : []),
+        ...(bool(ctx, "--verbose") ? [`  ${forkLine(report.fork)}`, `  ${totalsLine(report.totals)}`] : []),
+        ...(grade ? [`  ${grade}`] : []),
+        ...gradeRowLines(report),
+        ...failureLines(report, outputs, !streaming),
+        ...limitPauseLines(report),
+        ...keptLine,
+        ...(exit === 0 ? [] : [`  exit ${exit} (--fail-on ${failOn})`]),
+    ];
+    return emit(ctx.mode, env, lines, exit, ctx.pointer, streaming ? "stderr" : "payload");
+};
+function gradeFields(s) {
+    const r = s;
+    const out = {};
+    for (const k of ["graded", "passed", "score", "holdout_passed", "holdout_score", "grade"]) {
+        if (r[k] !== undefined && r[k] !== null)
+            out[k] = r[k];
+    }
+    return out;
+}
+export const GRADES_SHOWN = 10;
+export function gradeRowLines(report) {
+    const graded = (report.sandboxes ?? []).filter((s) => s.graded === true && (s.passed !== undefined || s.holdout_passed !== undefined));
+    const lines = graded.slice(0, GRADES_SHOWN).map((s) => `  ${s.sandbox_id}: grade: ${sandboxGrade(s)}`);
+    if (graded.length > GRADES_SHOWN) {
+        lines.push(`  … ${graded.length - GRADES_SHOWN} more graded (${sh `promigence run report ${report.run_id} --sandboxes all`})`);
+    }
+    return lines;
+}
+export function commandOutputLines(report, outputs) {
+    const lines = [];
+    let cut = 0;
+    for (const s of report.sandboxes ?? []) {
+        const o = outputs.get(s.sandbox_id);
+        if (!o)
+            continue;
+        if (o.truncated)
+            cut += 1;
+        lines.push(...tagLines(s.sandbox_id, o.stdout));
+    }
+    const ran = (report.sandboxes ?? []).filter((s) => s.execs?.length).length;
+    const unread = ran - outputs.size;
+    if (cut > 0 || unread > 0) {
+        const first = (report.sandboxes ?? []).find((s) => s.execs?.length);
+        const eid = first?.execs?.at(-1)?.exec_id;
+        const how = eid && first ? sh `promigence exec output ${eid} --sandbox ${first.sandbox_id}` : sh `promigence run report ${report.run_id}`;
+        const what = [cut > 0 ? `${cut} cut to the last ${OUTPUT_TAIL_CHARS} characters` : "", unread > 0 ? `${unread} more not shown` : ""].filter(Boolean).join(", ");
+        lines.push(`  (output: ${what}; one sandbox's in full: ${how})`);
+    }
+    return lines;
+}
+export const SETTLE_WAIT_MS = 15_000;
+const SETTLE_POLL_MS = 250;
+const allSettled = (report) => (report.sandboxes ?? []).every((s) => s.state === "ended");
+const LIMIT_PAUSES = { cap_paused: "spend_cap", credits_paused: "credits_exhausted" };
+export const limitPauseOf = (s) => s.state === "paused" ? LIMIT_PAUSES[s.failure?.code ?? ""] : undefined;
+async function settledReport(c, runId, keep, budgetMs) {
+    const until = Date.now() + Math.min(budgetMs, SETTLE_WAIT_MS);
+    for (;;) {
+        const report = await c.runs.report(runId);
+        if (allSettled(report))
+            return { report, settled: true };
+        if (keep)
+            return { report, settled: false };
+        if ((report.sandboxes ?? []).every((s) => s.state === "ended" || limitPauseOf(s)))
+            return { report, settled: false };
+        if (Date.now() + SETTLE_POLL_MS > until)
+            return { report, settled: false };
+        await new Promise((r) => setTimeout(r, SETTLE_POLL_MS));
+    }
+}
+function settledWhy(report, keep) {
+    const open = (report.sandboxes ?? []).filter((s) => s.state !== "ended");
+    if (keep)
+        return "kept sandboxes are still running and billing until they are killed or time out";
+    const paused = open.filter((s) => limitPauseOf(s)).length;
+    if (paused && paused === open.length) {
+        return `${paused} sandbox${paused === 1 ? " is" : "es are"} paused at a limit (paused time is not billed); ${paused === 1 ? "its" : "their"} last charge lands when ${paused === 1 ? "it ends" : "they end"}`;
+    }
+    return `${open.length} sandbox${open.length === 1 ? " has" : "es have"} not ended yet, so ${open.length === 1 ? "its" : "their"} last charge is still to land`;
+}
+const OUTCOME_EXIT = {
+    env_failed: 3, grader_failed: 3, not_started: 12, cap_killed: 12, expired: 12, stopped_by_support: 12,
+    task_failed: 4, snapshot_failed: 4,
+};
+const OUTCOME_CODE = {
+    env_failed: "env_failed", grader_failed: "grader_failed", not_started: "not_started", cap_killed: "cap_killed",
+    expired: "expired", stopped_by_support: "stopped_by_support", task_failed: "nonzero_exit", snapshot_failed: "snapshot_failed",
+};
+function failureFix(runId, s) {
+    const f = s.failure;
+    if (f?.fix)
+        return f.fix;
+    const code = f?.code ?? OUTCOME_CODE[s.outcome ?? ""] ?? "";
+    const execId = s.execs?.at(-1)?.exec_id;
+    const filled = (lookupError(code)?.fix ?? "")
+        .replaceAll("`promigence exec output {exec_id}`", execId ? `\`${sh `promigence exec output ${execId} --sandbox ${s.sandbox_id}`}\`` : "{exec_id}")
+        .replaceAll("{run_id}", runId).replaceAll("{sandbox_id}", s.sandbox_id);
+    return filled && !/\{[a-z_]+\}/.test(filled)
+        ? filled
+        : `Read this sandbox's evidence: \`${sh `promigence run report ${runId} --sandbox ${s.sandbox_id}`}\`.`;
+}
+export function runError(report, exit) {
+    if (exit === 0)
+        return undefined;
+    const rows = report.sandboxes ?? [];
+    const s = rows.find((x) => OUTCOME_EXIT[x.outcome ?? ""] === exit) ?? rows.find((x) => x.failure);
+    if (!s) {
+        return envError("internal", `run ${report.run_id} exited ${exit} with no sandbox to show for it`, `Read the report: ${sh `promigence run report ${report.run_id}`}.`);
+    }
+    const f = s.failure;
+    const code = f?.code ?? OUTCOME_CODE[s.outcome ?? ""] ?? "internal";
+    const exitCode = s.execs?.at(-1)?.exit_code;
+    const message = f?.message
+        ?? `${s.sandbox_id} ${s.outcome}${f?.code ? ` (${f.code})` : ""}${typeof exitCode === "number" ? `: the command exited ${exitCode}` : ""}`;
+    return envError(code, message, failureFix(report.run_id, s));
+}
+export function runHeadline(report, count) {
+    const t = (report.totals ?? {});
+    const others = Object.entries(t)
+        .filter(([k, v]) => !["completed", "env_verified", "evidence_missing"].includes(k) && typeof v === "number" && v > 0)
+        .map(([k, v]) => `${v} ${k === "stopped_by_support" ? "stopped by Promigence support" : k}`);
+    const done = typeof t["completed"] === "number" ? t["completed"] : 0;
+    return `run ${report.run_id}: ${done} of ${count} completed${others.length ? ` · ${others.join(" · ")}` : ""}` +
+        `${report.cost ? ` · charged ${moneyUsd(report.cost.charged)}` : ""}`;
+}
+export const FAILURES_SHOWN = 5;
+export function limitPauseLines(report) {
+    const lines = [];
+    const paused = (report.sandboxes ?? []).filter((x) => limitPauseOf(x));
+    for (const s of paused.slice(0, FAILURES_SHOWN)) {
+        const cap = s.failure?.evidence?.["spend_cap"] ?? report.spend_cap;
+        const usd = typeof cap === "number" ? moneyUsd(cap) : undefined;
+        if (limitPauseOf(s) === "spend_cap") {
+            lines.push(`  ${s.sandbox_id}: paused: spend cap reached${usd ? ` (${usd})` : ""}; its files and state are kept`);
+            lines.push(`    go on: ${sh `promigence sandbox resume ${s.sandbox_id} --cap USD`}${usd ? ` (above the run's ${usd})` : ""}, or end it: ${sh `promigence sandbox kill ${s.sandbox_id}`}`);
+        }
+        else {
+            lines.push(`  ${s.sandbox_id}: paused: the organization's credits ran out; its files and state are kept`);
+            lines.push(`    go on: add a card (owners: promigence billing card), then ${sh `promigence sandbox resume ${s.sandbox_id}`}, or end it: ${sh `promigence sandbox kill ${s.sandbox_id}`}`);
+        }
+    }
+    if (paused.length > FAILURES_SHOWN) {
+        lines.push(`  … ${paused.length - FAILURES_SHOWN} more paused the same way: ${sh `promigence sandbox list --state paused`}`);
+    }
+    return lines;
+}
+export function failureLines(report, outputs, stderrTail) {
+    const failed = (report.sandboxes ?? []).filter((x) => x.state === "ended" && x.outcome !== "completed" && x.outcome !== "superseded");
+    const lines = [];
+    for (const s of failed.slice(0, FAILURES_SHOWN)) {
+        const f = s.failure;
+        const ex = s.execs?.at(-1);
+        const billed = s.billable_seconds === undefined ? "" : ` · ${s.billable_seconds}s ${moneyUsd(s.cost ?? 0)}`;
+        lines.push(`  ${s.sandbox_id}: ${s.outcome}${f?.code ? ` (${f.code})` : ""}${typeof ex?.exit_code === "number" ? ` · exit ${ex.exit_code}` : ""}${billed}`);
+        if (f?.message)
+            lines.push(`    ${f.message}`);
+        if (stderrTail) {
+            const err = (outputs.get(s.sandbox_id)?.stderr ?? "").replace(/\n+$/, "");
+            if (err)
+                for (const l of err.split("\n").slice(-3))
+                    lines.push(`    stderr: ${l}`);
+        }
+        lines.push(`    fix: ${failureFix(report.run_id, s)}`);
+        if (ex?.exec_id)
+            lines.push(`    next: ${sh `promigence exec output ${ex.exec_id} --sandbox ${s.sandbox_id} --stderr`}`);
+    }
+    if (failed.length > FAILURES_SHOWN) {
+        lines.push(`  … ${failed.length - FAILURES_SHOWN} more: ${sh `promigence run report ${report.run_id} --sandboxes failed`}`);
+    }
+    return lines;
+}
+export const OUTPUT_TAIL_SANDBOXES = 20;
+export const OUTPUT_TAIL_CHARS = 4096;
+export async function outputTails(c, sandboxes) {
+    const out = new Map();
+    const ran = sandboxes.filter((s) => s.execs?.length).slice(0, OUTPUT_TAIL_SANDBOXES);
+    await Promise.all(ran.map(async (s) => {
+        const eid = s.execs[s.execs.length - 1].exec_id;
+        try {
+            const rec = await c.sandboxes.get(s.sandbox_id);
+            const o = (rec?.execs ?? []).find((e) => e.exec_id === eid);
+            if (!o)
+                return;
+            const tail = (t) => (t ?? "").slice(-OUTPUT_TAIL_CHARS);
+            out.set(s.sandbox_id, {
+                stdout: tail(o.stdout), stderr: tail(o.stderr),
+                truncated: Boolean(o.truncated) || (o.stdout ?? "").length > OUTPUT_TAIL_CHARS || (o.stderr ?? "").length > OUTPUT_TAIL_CHARS,
+            });
+        }
+        catch {
+        }
+    }));
+    return out;
+}
+export function positional(ctx, what, example) {
+    const id = ctx.args[0];
+    if (!id)
+        throw usageError(`${ctx.cmd.name} needs ${what}`, `Example: ${example}.`);
+    return id;
+}
+const runReport = async (ctx) => {
+    const runId = positional(ctx, "a run id", "promigence run report run_01 --json");
+    const which = str(ctx, "--sandboxes");
+    if (which !== undefined && which !== "all" && which !== "failed") {
+        throw usageError(`--sandboxes: '${which}' is not a selection`, "Pass --sandboxes all | failed (omit it for the summary plus what needs attention).");
+    }
+    const limitRaw = str(ctx, "--limit");
+    const view = {
+        sandboxes: (which ?? "default"),
+        limit: limitRaw === undefined ? 50 : Number(limitRaw),
+    };
+    if (!Number.isInteger(view.limit) || view.limit < 0) {
+        throw usageError(`--limit: '${limitRaw}' is not a row count`, "Pass --limit N with N >= 0; --limit 0 prints every sandbox.");
+    }
+    const report = await client(ctx).runs.report(runId);
+    let one = str(ctx, "--sandbox");
+    if (one === undefined && bool(ctx, "--repro")) {
+        const all = report.sandboxes ?? [];
+        if (all.length !== 1) {
+            throw usageError(`--repro is the command for one sandbox, and run ${runId} has ${all.length}`, `Name it: ${sh `promigence run report ${runId} --sandbox SID --repro`} (list them: ${sh `promigence run report ${runId} --sandboxes all`}).`);
+        }
+        one = all[0].sandbox_id;
+    }
+    if (one !== undefined) {
+        const s = (report.sandboxes ?? []).find((x) => x.sandbox_id === one);
+        if (!s) {
+            throw usageError(`${one} is not a sandbox of run ${runId}`, `List them: ${sh `promigence run report ${runId} --sandboxes all`}.`);
+        }
+        const row = s;
+        const repro = reproCommand(report, row);
+        const next = nexts([sh `promigence run replay ${runId} --sandbox ${one}`, "run this sandbox again (env failures only)"]);
+        const lines = [`run ${runId} · sandbox ${one}`, ...sandboxLines(row), ...(bool(ctx, "--repro") ? [`  repro: ${repro}`] : [])];
+        const env = okEnvelope(ctx.cmd.name, {
+            run_id: runId, sandbox_id: one, sandbox: s, repro,
+        }, next);
+        return emit(ctx.mode, env, lines, 0, ctx.pointer);
+    }
+    const next = nexts([sh `promigence run status ${runId}`, "the run's current state"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { run_id: runId, report }, next), reportLines(report, view), 0, ctx.pointer);
+};
+export function supportStoppedLines(sandboxes) {
+    const stopped = sandboxes.filter((s) => s.outcome === "stopped_by_support");
+    if (!stopped.length)
+        return [];
+    return [`  ${stopped.length} stopped by Promigence support; ${sh `promigence sandbox info ${stopped[0].sandbox_id}`} says why`];
+}
+const runStatus = async (ctx) => {
+    const runId = positional(ctx, "a run id", "promigence run status run_01 --wait");
+    const c = client(ctx);
+    let run = await c.runs.get(runId);
+    if (bool(ctx, "--wait")) {
+        const bound = waitBound(ctx);
+        const waited = await c.runs.waitDone(runId, { waitTimeoutMs: bound });
+        if (waited.timedOut)
+            return waitExpired(ctx, runId, bound, waited.run.sandboxes ?? []);
+        run = waited.run;
+    }
+    const states = {};
+    for (const s of run.sandboxes ?? [])
+        states[s.state] = (states[s.state] ?? 0) + 1;
+    const next = nexts([sh `promigence run report ${runId} --json`, "the validity report"]);
+    const tail = Object.keys(states).length ? ` - ${Object.entries(states).map(([k, v]) => `${k} ${v}`).join(" - ")}` : "";
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { run_id: runId, state: run.state, sandbox_states: states, run }, next), [`run ${runId}: ${run.state}${tail}`, ...supportStoppedLines(run.sandboxes ?? []), ...queuedLines(run.sandboxes ?? [])], 0, ctx.pointer);
+};
+const runKill = async (ctx) => {
+    const runId = positional(ctx, "a run id", "promigence run kill run_01");
+    await client(ctx).runs.kill(runId);
+    const next = nexts([sh `promigence run report ${runId} --json`, "what the sandboxes did before the kill"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { run_id: runId, killed: true }, next), [`run ${runId}: killed`], 0, ctx.pointer);
+};
+const runCancel = async (ctx) => {
+    const runId = positional(ctx, "a run id", "promigence run cancel run_01");
+    await client(ctx).runs.cancel(runId);
+    const next = nexts([sh `promigence run kill ${runId}`, "end the sandboxes that already started as well"], [sh `promigence run report ${runId} --json`, "the validity report"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { run_id: runId, cancelled: true, started_keep_running: true }, next), [
+        `run ${runId}: queued starts cancelled`,
+        `  sandboxes that already started keep running (and billing) until they end; ${sh `promigence run kill ${runId}`} ends them too`,
+    ], 0, ctx.pointer);
+};
+const sandboxKill = async (ctx) => {
+    const sid = positional(ctx, "a sandbox id", "promigence sandbox kill sbx_01");
+    const c = client(ctx);
+    const res = (await c.sandboxes.kill(sid) ?? {});
+    const runId = await c.sandboxes.get(sid).then((x) => x.run_id).catch(() => undefined);
+    const next = runId
+        ? nexts([sh `promigence run report ${runId} --json`, "the validity report for the sandbox's run"])
+        : nexts([sh `promigence sandbox info ${sid}`, "how it ended"]);
+    const already = res.already_ended === true;
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+        sandbox_id: sid, killed: !already, ...(already ? { already_ended: true } : {}), ...(res.outcome ? { outcome: res.outcome } : {}),
+    }, next), [already ? `sandbox ${sid}: had already ended${res.outcome ? ` (${res.outcome})` : ""}; nothing to kill` : `sandbox ${sid}: killed`], 0, ctx.pointer);
+};
+const sandboxNetwork = async (ctx) => {
+    const sid = positional(ctx, "a sandbox id", "promigence sandbox network sbx_01");
+    if (bool(ctx, "--cut")) {
+        const cut = await client(ctx).sandboxes.setNetworkNone(sid);
+        const lines = cut.applied
+            ? [`sandbox ${sid}: egress cut`]
+            : [`sandbox ${sid}: egress was already cut`];
+        lines.push("  nothing it runs from here can reach the network");
+        const next = nexts(["promigence sandbox network " + sid, "what it may reach, and what it was refused"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, cut, next), lines, 0, ctx.pointer);
+    }
+    const v = await client(ctx).sandboxes.network(sid);
+    const mode = typeof v.network === "string" ? v.network : `only ${v.network.allow.join(", ")}`;
+    const lines = [`sandbox ${sid}: ${mode}`];
+    const refused = v.refused_hosts ?? [];
+    for (const r of refused) {
+        lines.push(`  refused  ${r.host}${r.count ? ` (${r.count} attempts)` : ""}`);
+    }
+    const toAddresses = Number(v["refused_connections"] ?? 0) || 0;
+    if (toAddresses > 0) {
+        lines.push(`  refused  ${toAddresses} connection${toAddresses === 1 ? "" : "s"} to an address with no name (counted; addresses are not recorded)`);
+    }
+    if (refused.length) {
+        lines.push(`add one with --allow HOST when you start the sandbox`);
+    }
+    else if (typeof v.network !== "string" && toAddresses === 0) {
+        lines.push("  nothing has been refused");
+    }
+    for (const b of v.via_secret ?? []) {
+        lines.push(`  via secret ${b.secret}: ${b.hosts.join(", ") || "(no hosts)"}`);
+    }
+    const next = nexts([sh `promigence sandbox info ${sid}`, "the sandbox, its run and the commands it ran"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, v, next), lines, 0, ctx.pointer);
+};
+const usd = (n) => `$${n.toFixed(n < 0.01 && n > 0 ? 4 : 2)}`;
+const rate = (n) => `$${Number(n.toFixed(9))}`;
+function bytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const u = ["KiB", "MiB", "GiB", "TiB"];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < u.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(v < 10 ? 1 : 0)} ${u[i]}`;
+}
+const runQuote = async (ctx) => {
+    const c = client(ctx);
+    const snapshot = str(ctx, "--snapshot") === undefined ? DEFAULT_SNAPSHOT : await snapshotArg(ctx, c);
+    const count = parseCount(required(ctx, "--count", "Pass --count N (number of sandboxes to fork)."), "--count");
+    const timeout = str(ctx, "--timeout");
+    const tier = str(ctx, "--tier");
+    const cap = str(ctx, "--cap");
+    const q = await c.runs.quote({
+        snapshot,
+        count,
+        ...(timeout ? { timeoutMs: parseDuration(timeout, "--timeout") } : {}),
+        ...(tier ? { tier } : {}),
+        ...(cap ? { spendCap: parseUsd(cap, "--cap") } : {}),
+    });
+    const next = nexts([`${sh `promigence run --snapshot ${snapshot} --count ${count}`}${timeout ? sh ` --timeout ${timeout}` : ""}${tier ? sh ` --tier ${tier}` : ""}${sh ` --cap ${q.max_cost || 1}`} -- CMD`, "run it, capped at the quote"], [`promigence me`, "what you have spent so far"]);
+    const lines = [
+        `quote ${usd(q.max_cost)} — ${q.count} x ${q.seconds_per_sandbox}s x ${rate(q.per_second_usd)}/s (tier ${q.tier}: ${q.vcpus} vCPU, ${q.mem_gib} GiB; ${rate(q.vcpu_second_usd)}/vCPU-s + ${rate(q.gib_second_usd)}/GiB-s)`,
+        ...q.breakdown
+            .filter((b) => q.breakdown.length > 1)
+            .map((b) => `  ${b.sandbox_count} x ${b.seconds_per_sandbox}s x ${rate(b.per_second_usd)}/s = ${usd(b.sandbox_count * b.seconds_per_sandbox * b.per_second_usd)}`),
+        ...q.warnings.map((w) => `  warning: ${w}`),
+    ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { quote: q, max_cost: q.max_cost, per_second_usd: q.per_second_usd, seconds_per_sandbox: q.seconds_per_sandbox, breakdown: q.breakdown, warnings: q.warnings }, next), lines, 0, ctx.pointer);
+};
+const runReplay = async (ctx) => {
+    const runId = positional(ctx, "a run id", "promigence run replay run_01 --sandbox sbx_01");
+    const only = list(ctx, "--sandbox");
+    const env = {};
+    for (const kv of list(ctx, "--env")) {
+        const eq = kv.indexOf("=");
+        if (eq <= 0)
+            throw usageError(`--env '${kv}' is not K=V`, "Pass --env NAME=value (repeatable).");
+        env[kv.slice(0, eq)] = kv.slice(eq + 1);
+    }
+    const r = await client(ctx).runs.replay(runId, only, Object.keys(env).length ? { env } : {});
+    const next = r.replayed === 0
+        ? nexts([sh `promigence run report ${runId} --json`, "the report: only env failures (ours) are replayable"])
+        : nexts([sh `promigence run status ${runId} --wait`, "wait for the replayed sandboxes"], [sh `promigence run report ${runId} --json`, "fork.replay carries them; the headline numbers do not"]);
+    const lines = r.replayed === 0
+        ? [`run ${runId}: nothing to replay${r.detail ? ` (${r.detail})` : ""}`]
+        : [
+            `run ${runId}: replayed ${r.replayed} env failure${r.replayed === 1 ? "" : "s"}`,
+            ...r.sandboxes.map((s) => `  ${s.sandbox_id} replays ${s.replay_of}`),
+        ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+        run_id: runId, replayed: r.replayed, sandboxes: r.sandboxes,
+        ...(r.replayed === 0 ? { reason: r.detail ?? "no env_failed or preempted sandboxes to replay" } : {}),
+    }, next), lines, 0, ctx.pointer);
+};
+const runOpen = async (ctx) => {
+    const runId = positional(ctx, "a run id", "promigence run open run_01");
+    const sandboxId = str(ctx, "--sandbox");
+    const cap = str(ctx, "--cap");
+    const timeout = str(ctx, "--timeout");
+    const r = await client(ctx).runs.open(runId, {
+        ...(sandboxId ? { sandboxId } : {}),
+        ...(cap ? { spendCap: parseUsd(cap, "--cap") } : {}),
+        ...(timeout ? { timeoutMs: parseDuration(timeout, "--timeout") } : {}),
+    });
+    const next = nexts([sh `promigence exec --sandbox ${r.sandbox_id} -- ls -la`, "look at what it left behind"], [sh `promigence sandbox kill ${r.sandbox_id}`, "stop it — it is billing from now"]);
+    const lines = [
+        `sandbox ${r.sandbox_id}  ready${r.ready_ms === undefined ? "" : ` ${Math.round(r.ready_ms)} ms`}`,
+        `  a new sandbox, forked from ${r.opened_from} as it was when it failed`,
+        `  failed at ${r.failed_at}, ${r.outcome}${r.code ? ` (${r.code})` : ""}`,
+        `  preserved until ${r.expires_at}`,
+    ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, r, next), lines, 0, ctx.pointer);
+};
+const runCaptures = async (ctx) => {
+    const runId = positional(ctx, "a run id", "promigence run captures run_01");
+    const doomed = str(ctx, "--delete");
+    if (doomed !== undefined) {
+        const d = await client(ctx).captures.delete(doomed);
+        const line = d.deleted
+            ? `deleted ${d.snapshot_id}: ${bytes(d.bytes)} freed at ${d.deleted_at}`
+            : `${d.snapshot_id} was already gone`;
+        const after = nexts([sh `promigence run captures ${runId}`, "what is still preserved"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { run_id: runId, ...d }, after), [line], 0, ctx.pointer);
+    }
+    const r = await client(ctx).runs.captures(runId);
+    const openable = r.captures.filter((x) => x.available !== false);
+    const next = openable.length === 0
+        ? nexts([sh `promigence run report ${runId}`, "the run's report"])
+        : nexts([
+            openable.length === 1 ? sh `promigence run open ${runId}` : sh `promigence run open ${runId} --sandbox ${openable[0].sandbox_id}`,
+            "reopen one as a live sandbox",
+        ]);
+    const lines = r.captures.length === 0
+        ? [`run ${runId}: nothing preserved`]
+        : [
+            `run ${runId}: ${r.captures.length} preserved failure${r.captures.length === 1 ? "" : "s"}`,
+            ...r.captures.map((c) => `  ${c.sandbox_id}  ${c.outcome}${c.code ? ` (${c.code})` : ""}  ${bytes(c.bytes)}  ${c.available === false ? "no longer available (cannot be opened)" : `until ${c.expires_at} at the latest`}`),
+        ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { run_id: runId, captures: r.captures }, next), lines, 0, ctx.pointer);
+};
+const snapshotVerify = async (ctx) => {
+    const id = positional(ctx, "a snapshot id or alias", "promigence snapshot verify snap_01");
+    const c = client(ctx);
+    const started = await c.snapshots.verify(id);
+    await write(process.stderr, forTerminal(process.stderr, `verify ${started.snapshot_id}: up to ${usd(started.price)} (${started.seconds}s of tier ${started.tier} at ${rate(started.per_second_usd)}/s) — running \`${started.verify}\` in a fresh fork`) + "\n");
+    const bound = waitBound(ctx);
+    const waited = await c.runs.waitDone(started.run_id, { waitTimeoutMs: bound });
+    if (waited.timedOut)
+        return waitExpired(ctx, started.run_id, bound, waited.run.sandboxes ?? []);
+    const report = await c.runs.report(started.run_id);
+    const t = report.totals;
+    const verified = (t?.completed ?? 0) > 0;
+    const exit = verified ? 0 : (t?.env_failed ?? 0) > 0 ? 3 : 6;
+    const next = nexts([sh `promigence run report ${started.run_id} --json`, "the fork's own validity report"], [sh `promigence snapshot inspect ${started.snapshot_id}`, "the recorded verification"]);
+    const lines = [
+        `snapshot ${started.snapshot_id}: ${verified ? "verified" : exit === 3 ? "not run — the environment failed (ours; the report says what was billed)" : "DID NOT VERIFY"}`,
+        `  \`${started.verify}\` in ${started.workspace} · charged ${usd(report.cost?.charged ?? 0)}`,
+        ...reportSummaryLines(report).slice(1),
+    ];
+    const env = okEnvelope(ctx.cmd.name, {
+        snapshot_id: started.snapshot_id, run_id: started.run_id, verified,
+        verify: started.verify, price: started.price, report,
+    }, next);
+    env.ok = exit === 0;
+    return emit(ctx.mode, env, lines, exit, ctx.pointer);
+};
+function localTar(args, what) {
+    const r = spawnSync("tar", args, { encoding: "utf8", env: { ...process.env, COPYFILE_DISABLE: "1" } });
+    if (r.error && r.error.code === "ENOENT") {
+        throw usageError("`tar` is not on PATH, and a directory transfer needs one locally", "Install tar (macOS and every Linux ship one), or move the files one at a time without --recursive.");
+    }
+    if (r.status !== 0) {
+        throw usageError(`${what} failed: ${(r.stderr ?? "").trim() || `tar exited ${r.status}`}`, "Check the path and that you can read/write it.");
+    }
+}
+function filesArgs(ctx) {
+    const sid = required(ctx, "--sandbox", "Pass --sandbox sbx_<id> (from `promigence sandbox list`).");
+    const [src, dst] = [ctx.args[0], ctx.args[1]];
+    if (!src || !dst) {
+        throw usageError(`${ctx.cmd.name} needs SRC and DST`, `Example: promigence ${ctx.cmd.name} --sandbox ${shellArg(sid)} ${ctx.cmd.name === "files put" ? "./fixture.json /tmp/fixture.json" : "/tmp/trace.json ./trace.json"}.`);
+    }
+    return { sid, src, dst };
+}
+const filesPut = async (ctx) => {
+    if (bool(ctx, "--recursive"))
+        return filesPutDir(ctx);
+    const { sid, src, dst } = filesArgs(ctx);
+    if (!dst.startsWith("/"))
+        throw usageError(`DST ${dst} must be absolute inside the sandbox`, "Example: /tmp/fixture.json.");
+    const r = await withLocalFile(src, (source) => client(ctx).sandboxes.files.putFrom(sid, dst, source, source.mode === undefined ? {} : { mode: source.mode }));
+    const next = nexts([sh `promigence exec --sandbox ${sid} -- ls -l ${dst}`, "see it in the sandbox"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, src, dst, bytes: r.bytes, chunks: r.chunks, mode: r.mode }, next), [`${src} -> ${sid}:${dst} (${bytes(r.bytes)}${r.chunks > 1 ? `, ${r.chunks} chunks` : ""})`], 0, ctx.pointer);
+};
+async function withLocalFile(path, fn) {
+    let fd;
+    let size;
+    let mode;
+    try {
+        fd = openSync(path, "r");
+        const st = fstatSync(fd);
+        if (st.isDirectory()) {
+            closeSync(fd);
+            throw Object.assign(new Error("it is a directory"), { code: "EISDIR" });
+        }
+        size = st.isFile() ? st.size : -1;
+        mode = st.isFile() && process.platform !== "win32" ? st.mode & 0o777 : undefined;
+    }
+    catch (e) {
+        const code = e.code;
+        throw usageError(`cannot read ${path}: ${code === "EISDIR" ? "it is a directory" : e.message}`, code === "EISDIR"
+            ? "Pass --recursive to copy a directory."
+            : "Give a readable local path as SRC; DST is the absolute path inside the sandbox.");
+    }
+    try {
+        if (size < 0) {
+            const all = readFileSync(fd);
+            return await fn({ size: all.length, read: (o, l) => all.subarray(o, o + l) });
+        }
+        const buf = Buffer.alloc(FILE_PUT_CHUNK_BYTES);
+        return await fn({
+            size,
+            mode,
+            read: (offset, len) => {
+                const want = Math.min(len, buf.length);
+                let got = 0;
+                while (got < want) {
+                    const n = readSync(fd, buf, got, want - got, offset + got);
+                    if (n === 0)
+                        break;
+                    got += n;
+                }
+                return buf.subarray(0, got);
+            },
+        });
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function filesPutTarArgs(out, parent, base, noMetadata = localTarNoMetadataArgs()) {
+    return ["-c", "-f", out, ...noMetadata, "-C", parent, base];
+}
+const filesPutDir = async (ctx) => {
+    const { sid, src, dst } = filesArgs(ctx);
+    if (!dst.startsWith("/"))
+        throw usageError(`DST ${dst} must be absolute inside the sandbox`, "Example: /tmp/data.");
+    if (!existsSync(src))
+        throw usageError(`cannot read ${src}`, "SRC is a local directory when --recursive is given.");
+    const tmp = join(mkdtempSync(join(tmpdir(), "promigence-put-")), "dir.tar");
+    const parent = dirname(resolve(src));
+    const base = basename(resolve(src));
+    localTar(filesPutTarArgs(tmp, parent, base), `tarring ${src}`);
+    const bytesIn = statSync(tmp).size;
+    const c = client(ctx);
+    const scratch = `/tmp/.promigence-upload/cli-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}.tar`;
+    await withLocalFile(tmp, (source) => c.sandboxes.files.putFrom(sid, scratch, source));
+    let entries;
+    try {
+        ({ entries } = await c.sandboxes.files.extract(sid, scratch, dst, { strip: 1 }));
+    }
+    finally {
+        await c.sandboxes.files.delete(sid, scratch).catch(() => { });
+        rmSync(dirname(tmp), { recursive: true, force: true });
+    }
+    const next = nexts([sh `promigence files ls ${dst} --sandbox ${sid}`, "what landed"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, src, dst, bytes: bytesIn, entries, recursive: true }, next), [`${src}/ -> ${sid}:${dst} (${bytes(bytesIn)}${entries === null ? "" : `, ${entries} entries`})`], 0, ctx.pointer);
+};
+const filesGet = async (ctx) => {
+    if (bool(ctx, "--recursive"))
+        return filesGetDir(ctx);
+    if (list(ctx, "--exclude").length) {
+        throw usageError("--exclude needs --recursive", "It leaves paths out of a directory; drop it for one file, or add --recursive.");
+    }
+    const { sid, src, dst } = filesArgs(ctx);
+    if (!src.startsWith("/"))
+        throw usageError(`SRC ${src} must be absolute inside the sandbox`, "Example: /tmp/trace.json.");
+    const c = client(ctx);
+    const stat = await c.sandboxes.files.stat(sid, src);
+    if (stat.stat?.is_dir === true) {
+        throw usageError(`${src} is a directory`, `Pass --recursive: ${sh `promigence files get ${src} ${dst} --sandbox ${sid} --recursive`}.`);
+    }
+    let sink;
+    let wrote = dst;
+    if (dst === "-") {
+        sink = {
+            write: (chunk) => new Promise((resolve) => {
+                if (process.stdout.write(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.length)))
+                    resolve();
+                else
+                    process.stdout.once("drain", () => resolve());
+            }),
+            done: async () => { },
+            abort: () => { },
+        };
+    }
+    else {
+        const d = openDownload(dst, src.split("/").filter(Boolean).pop());
+        wrote = d.path;
+        sink = d;
+    }
+    let got;
+    try {
+        got = await c.sandboxes.files.download(sid, src, (chunk) => sink.write(chunk));
+        await sink.done();
+    }
+    catch (e) {
+        sink.abort();
+        if (stat.stat?.is_symlink !== true)
+            throw e;
+        throw usageError(`${src} is a symbolic link, which files get cannot copy yet`, `Copy the file it points to: ${sh `promigence exec --sandbox ${sid} -- readlink -f ${src}`} names it.`);
+    }
+    if (dst === "-")
+        return exitWith(0);
+    const next = nexts([sh `promigence files ls ${dirname(src)} --sandbox ${sid}`, "what else is beside it"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { sandbox_id: sid, src, dst: wrote, bytes: got.bytes, stat: stat.stat }, next), [`${sid}:${src} -> ${wrote} (${bytes(got.bytes)})`], 0, ctx.pointer);
+};
+function openDownload(dstIn, srcName) {
+    let dst = dstIn;
+    let st;
+    try {
+        st = lstatSync(dst);
+    }
+    catch {
+    }
+    if (st?.isSymbolicLink()) {
+        throw usageError(`${dst} is a symbolic link; files get does not write through links`, "Remove the link, or name another local path as DST.");
+    }
+    if (st?.isDirectory()) {
+        if (srcName === undefined)
+            throw usageError(`${dst} is a directory`, "Name a file path as DST, e.g. ./out/trace.json.");
+        dst = join(dst, srcName);
+        let inner;
+        try {
+            inner = lstatSync(dst);
+        }
+        catch { }
+        if (inner?.isSymbolicLink()) {
+            throw usageError(`${dst} is a symbolic link; files get does not write through links`, "Remove the link, or name another local path as DST.");
+        }
+        if (inner?.isDirectory())
+            throw usageError(`${dst} is a directory`, "Name a file path as DST.");
+    }
+    const local = (e, what) => {
+        throw usageError(`cannot write ${what}: ${e.message}`, "Check that the directory exists and that you can write to it, or name another DST.");
+    };
+    try {
+        mkdirSync(dirname(dst), { recursive: true });
+    }
+    catch (e) {
+        local(e, dirname(dst));
+    }
+    const partial = join(dirname(dst), `.${basename(dst)}.promigence-partial-${randomBytes(4).toString("hex")}`);
+    const NOFOLLOW = fsConstants["O_NOFOLLOW"] ?? 0;
+    let fd = -1;
+    try {
+        fd = openSync(partial, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | NOFOLLOW, 0o644);
+    }
+    catch (e) {
+        local(e, dst);
+    }
+    const close = () => { if (fd >= 0) {
+        try {
+            closeSync(fd);
+        }
+        catch { }
+        fd = -1;
+    } };
+    return {
+        path: dst,
+        write: async (chunk) => {
+            let at = 0;
+            while (at < chunk.length)
+                at += writeSync(fd, chunk, at, chunk.length - at);
+        },
+        done: async () => {
+            close();
+            try {
+                renameSync(partial, dst);
+            }
+            catch (e) {
+                rmSync(partial, { force: true });
+                local(e, dst);
+            }
+        },
+        abort: () => {
+            close();
+            rmSync(partial, { force: true });
+        },
+    };
+}
+const filesGetDir = async (ctx) => {
+    const { sid, src, dst } = filesArgs(ctx);
+    if (!src.startsWith("/"))
+        throw usageError(`SRC ${src} must be absolute inside the sandbox`, "Example: /tmp/data.");
+    if (dst === "-")
+        throw usageError("files get --recursive writes a directory, not a stream", "Name a local directory as DST, or drop --recursive for one file.");
+    const c = client(ctx);
+    const exclude = list(ctx, "--exclude");
+    const made = await c.sandboxes.files.archive(sid, src, { ...(exclude.length ? { exclude } : {}) });
+    const tmp = join(mkdtempSync(join(tmpdir(), "promigence-get-")), "dir.tar");
+    let unpacked;
+    try {
+        const tarOut = openDownload(tmp);
+        try {
+            await c.sandboxes.files.download(sid, made.archive_path, (chunk) => tarOut.write(chunk));
+            await tarOut.done();
+        }
+        catch (e) {
+            tarOut.abort();
+            throw e;
+        }
+        try {
+            unpacked = untarSafe(tmp, dst, { strip: 1, keepLinks: bool(ctx, "--keep-links") });
+        }
+        catch (e) {
+            if (!(e instanceof UnsafeArchiveError))
+                throw e;
+            throw usageError(`files get --recursive refused ${src}: ${e.message}; nothing was written`, `Leave them out with --exclude NAME, or remove them in the sandbox. --keep-links recreates links that point outside ${dst} as they are (hard links, devices and fifos are always refused).`);
+        }
+    }
+    finally {
+        await c.sandboxes.files.delete(sid, made.archive_path).catch(() => { });
+        rmSync(dirname(tmp), { recursive: true, force: true });
+    }
+    const next = nexts([sh `promigence files ls ${src} --sandbox ${sid}`, "what is still in the sandbox"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+        sandbox_id: sid, src, dst, bytes: made.size, recursive: true,
+        files: unpacked.files, dirs: unpacked.dirs, links: unpacked.links,
+    }, next), [`${sid}:${src}/ -> ${dst} (${bytes(made.size)})`], 0, ctx.pointer);
+};
+export const HANDLERS = {
+    "auth login": authLogin,
+    "snapshot create": snapshotCreate,
+    "snapshot status": snapshotStatus,
+    "snapshot list": snapshotList,
+    "snapshot inspect": snapshotInspect,
+    fork,
+    exec,
+    run: runComposite,
+    "run report": runReport,
+    "run status": runStatus,
+    "run kill": runKill,
+    "run cancel": runCancel,
+    "run quote": runQuote,
+    "run replay": runReplay,
+    "run open": runOpen,
+    "run captures": runCaptures,
+    "snapshot verify": snapshotVerify,
+    "files put": filesPut,
+    "files get": filesGet,
+    "sandbox kill": sandboxKill,
+    "sandbox network": sandboxNetwork,
+    "secrets set": secretsSet,
+};