@promigence/sdk 0.1.0-beta.12

package/dist/cjs/client.d.ts

@@ -0,0 +1,3015 @@
+/** `PromigenceClient` — the native client for the Promigence API. */
+import { inspect, type InspectOptions } from "node:util";
+import { PromigenceError, type CommandResult, type NetworkMode, type OptimizeFor, type Tier } from "./core.js";
+import { type Bundle } from "./bundle.js";
+import { type PtyExit, type PtySession } from "./pty.js";
+import { type SshTunnel } from "./ssh.js";
+import type * as M from "./models.gen.js";
+import { type ConnectRequest, type ConnectTicket, type GithubConnect, type GithubDisconnected, type GithubRepos, type GithubStatus, type GithubUntracked } from "./github.js";
+import { type GitlabConnect, type GitlabDisconnected, type GitlabRepos, type GitlabStatus, type GitlabUntracked } from "./gitlab.js";
+export type FetchLike = typeof globalThis.fetch;
+/**
+ * Default deadline for one `files get|put`.
+ *
+ * A transfer is bounded by the artefact's size, not by the 30 s that is generous for a control
+ * message: a 2 GB trace over a shaped link is minutes, and timing it out at 30 s would make the
+ * route useless for exactly the payload it exists to carry.
+ */
+export declare const FILE_TIMEOUT_MS: number;
+export type RunState = M.RunState;
+/**
+ * `queued` and `awaiting_capacity` are both waiting, and the difference is the whole point.
+ *
+ * `queued` = waiting for capacity that **exists**; typically milliseconds to a few seconds.
+ * `awaiting_capacity` = there is no free capacity and more is being **provisioned for you**; the
+ * run's `capacity` block carries an ETA. A waiting sandbox may also say why it waits: see
+ * {@link QueuedInfo}.
+ *
+ */
+export type SandboxState = "queued" | "awaiting_capacity" | "ready" | "running" | "paused" | "ended";
+/** A sandbox is still waiting for capacity, for either reason. */
+export declare const isWaiting: (s: SandboxState | string) => boolean;
+/**
+ * Why a waiting sandbox is waiting.
+ *
+ * `capacity_arriving` — more capacity is being added for the run; `eta_s` says when it is
+ * expected, and `one_time` whether it covers everything waiting. `snapshot_held` — the sandbox can
+ * only start where its snapshot is held, and there is no room there yet; it starts when a sandbox
+ * there ends. `capacity_limit` — the service is at its capacity limit; it starts when room frees.
+ * `preparing` — the snapshot is being made ready to start; its first start takes a few seconds.
+ */
+export type QueuedReason = M.QueuedReason;
+/**
+ * Why a waiting sandbox is waiting and how long that should take — on every sandbox record a run
+ * or sandbox route returns, and on the validity report's rows. All four fields are present
+ * together, or none: absent while the sandbox is not waiting, and while nothing more is known
+ * than that it is queued.
+ */
+export interface QueuedInfo {
+    queued_reason?: QueuedReason;
+    /**
+     * Seconds until the capacity it waits for is expected to be ready, with `capacity_arriving`.
+     * `null` with the other reasons, and once the sandbox has waited past the estimate it was first
+     * given (`queued_message` then says it is taking longer than expected).
+     */
+    eta_s?: number | null;
+    /**
+     * A one-time wait: the capacity being added covers what is waiting, so once it is ready the
+     * rest of the run starts at once. An agent can decide to wait on this.
+     */
+    one_time?: boolean;
+    /** The same, in words, ready to show a person. */
+    queued_message?: string;
+}
+/**
+ * Capacity while this run waits. Attached to `GET /runs/:id` and `GET /runs/:id/sandboxes`, so
+ * the request a client is already long-polling carries the answer.
+ */
+export interface Capacity {
+    /** `ok` there is free capacity · `arriving` more is on its way for you · `blocked` no more is available right now. */
+    state: "ok" | "arriving" | "blocked";
+    awaiting_capacity: number;
+    /** Soonest a sandbox can start, in seconds. `null` when nothing is on its way. */
+    eta_s: number | null;
+    /** Why no more capacity is available right now. Not an ETA. */
+    blocked?: {
+        code: string;
+        reason: string;
+        at: string;
+    } | null;
+    /** Why this run's waiting sandboxes are waiting: the `queued_reason` they carry. */
+    queued_reason?: QueuedReason;
+    /** The same, in words, with the time it should take: the `queued_message` they carry. */
+    queued_message?: string;
+}
+export type Outcome = M.Outcome;
+/** `GET /me/outcomes`: what the organization got this month, measured. */
+export type Outcomes = M.Outcomes;
+export interface Percentiles {
+    p50: number;
+    p95: number;
+    p99?: number;
+}
+/** Reply to `sandboxes.pause`. `bytes.allocated` is the disk space the paused sandbox occupies. */
+export interface PauseResult {
+    ok: boolean;
+    sandbox_id: string;
+    state: "paused";
+    /** An opaque name for this pause. Resume by the sandbox id. */
+    paused_id: string;
+    /** Milliseconds the pause took, from the request to the answer. */
+    took_ms?: number;
+    bytes?: {
+        allocated: number;
+    };
+    /** False if the pause happened but could not be written down; worth retrying. */
+    recorded?: boolean;
+    /** True when the paused sandbox is stored so that it survives a hardware failure. */
+    durable?: boolean;
+    /** The pause was a no-op: it was already parked. */
+    already_paused?: boolean;
+    /**
+     * Background execs (started with `background: true`) this pause ended. Their exec ids answer
+     * not found after resume; a process a foreground command detached is kept.
+     */
+    background_execs_killed?: number;
+    /**
+     * `code: sentence` lines, present only when there is something to say. Today:
+     * `secrets_in_saved_state` — the sandbox was given the value of a secret, so its saved state
+     * can contain that value while it is paused.
+     */
+    warnings?: string[];
+}
+/**
+ * Reply to `sandboxes.snapshot` — a snapshot taken from a sandbox that is still running.
+ *
+ * `still_running` is sent explicitly rather than implied by the absence of an error, because it
+ * is the whole difference between this call and `pause`.
+ */
+export interface SandboxSnapshotResult {
+    ok: boolean;
+    /** An ordinary snapshot id. Fork it like any other. */
+    snapshot_id: string;
+    sandbox_id: string;
+    alias?: string | null;
+    tier: string;
+    /** What the image occupies on disk. */
+    bytes: {
+        allocated: number;
+    };
+    /** Milliseconds the snapshot took, from the request to the answer. */
+    took_ms?: number;
+    /** Background processes ended to take the snapshot. */
+    background_execs_killed: number;
+    still_running: boolean;
+    /**
+     * Present only when there is something to say. Today: `secrets_in_saved_state` on a snapshot
+     * taken with `force` from a sandbox that was given a secret — the snapshot, and every sandbox
+     * started from it, can contain that value.
+     */
+    warnings?: string[];
+}
+/** Reply to `sandboxes.resume`. `took_ms` is the time it took. */
+export interface ResumeResult {
+    ok: boolean;
+    sandbox_id: string;
+    state: "ready";
+    /** The `paused_id` of the pause this restored. */
+    paused_id?: string;
+    /** Milliseconds the resume took, from the request to the answer. */
+    took_ms?: number;
+    recorded?: boolean;
+}
+export interface SandboxRef extends QueuedInfo {
+    sandbox_id: string;
+    state: SandboxState;
+    /**
+     * `runs.get` only: the verdict on the sandbox's terminal command when the sandbox outlived it.
+     * `completed` | `task_failed` with `killOnExit: false`: the command is over, the sandbox is live
+     * and billed until it is killed or expires. `cap_killed`: the run's spend cap (or the trial's
+     * credits) stopped the command and the sandbox was paused with its files and state; it goes on
+     * once the cap is raised (`sandboxes.resume(id, { spendCap })`) or credits are added. Absent
+     * otherwise.
+     */
+    command_outcome?: "completed" | "task_failed" | "cap_killed";
+    [extra: string]: unknown;
+}
+/** How a grader's result is read. */
+export type ScoreMode = M.ScoreMode;
+/**
+ * Score the agent's work after the episode, in a clean copy of the snapshot with the agent's
+ * changes applied. `holdout_cmd` is your own second test set; the report carries the gap
+ * between the two pass rates. It runs in a copy of the same snapshot, so any file it reads from
+ * the snapshot was readable by the agent too — keep held-out tests out of the snapshot.
+ *
+ * The answer is a verdict and a score. What the grader prints is kept only when the run asks for
+ * it (`gradeOutput`): then its last 16 KiB come back in the report (`ReportSandbox.grade`).
+ */
+export interface GradeSpec {
+    cmd: string;
+    holdout_cmd?: string;
+    timeout_ms?: number;
+    score?: ScoreMode;
+}
+/**
+ * What a sandbox's grader printed, in the run report when the run asked for it (`gradeOutput`):
+ * the end of its output, stdout and stderr together, at most its last 16 KiB. Never a held-out
+ * grader's.
+ */
+export interface GradeOutput {
+    output: string;
+    /** The grader printed more than `output` holds; the beginning was left out. */
+    output_truncated: boolean;
+}
+/** Per run: the two pass rates and the gap between them, in points. */
+export interface GradeStats {
+    graded: number;
+    passed: number;
+    pass_pct: number;
+    holdout_graded?: number;
+    holdout_passed?: number;
+    holdout_pass_pct?: number;
+    /** `pass_pct − holdout_pass_pct`. Absent without a held-out set. */
+    gap_pct?: number;
+    grader_failed?: number;
+}
+export interface RunStartResponse {
+    run_id: string;
+    sandboxes: SandboxRef[];
+    /** Set by the server when an `Idempotency-Key` replayed an existing run. */
+    idempotent_replay?: boolean;
+    /** With `idempotent_replay`: how many seconds ago that run's answer was first given. */
+    idempotent_replay_age_s?: number;
+    [extra: string]: unknown;
+}
+export interface RunRecord {
+    run_id: string;
+    state: RunState;
+    snapshot_id?: string;
+    sandboxes?: SandboxRef[];
+    [extra: string]: unknown;
+}
+export interface ForkStats {
+    n: number;
+    queued_ms?: Percentiles;
+    ready_ms?: Percentiles;
+    e2e_ms?: Percentiles;
+    verify_each_ms?: Percentiles;
+    warm_retries: number;
+    first_attempt_success_pct: number;
+    final_success_pct: number;
+    percentile_method?: string;
+    replay?: {
+        n: number;
+        success_pct: number;
+    };
+}
+export interface Totals {
+    env_verified: number;
+    completed: number;
+    task_failed: number;
+    env_failed: number;
+    /** The grade could not be computed. Never counted as a task failure. */
+    grader_failed?: number;
+    snapshot_failed: number;
+    aborted_by_client: number;
+    /**
+     * Sandboxes Promigence support stopped (outcome `stopped_by_support`), each with its reason in its
+     * failure's message. Never counted as your own kill (`aborted_by_client`). Absent from an older API.
+     */
+    stopped_by_support?: number;
+    expired: number;
+    cap_killed: number;
+    not_started: number;
+    evidence_missing: number;
+}
+export interface ExecRecord {
+    exec_id: string;
+    argv: string[];
+    exit_code?: number;
+    signal?: number;
+    wall_ms?: number;
+    cpu_ms?: number;
+    stdout_ref?: string;
+    stderr_ref?: string;
+    truncated?: boolean;
+    [extra: string]: unknown;
+}
+export interface ReportSandbox extends QueuedInfo {
+    sandbox_id: string;
+    state: SandboxState;
+    attempt?: number;
+    queued_ms?: number;
+    ready_ms?: number;
+    e2e_ms?: number;
+    env_verified?: boolean;
+    execs?: ExecRecord[];
+    outcome: Outcome;
+    /** The grader ran in a clean environment and produced a verdict. */
+    graded?: boolean;
+    /** The visible test set's verdict. This one decides the sandbox's outcome. */
+    passed?: boolean;
+    score?: number;
+    /** The held-out set, run in its own clean environment. Reported, never attributed. */
+    holdout_passed?: boolean;
+    holdout_score?: number;
+    /** What the grader printed, when the run asked for it (`gradeOutput`). Absent otherwise. */
+    grade?: GradeOutput;
+    failure?: {
+        category: "env" | "task" | "snapshot" | "grader" | "cap";
+        code: string;
+        evidence?: Record<string, unknown>;
+    };
+    warnings?: string[];
+    /** Seconds from hand-over to end minus paused time, rounded up — whatever the outcome. */
+    used_seconds?: number;
+    /** Seconds this sandbox bills: `used_seconds` capped at `committed_seconds`, 0 for env failures. */
+    billable_seconds?: number;
+    /** Seconds the run's cap reserved for it (raised only by `PATCH /sandboxes/:id`). */
+    committed_seconds?: number;
+    /** USD: `billable_seconds × per_second_usd`. */
+    cost?: number;
+    [extra: string]: unknown;
+}
+export interface RunReport {
+    schema: string;
+    run_id: string;
+    state: RunState;
+    snapshot_id?: string;
+    alias?: string;
+    labels?: Record<string, string>;
+    requested?: {
+        count: number;
+        timeout_ms: number;
+        verify_each: boolean;
+        network: NetworkMode;
+        allow_partial: boolean;
+        secrets?: string[];
+        grade?: GradeSpec;
+        grade_output?: boolean;
+    };
+    quote?: Quote;
+    spend_cap?: number;
+    started_at?: string;
+    finished_at?: string;
+    fork: ForkStats;
+    totals: Totals;
+    cost?: {
+        quoted: number;
+        charged: number;
+        unbilled: number;
+        cap_killed: boolean;
+        billable_seconds?: number;
+        per_second_usd?: number;
+    };
+    /** The two pass rates and the gap between them. Absent when the run was not graded. */
+    grade?: GradeStats;
+    sandboxes: ReportSandbox[];
+    [extra: string]: unknown;
+}
+/** A build of a snapshot (`POST /snapshots`, `GET /snapshots/builds/:id`). */
+/** `built`: finished and stored with no verification command to run; done, like `verified`. */
+export type BuildState = "queued" | "running" | "verified" | "built" | "rejected" | "failed";
+export interface SecretRecord {
+    name: string;
+    /** Length of the stored value, so a caller can sanity-check without reading it. */
+    bytes: number;
+    /** On `secrets.set` only: `false` when an existing secret of that name was overwritten. */
+    created?: boolean;
+    /** On `secrets.list` only. */
+    created_at?: string;
+    updated_at?: string;
+    /**
+     * The hosts the secret is bound to. Absent when it is not bound: a sandbox that names it is
+     * then given the value. When present, requests the sandbox sends to the host's address in
+     * `urls` are authenticated with the secret, a request made straight to `https://<host>/` is not,
+     * and the value stays out of the sandbox unless a run asks for it (`raw`).
+     */
+    hosts?: string[];
+    /**
+     * For each of `hosts`, in order, the address a sandbox sends its requests to, with the
+     * request's path added. On `set` and `list` of a bound secret.
+     */
+    urls?: string[];
+    /**
+     * The variables a sandbox that names this secret is also given, each set to its host's
+     * address in `urls`: `OPENAI_BASE_URL` for `api.openai.com`, `ANTHROPIC_BASE_URL` for
+     * `api.anthropic.com`. Absent when there is none. A variable the caller sets itself wins.
+     */
+    env?: Record<string, string>;
+    /** The request headers the secret authenticates: on `secrets.list`, when `hosts` is present. */
+    headers?: string[];
+    /** What the variable in a sandbox that names it holds instead of the value (on `set` of a bound secret). */
+    placeholder?: string;
+    /** `refused` when the value itself can never be given to a sandbox (present when `hosts` is). */
+    raw?: "allowed" | "refused";
+    /** Whether the value is kept out of the bound hosts' answers (present when `hosts` is). */
+    scan_responses?: boolean;
+}
+/**
+ * `secrets.set` options: bind the secret to hosts. Requests a sandbox sends to the host's address
+ * the answer gives in `urls` (and to `$OPENAI_BASE_URL` / `$ANTHROPIC_BASE_URL` for those
+ * providers) are authenticated with it, one sent straight to the host is not, and the value stays
+ * out of the sandbox unless a run asks for it (`raw: "refused"` forbids that; the default allows it).
+ *
+ * Every option left out keeps what the secret already has, so setting a bound secret again with
+ * a new value (a rotation) keeps its binding. `hosts: []` removes it.
+ */
+export interface SecretSetOpts {
+    /** Host names, e.g. `["api.openai.com"]` or `["*.openai.azure.com"]`. Never an address. */
+    hosts?: string[];
+    /** The request headers the key is sent in. Default: authorization, x-api-key, api-key, x-goog-api-key. */
+    headers?: string[];
+    /** `refused`: the value itself can never be given to a sandbox (`{ name, mode: "raw" }` is refused). */
+    raw?: "allowed" | "refused";
+    /** Mask the value out of responses from the bound hosts (default true). */
+    scanResponses?: boolean;
+}
+export interface SnapshotSource {
+    kind: "image" | "repo" | (string & {});
+    image?: string;
+    digest?: string;
+    [extra: string]: unknown;
+}
+export interface SnapshotBuild {
+    build_id: string;
+    state: BuildState;
+    snapshot_id?: string | null;
+    /** The name the snapshot holds now; `null` once it is deleted (see `snapshot_deleted`). */
+    alias?: string | null;
+    /** `true` when the snapshot this build made has since been deleted. */
+    snapshot_deleted?: boolean;
+    tier_assigned?: string;
+    /**
+     * The most the build can cost, USD, said before it runs: `max_seconds` at `per_second_usd`. A build
+     * is billed per second for the time it runs; what it cost is `cost_usd` once it has ended.
+     */
+    build_price?: number;
+    /** What one second of the build costs, USD: its tier's per-second rate. */
+    per_second_usd?: number;
+    /** The longest the build may run, in seconds: it is billed for at most this long. */
+    max_seconds?: number;
+    /** Once it has ended, the seconds it is billed for; 0 when it failed on our side. */
+    billable_seconds?: number;
+    /** Once it has ended, what it cost, USD; 0 when nothing was charged. */
+    cost_usd?: number;
+    repo?: string;
+    commit?: string;
+    verification?: Record<string, unknown>;
+    /** A rejected build names the guard and the measured value; nothing was stored. */
+    error?: {
+        code?: string;
+        guard?: string;
+        message?: string;
+        values?: number[];
+        stored?: boolean;
+    } | null;
+    /** Set when an identical build already existed. */
+    deduped?: boolean;
+    /**
+     * Set when an identical build was already IN PROGRESS and this answer is that build: wait on
+     * it like your own. Unlike `deduped`, nothing is finished yet.
+     */
+    joined?: boolean;
+    /** Server notes on this answer, e.g. that a joined build's alias was not applied. */
+    warnings?: string[];
+    /**
+     * `true` when this answer repeats an earlier create's (the same `Idempotency-Key`): nothing new
+     * was built or charged, whatever `build_price` says.
+     */
+    idempotent_replay?: boolean;
+    /** With `idempotent_replay`: how many seconds ago that first answer was given. */
+    idempotent_replay_age_s?: number;
+    /** Image or repo. */
+    source?: SnapshotSource;
+    /** `false` for an image snapshot built without `verify` — stored, but nothing was verified. */
+    verified?: boolean;
+    next?: string[];
+    [extra: string]: unknown;
+}
+export interface SnapshotRecord {
+    snapshot_id: string;
+    alias?: string | null;
+    visibility?: string;
+    repo?: string;
+    commit?: string;
+    setup?: string[];
+    verify?: {
+        cmd: string;
+        allow_fast?: boolean;
+    };
+    tier?: string;
+    tier_assigned?: string;
+    build_id?: string;
+    verification?: Record<string, unknown>;
+    /** Image or repo. */
+    source?: SnapshotSource;
+    /** `false` for an image snapshot built without `verify` — stored, but nothing was verified. */
+    verified?: boolean;
+    created_at?: string;
+    /**
+     * Set when the snapshot can no longer be started, saying why (it was lost before it could be
+     * kept); a fork of it is refused `snapshot_unavailable`. Absent while it can be started.
+     */
+    unavailable?: string;
+    /**
+     * The user commands, terminals and SSH sessions in its sandboxes run as when they name none:
+     * its image's own `USER`, or the `user` it was created with. Absent: root.
+     */
+    user?: string | null;
+    [extra: string]: unknown;
+}
+/** `GET /snapshots/:id/manifest`: the snapshot's manifest, sealed (`buildBundle` turns it into a `.promigence` bundle). */
+export interface SnapshotManifestResponse {
+    snapshot_id: string;
+    layers?: number;
+    apparent_bytes?: number;
+    transferable_bytes?: number;
+    cached_at?: string;
+    /**
+     * What a scrub of these bytes can verify. `verifiable: false` means
+     * the manifest records no digest for at least one artefact — the snapshot was built before
+     * digests were recorded, and no scrub can tell rot from the real bytes. `summary` is the line
+     * `promigence snapshot inspect` prints.
+     */
+    integrity?: {
+        verifiable?: boolean;
+        chunked?: string[];
+        whole_file?: string[];
+        unverifiable?: string[];
+        bytes?: number;
+        summary?: string;
+    };
+    manifest: Record<string, unknown>;
+    [extra: string]: unknown;
+}
+export interface ExecResponse {
+    exec_id: string;
+    /**
+     * The command's exit code. `null` only when the exit carried neither a code nor a signal: the
+     * result is unknown, which is never success (a signal is reported as `128 + signal`).
+     */
+    exit_code: number | null;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    /** True when the command was killed at its own timeout. */
+    timed_out?: boolean;
+    /** True when the command was killed for running out of memory. */
+    oom_killed?: boolean;
+    /** Why it ended without an exit code of its own: `timeout`, `out_of_memory` or `signal`. */
+    reason?: "timeout" | "out_of_memory" | "signal";
+    /** With `encoding: "base64"`: the exact bytes of standard output (see `execOutputBytes`). */
+    stdout_b64?: string;
+    /** With `encoding: "base64"`: the exact bytes of standard error. */
+    stderr_b64?: string;
+    [extra: string]: unknown;
+}
+/**
+ * A command's output as bytes: the exact bytes when it was asked for with `encoding: "base64"`,
+ * otherwise the UTF-8 of its text.
+ */
+export declare function execOutputBytes(r: ExecResponse, stream?: "stdout" | "stderr"): Uint8Array;
+export interface SandboxRecord extends QueuedInfo {
+    sandbox_id: string;
+    state: SandboxState;
+    /**
+     * Why it is paused, when a limit paused it rather than a request: `"spend_cap"` (its run
+     * reached its spend cap; resume with `spendCap` raised) or `"credits_exhausted"` (the
+     * organization's credits ran out; add a card, then resume). Absent otherwise.
+     */
+    pause_reason?: "spend_cap" | "credits_exhausted";
+    run_id?: string;
+    /**
+     * The snapshot it was started from, as its run names it (`runs.get(runId).snapshot_id`): the
+     * snapshot's id, or `promigence/base` for the built-in base.
+     */
+    snapshot_id?: string;
+    /** When the sandbox was created, RFC 3339. */
+    created_at?: string;
+    outcome?: Outcome;
+    /**
+     * The labels this sandbox inherited from its run — the same map `runs.start({ labels })` took.
+     *
+     * Reported so that a caller who found a sandbox with `list({ labels })` can see what it
+     * matched, and so that one who did not can learn what a sandbox is tagged with at all.
+     */
+    labels?: Record<string, string>;
+    /**
+     * Seconds of idleness after which this sandbox pauses itself; `0` when it never does.
+     * Set it with `sandboxes.patch(id, { autoPauseS })`.
+     */
+    auto_pause_s?: number;
+    /**
+     * What counts as idle: `"requests"` (the default) or `"activity"`. Set it with
+     * `sandboxes.patch(id, { autoPauseMode })`.
+     */
+    auto_pause_mode?: AutoPauseMode;
+    /** What this sandbox asks for on every start and resume (`runs.start({ optimizeFor })`). */
+    optimize_for?: OptimizeFor;
+    /**
+     * What its latest start or resume actually got; `null` before the first. It can differ from
+     * `optimize_for`, and the next resume asks again.
+     */
+    optimize_for_applied?: OptimizeFor | null;
+    /**
+     * The lifetime this sandbox is bound to, in milliseconds of running time: time spent paused
+     * does not count. `setTimeout` / `sandboxes.patch(id, { timeoutMs })` extend it.
+     */
+    timeout_ms?: number | null;
+    /**
+     * Milliseconds of running time since hand-over, paused time excluded: what `timeout_ms` is
+     * measured against, so `timeout_ms - elapsed_ms` is the time left. `null` before hand-over and
+     * once it has ended.
+     */
+    elapsed_ms?: number | null;
+    [extra: string]: unknown;
+}
+/** `POST /images/resolve`. */
+export interface ResolvedImage {
+    /** The pinned reference: your own name with `@sha256:…` on the end. Pass it to `snapshots.create`. */
+    image: string;
+    /** The digest `image` carries — the **index**'s, for a multi-arch tag. */
+    digest: string;
+    registry: string;
+    repository: string;
+    tag: string | null;
+    /** The media type at `digest`. Empty when the reference was already pinned. */
+    media_type: string;
+    /** Always `linux/amd64`: the one platform a sandbox runs. */
+    platform: string;
+    /** The `linux/amd64` child of an index; `null` for a single-platform manifest. */
+    platform_digest: string | null;
+    /** Every `os/arch` an index offered. Empty for a single manifest. */
+    platforms: string[];
+    /** `true` when the reference was already a digest and no registry was contacted. */
+    already_pinned: boolean;
+    ms?: number;
+}
+/** Options for {@link PromigenceClient.sandboxes}`.list`. */
+export interface SandboxListOptions {
+    limit?: number;
+    /**
+     * Only sandboxes whose run carries **every** one of these labels.
+     *
+     * This is a server-side filter, and that is the point: `limit` bounds the rows the server
+     * *reads*, so filtering in your own code cannot find a sandbox older than the last page.
+     * It is how two replicas of one service converge on a single sandbox instead of each
+     * forking its own.
+     */
+    labels?: Record<string, string>;
+    /** States to keep, server-side: `["running", "ready"]`. Empty = every state. */
+    state?: string[];
+    /** A `nextCursor` from an earlier page. Opaque: a client only ever echoes it back. */
+    cursor?: string;
+}
+/**
+ * One page of a list route. `nextCursor` is `null` on the last page, **and that is the only
+ * reliable stop signal**: a short page is not one, because a server-side filter can empty a page
+ * that still has successors.
+ */
+export interface Page<T> {
+    items: T[];
+    nextCursor: string | null;
+    /** What the server actually used, which is not always what was asked for (it caps at 500). */
+    limit: number;
+}
+/** `GET /health` — unauthenticated: `ok`, `version`, `serving` and `location`; `build_sha` to a caller with a key. */
+export interface HealthResponse {
+    ok?: boolean;
+    version?: string;
+    build_sha?: string;
+    /** Whether the service can start new sandboxes right now. */
+    serving?: boolean;
+    /** Where sandboxes run, in plain words (for example "US East Coast"); absent when not said. */
+    location?: string;
+    [extra: string]: unknown;
+}
+/** One service's row in `GET /status` (`api`, `sandboxes`): `up`, `degraded` or `down`. */
+export interface ServiceStatus {
+    name: string;
+    state?: string;
+    last_health_at?: string | null;
+    [extra: string]: unknown;
+}
+/** `GET /status` — unauthenticated; the synthetic check window plus one row per service. */
+export interface StatusResponse {
+    checks?: unknown;
+    services?: ServiceStatus[];
+    [extra: string]: unknown;
+}
+/** One API key (`KeyView` in the API reference). `api_key` is present only in the answer that minted it. */
+export interface KeyRecord {
+    key_id: string;
+    prefix: string;
+    name: string;
+    created_at: string;
+    created_by?: string | null;
+    last_used_at?: string | null;
+    revoked?: boolean | null;
+    revoked_at?: string | null;
+    /** When it stops working; `null` or absent = never. */
+    expires_at?: string | null;
+    /** The key that minted it; revoking that key revokes this one. */
+    minted_by?: string | null;
+    /** True for the key making this call. */
+    current?: boolean | null;
+    /** The secret, in the create answer only; never retrievable again. */
+    api_key?: string | null;
+    /** On a revoke: the keys this one minted, revoked with it. */
+    also_revoked?: string[] | null;
+}
+/** A key minted in an organization's project (`OrgKeyView`). `api_key` is shown once. */
+export interface OrgKeyRecord {
+    key_id: string;
+    prefix: string;
+    name: string;
+    org_id: string;
+    project_id: string;
+    service: boolean;
+    created_at: string;
+    created_by?: string | null;
+    expires_at?: string | null;
+    api_key: string;
+}
+/** A key's lifetime: days from now, or a date (`2027-01-31`) / UTC time ending in `Z`. Neither = never expires. */
+export interface KeyExpiry {
+    expiresInDays?: number;
+    expiresAt?: string;
+}
+export interface OrgRecord {
+    org_id: string;
+    name: string;
+    role: string;
+    default: boolean;
+    card_on_file: boolean;
+    projects: number;
+    members: number;
+    created_at: string;
+}
+export interface ProjectRecord {
+    project_id: string;
+    org_id: string;
+    name: string;
+    default: boolean;
+    keys: number;
+    /** The most the project may bill in a calendar month (UTC); `null` = no cap. */
+    monthly_cap_usd?: number | null;
+    created_at: string;
+}
+export interface MemberRecord {
+    user_id: string;
+    email: string;
+    role: string;
+    joined_at: string;
+    /** True for the person this call is made as. */
+    you: boolean;
+}
+export interface InviteRecord {
+    invite_id: string;
+    org_id: string;
+    org_name: string;
+    email: string;
+    role: string;
+    invited_by: string;
+    created_at: string;
+}
+/** `GET /credits/offer`: the account's free credit. It is claimed in a browser, never by an API call. */
+export interface CreditOffer {
+    /** `claimable` | `claimed` | `pending_review` | `needs_card` | `not_eligible` | `offer_ended` | `none` */
+    state: string;
+    credit_usd: number;
+    card_bonus_usd: number;
+    /** USD charged to confirm Apple Pay, Google Pay or Amazon Pay when one is added (added to the credit). */
+    method_check_usd?: number;
+    expires_at?: string | null;
+    campaign?: string | null;
+    message: string;
+}
+/** `GET /billing` — the customer's own month to date (`promigence billing usage`). */
+/** `GET /referrals` (`ReferralStatus` in the API reference). */
+export interface ReferralStatus {
+    /** `"on"` while an offer runs, else `"off"`. */
+    program: "on" | "off" | string;
+    /** Your code; `null` while the program is off. */
+    code: string | null;
+    offer: {
+        /** E.g. `"Give $50, get $100"`. */
+        headline: string;
+        give_usd: number;
+        get_usd: number;
+        credit_expiry_days: number | null;
+        hold_days: number;
+        qualifying_plans: string[];
+        ends_at: string | null;
+    } | null;
+    referrals: {
+        pending: number;
+        held: number;
+        rewarded: number;
+        under_review: number;
+        other: number;
+    };
+    earned_usd: number;
+    referred_by: {
+        status: string;
+        reward_usd: number;
+        rewarded_at: string | null;
+    } | null;
+    expiring_credits: Array<{
+        remaining_usd: number;
+        granted_usd: number;
+        expires_at: string;
+    }>;
+}
+/** `POST /referrals/apply` (`ReferralApplied`), and a first sign-in's `referral`. */
+export interface ReferralApplied {
+    /** `pending` | `under_review` | `not_applied` (sign-in only). */
+    status: string;
+    detail?: string;
+    code: string;
+    reward_usd: number;
+    qualifying_plans: string[];
+}
+/** One sandbox shape and its price in a {@link PricingView}. */
+export interface PricingTier {
+    /** The name `--tier` takes. */
+    name: string;
+    vcpus: number;
+    mem_gib: number;
+    disk_gib: number;
+    /** USD per second, on demand. */
+    per_second_usd: number;
+    /** USD per hour, on demand. */
+    per_hour_usd: number;
+    /** USD per second for a run started `preemptible`. */
+    preemptible_per_second_usd: number;
+    /** Within the account's largest sandbox shape (`limits.max_sandbox_vcpus`). */
+    available: boolean;
+}
+/**
+ * `GET /pricing` — the price list, read live on every call from what billing charges. Without a
+ * key: what a new account gets (`scope: "new_account"`). With one: what that key's organization
+ * pays (`scope: "organization"`). A run is billed at the rates in force when it was created.
+ */
+export interface PricingView {
+    /** `promigence.pricing/v1`. */
+    schema: string;
+    /** When these values were read (RFC 3339): read them again rather than keeping a copy. */
+    as_of: string;
+    /** `usd`. */
+    currency: string;
+    scope: "new_account" | "organization" | string;
+    /** `null` for `new_account`. */
+    org_id: string | null;
+    plan: {
+        plan_id: string;
+        display_name: string;
+        /** `null` when no plan is assigned and the standard values apply. */
+        version: number | null;
+        /** Work is paid from free credit, within the trial's limits, until a card is added. */
+        on_trial: boolean;
+    };
+    /** `per_second`. */
+    billing: string;
+    granularity_seconds: number;
+    min_billable_seconds: number;
+    rates: {
+        vcpu_second_usd: number;
+        gib_second_usd: number;
+        preemptible_vcpu_second_usd: number;
+        preemptible_gib_second_usd: number;
+        /**
+         * The most one snapshot build of the default tier can cost (`limits.build_max_s` seconds at that
+         * tier's rate). A build is billed per second at its own tier's rate for the time it runs.
+         */
+        build_usd: number;
+        /** Per GiB of data out above the month's allowance; `null` when not priced. */
+        egress_gb_usd: number | null;
+        /** Per GiB-month of stored snapshot data; `null` while not priced. */
+        storage_gb_month_usd: number | null;
+    };
+    /** Every shape on sale, smallest first. */
+    tiers: PricingTier[];
+    limits: {
+        /** `null` = no limit. */
+        max_concurrency: number | null;
+        /** The largest sandbox shape, in vCPU; `null` = no limit. */
+        max_sandbox_vcpus: number | null;
+        /** The longest a sandbox may live, extensions included. */
+        max_session_s: number;
+        /** A sandbox's timeout when its run names none. */
+        default_timeout_s: number;
+        max_count_per_run: number;
+        /** Data out included each month, GiB; `null` = none included. */
+        egress_gb_month: number | null;
+        /** Where data out stops each month, GiB; `null` = it does not stop. */
+        max_egress_gb_month: number | null;
+        /** Outbound mail ports open. */
+        smtp: boolean;
+        /** The longest a snapshot build may run, in seconds: the most one build is billed for. */
+        build_max_s?: number;
+    };
+    /** The free credit a new account gets (an account's own: `GET /credits/offer`). */
+    free_credit: {
+        /** Claimed once, in the browser; 0 once the offer has ended. */
+        signup_credit_usd: number;
+        /** More when a card is first added; 0 once the offer has ended. */
+        card_bonus_usd: number;
+        expiry_days_after_claim: number | null;
+        /** No free credit outlives this instant; `null` = no fixed end. */
+        expires_by: string | null;
+        terms_url: string;
+        /** New accounts need an invite code; a code may carry its own credit. */
+        invite_required: boolean;
+    };
+    monthly_fee_usd: number;
+    /** Usage the monthly fee includes each month, USD. */
+    included_credits_usd: number;
+    monthly_minimum_usd: number;
+}
+export interface BillingUsage {
+    org_id?: string;
+    /**
+     * `false` when this deployment takes no card: `billing.checkout()` / `portal()` then answer
+     * `billing_unavailable`, so nothing should send a customer to them.
+     */
+    billing_enabled?: boolean;
+    /**
+     * The payment state (`free` with no subscription, `payg` with one). The plan the limits come
+     * from — the name the refusals use — is `me().plan`.
+     */
+    plan?: string;
+    card_on_file?: boolean;
+    card?: {
+        brand?: string;
+        last4?: string;
+    } | null;
+    /** Set when the card on file does not unlock paid limits for this organization (it already pays for another one,
+     *  it is being confirmed with a $1 charge, or that charge did not go through). */
+    card_note?: string | null;
+    /** The $1 that confirms Apple Pay, Google Pay or Amazon Pay on file: `confirming`, `paid` or `failed`. */
+    method_check?: {
+        method: string;
+        status: string;
+        amount_usd: number;
+        bonus_usd?: number | null;
+    } | null;
+    suspended?: boolean;
+    suspend_reason?: string | null;
+    period?: {
+        start?: string;
+        end?: string;
+        basis?: string;
+    };
+    usage?: {
+        total?: number;
+        [extra: string]: unknown;
+    };
+    trial?: {
+        credits_remaining?: number;
+        [extra: string]: unknown;
+    } | null;
+    upcoming_invoice?: {
+        amount_due?: number | null;
+        currency?: string;
+        period_end?: string | null;
+    } | null;
+    upcoming_invoice_error?: string | null;
+    [extra: string]: unknown;
+}
+/** One row of `GET /billing/history`: a credit the organization received, or a payment. */
+export type BillingHistoryEntry = M.BillingHistoryEntry;
+/** What `billing.historyPage()` lists: everything, only credits, or only payments. */
+export type BillingHistoryKind = "all" | "credits" | "payments";
+/** One metered row of `GET /me/ledger`. */
+export interface LedgerEntry {
+    entry_id: string;
+    kind: string;
+    run_id?: string | null;
+    subject?: string;
+    tier?: string;
+    seconds?: number;
+    sandbox_id?: string | null;
+    interim?: boolean;
+    amount?: number;
+    detail?: unknown;
+    created_at?: string;
+    [extra: string]: unknown;
+}
+/** One exec's stored output, resolved by `exec_id` (`promigence exec output`). */
+export interface ExecOutput {
+    exec_id: string;
+    sandbox_id?: string;
+    run_id?: string;
+    argv?: string[];
+    exit_code?: number | null;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    /** Bytes actually returned after `range`, and the full size before it. */
+    bytes: number;
+    total_bytes: number;
+    range?: {
+        from: number;
+        to: number;
+    };
+}
+/** One line of a quote: N sandboxes at `per_second_usd` for up to `seconds_per_sandbox` each. */
+export interface QuoteLine {
+    sandbox_count: number;
+    per_second_usd: number;
+    seconds_per_sandbox: number;
+}
+/** The quote: per-second billing, `max_cost = Σ sandbox_count × seconds_per_sandbox × per_second_usd`. */
+export interface Quote {
+    max_cost: number;
+    /** `vcpus × vcpu_second_usd + mem_gib × gib_second_usd`. */
+    per_second_usd: number;
+    vcpu_second_usd: number;
+    gib_second_usd: number;
+    vcpus: number;
+    mem_gib: number;
+    /** `ceil(timeout_ms / 1000)`: the most one sandbox can bill. */
+    seconds_per_sandbox: number;
+    breakdown: QuoteLine[];
+}
+/** `POST /runs/quote` — the bill before the run starts. */
+export interface RunQuote {
+    snapshot: string;
+    snapshot_id?: string | null;
+    count: number;
+    timeout_ms: number;
+    tier: string;
+    billing: "per_second";
+    granularity_seconds: number;
+    min_billable_seconds: number;
+    vcpus: number;
+    mem_gib: number;
+    vcpu_second_usd: number;
+    gib_second_usd: number;
+    per_second_usd: number;
+    per_hour_usd: number;
+    seconds_per_sandbox: number;
+    /** Rounded to cents; `quote.max_cost` carries full precision. */
+    max_cost: number;
+    breakdown: QuoteLine[];
+    quote: Quote;
+    spend_cap: number;
+    /** Trial orgs: credits not already reserved by live sandboxes. `null` with a card. */
+    credits_available?: number | null;
+    /** Things that will surprise the invoice if unread: a free bench tier, a quote already over
+     *  the cap, a quote the trial credits do not cover. */
+    warnings: string[];
+}
+/** `POST /runs/:id/replay` — client-triggered, never automatic. */
+export interface ReplayResponse {
+    ok: boolean;
+    run_id: string;
+    replayed: number;
+    sandboxes: Array<{
+        sandbox_id: string;
+        replay_of: string;
+        state: string;
+    }>;
+    detail?: string;
+}
+export interface Capture {
+    snapshot_id: string;
+    run_id: string;
+    sandbox_id: string;
+    outcome: string;
+    code: string;
+    /** What keeping it costs — and what deleting it gives back. */
+    bytes: number;
+    captured_at: string;
+    /** When it goes at the latest; it can stop being openable sooner (`available`). */
+    expires_at: string;
+    /** Whether `runs.open` can still open it; `false` once it was lost before it expired. */
+    available?: boolean;
+}
+/** `GET /runs/:id/captures`. */
+export interface CapturesResponse {
+    ok: boolean;
+    run_id: string;
+    captures: Capture[];
+}
+/**
+ * `POST /runs/:id/open` — a NEW live sandbox forked from a failure, with its own id and its own
+ * billing clock. It is not the dead sandbox resurrected.
+ */
+export interface OpenResponse {
+    ok: boolean;
+    run_id: string;
+    /** The new sandbox. Exec against this one. */
+    sandbox_id: string;
+    state: string;
+    /** The sandbox whose failure it was forked from. */
+    opened_from: string;
+    snapshot_id: string;
+    /** When that sandbox failed, and how. */
+    failed_at: string;
+    outcome: string;
+    code: string;
+    expires_at: string;
+    committed_seconds: number;
+    timeout_ms: number;
+    max_cost: number;
+    ready_ms?: number;
+    detail?: string;
+}
+/**
+ * `PATCH /sandboxes/:id` — extend one live sandbox inside the cap, and/or set its idle rule.
+ *
+ * Everything but `ok` and `sandbox_id` is optional because either field may be sent on its own:
+ * a call that only set `autoPauseS` answers with the idle window and nothing about the cap,
+ * since nothing about the cap changed.
+ */
+export interface SandboxPatchResponse {
+    ok: boolean;
+    sandbox_id: string;
+    run_id?: string;
+    timeout_ms?: number;
+    committed_seconds?: number;
+    cost?: {
+        added: number;
+        charged: number;
+        live_commitment: number;
+        ceiling: number;
+        remaining: number;
+    };
+    /** Seconds of idleness after which the sandbox pauses itself; `0` when it never does. */
+    auto_pause_s?: number;
+    /** What counts as idle: `"requests"` or `"activity"`. */
+    auto_pause_mode?: AutoPauseMode;
+}
+/**
+ * What the idle rule counts as idle. `"requests"` (the default): nobody has called the sandbox
+ * for the window and no command, terminal or SSH session is open. `"activity"`: all of that, and
+ * for the whole window nothing inside used CPU or sent or received a byte, and no network
+ * connection to the outside is open — for an agent that runs inside the sandbox on its own.
+ */
+export type AutoPauseMode = M.AutoPauseMode;
+/** `POST /snapshots/:id/verify` — re-run the recorded `verify` in a fresh fork. */
+export interface SnapshotVerifyResponse {
+    run_id: string;
+    snapshot_id: string;
+    alias?: string | null;
+    verify: string;
+    workspace: string;
+    /** The most the fork can cost (`seconds × per_second_usd`) — printed before waiting, like `build_price`. */
+    price: number;
+    seconds: number;
+    per_second_usd: number;
+    tier: string;
+    count: number;
+    last_verified_at?: string | null;
+    sandboxes: Array<{
+        sandbox_id: string;
+        state: string;
+    }>;
+}
+/** `GET /sandboxes/:id/files/stat`. */
+export interface FileStat {
+    path: string;
+    size: number;
+    /** Octal, as a string — `"644"`. */
+    mode: string;
+    mtime_unix_ns: number;
+    is_dir: boolean;
+    is_symlink: boolean;
+}
+export interface DirEntry {
+    name: string;
+    path: string;
+    size: number;
+    /** Octal, as a string — `"100644"`. */
+    mode: string;
+    /**
+     * `null` when the listing could give names only. A missing owner is reported as missing
+     * rather than as root, because `0` is a real uid somebody may act on.
+     */
+    uid?: number | null;
+    gid?: number | null;
+    mtime_unix_ns: number;
+    is_dir: boolean;
+    is_symlink: boolean;
+}
+/** An opaque label of how a file request was answered, passed through for support. */
+export type ServedBy = string;
+/** `GET /sandboxes/:id/files/list?path=`. */
+export interface DirListing {
+    sandbox_id: string;
+    path: string;
+    entries: DirEntry[];
+    /** More than 10,000 entries, or a listing too large for one exec: this is a prefix. */
+    truncated: boolean;
+    served_by?: ServedBy;
+}
+/** `?recursive=&depth=&limit=&hidden=` on `files/list`. */
+export interface DirListOpts {
+    recursive?: boolean;
+    /** With `recursive`: how many levels below `path`. Unset = no bound. */
+    depth?: number;
+    limit?: number;
+    /** Dotfiles are listed by default; `false` omits them. */
+    hidden?: boolean;
+}
+export interface FileInfo {
+    sandbox_id: string;
+    path: string;
+    size: number;
+    /** Octal, as a string — `"40755"` for a directory. */
+    mode: string;
+    mtime_unix_ns: number;
+    is_dir: boolean;
+    is_symlink: boolean;
+    served_by?: ServedBy;
+}
+/** One hit of `GET /sandboxes/:id/files/search`. `line`/`text` only for a `contains` search. */
+export interface FileMatch {
+    path: string;
+    line?: number | null;
+    text?: string | null;
+}
+export interface SearchResult {
+    sandbox_id: string;
+    path: string;
+    matches: FileMatch[];
+    /** `limit` was reached: this is a prefix of the hits, not all of them. */
+    truncated: boolean;
+    served_by?: ServedBy;
+}
+/** `pattern` is a name glob (`*.py`); `contains` is literal text looked for inside the files. */
+export interface SearchOpts {
+    pattern?: string;
+    contains?: string;
+    ignoreCase?: boolean;
+    limit?: number;
+    hidden?: boolean;
+}
+/**
+ * `POST /sandboxes/:id/files/archive` — where the tar landed **inside the sandbox** and how big
+ * it is. The bytes stay in the sandbox on purpose; see `files.downloadDir`.
+ */
+export interface ArchiveResult {
+    sandbox_id: string;
+    /** Where the tar landed inside the sandbox. */
+    archive_path: string;
+    /** Its size in bytes. */
+    size: number;
+    /** The directory that was packed. */
+    source: string;
+    served_by?: ServedBy;
+}
+/** `POST /sandboxes/:id/files/extract`. `entries` is `null` on the fallback path, which cannot
+ *  count them without a second pass — a number invented there would be worse than none. */
+export interface ExtractResult {
+    sandbox_id: string;
+    archive: string;
+    into: string;
+    entries: number | null;
+    served_by?: ServedBy;
+}
+/**
+ * A background exec (`POST /sandboxes/:id/execs {background: true}`) as the API reports it.
+ * `exec_id` is scoped to its sandbox and only resolves under the sandbox that started it.
+ */
+export interface BackgroundExecRecord {
+    exec_id: string;
+    sandbox_id: string;
+    state: "running" | "exited" | "failed";
+    /** The command as started (`sh` or `argv` joined). */
+    argv: string;
+    /** Started with `stdin: true`, so `execs.stdin` can write to it. A child's stdin cannot be
+     *  opened after it has been spawned, which is why this is a property of the start and not a
+     *  thing to try. */
+    stdin_open?: boolean;
+    started_unix_ns?: number;
+    /** Bytes buffered (≤ `max_output_bytes` per stream) and bytes written in total. */
+    stdout_bytes: number;
+    stderr_bytes: number;
+    stdout_total?: number;
+    stderr_total?: number;
+    truncated?: boolean;
+    /** Started with `follow`: the newest output is kept, and the handle goes 10 minutes after it ends. */
+    follow?: boolean;
+    /** A range read of a `follow` command: bytes dropped between the asked offset and the first held. */
+    skipped?: number;
+    exit?: {
+        exit_code: number | null;
+        signal: number | null;
+        wall_ms?: number;
+        cpu_ms?: number;
+        max_rss_kib?: number;
+        truncated?: boolean;
+        oom_killed?: boolean;
+    };
+    error?: {
+        code: string;
+        msg: string;
+    };
+    /** With `waitMs`: how long the API parked the request. */
+    waited_ms?: number;
+    /**
+     * Present when the sandbox pauses itself when idle: after the command ends, the idle rule waits
+     * up to this many seconds for its result to be read. `forget` the handle to release it at once.
+     */
+    idle_hold_s?: number;
+}
+/** A published port (`POST /sandboxes/:id/ports`). The `url` is live until revoked or killed. */
+/** What `POST /sandboxes/:id/ssh` answers. */
+export interface SshAccess {
+    sandbox_id: string;
+    key_id: string;
+    fingerprint: string;
+    /** The login name. It is the sandbox id: a key is authorised for one name only. */
+    user: string;
+    host: string;
+    /** The access credential. Shown once, expires, reaches this sandbox and nothing else. */
+    token: string;
+    expires_at: string;
+    idle_timeout_s: number;
+    /** A `known_hosts` line body for this sandbox. Pin it. */
+    host_key: string;
+    host_key_fingerprint: string;
+    proxy_command: string;
+    ssh_command: string;
+}
+export interface SshKeyRecord {
+    key_id: string;
+    fingerprint: string;
+    user: string;
+    expires_at: string;
+    created_at: string;
+    token_active: boolean;
+}
+export interface SshAccessList {
+    sandbox_id: string;
+    keys: SshKeyRecord[];
+    idle_timeout_s: number;
+    host_key?: string;
+    host_key_fingerprint?: string;
+}
+export interface SshRevoked {
+    sandbox_id: string;
+    key_id: string;
+    revoked: boolean;
+}
+export interface PortRecord {
+    sandbox_id: string;
+    port: number;
+    /** 256-bit capability; anyone with the URL reaches the port. */
+    token: string;
+    url: string;
+    /** The same token as a DNS label, for a wildcard-DNS deployment (`<label>.<suffix>`). */
+    host_url_label?: string;
+    created_unix_ns?: number;
+}
+/** A key named without its secret (`/me`'s `key`, the key lists). */
+export interface KeyRef {
+    key_id: string;
+    name?: string;
+    /** The first few characters, enough to recognise a key without holding it. */
+    prefix?: string;
+    /** A project's service key: it outlives its minter's membership. */
+    service?: boolean;
+}
+export interface MeResponse {
+    org_id?: string;
+    /** The organization's name. */
+    org?: string;
+    /** The key this request was made with. */
+    key?: KeyRef | null;
+    user?: {
+        user_id: string;
+        email?: string;
+        provider?: string;
+    } | null;
+    /**
+     * The plan the organisation's limits and prices come from: `hobby` for a trial organisation
+     * with no plan assigned. The name `tier_over_plan` and the other refusals use.
+     */
+    plan?: string;
+    limits?: {
+        max_inflight?: number;
+        max_concurrency?: number;
+        max_session_s?: number | null;
+        max_sandbox_vcpus?: number | null;
+        [extra: string]: number | null | undefined;
+    };
+    /**
+     * Sandboxes holding capacity now (queued, starting, ready or running; paused ones hold none)
+     * against the limit.
+     */
+    concurrency?: {
+        limit?: number;
+        in_use?: number;
+    };
+    /**
+     * What the organisation has spent, in USD. Absent (with `spend_detail`, `trial` and `notice`)
+     * for a key that may not see the organisation's money: only an owner's key of the default
+     * project does.
+     */
+    spend?: number;
+    spend_detail?: {
+        total?: number;
+        currency?: string;
+        billable_seconds?: number;
+        by_kind?: Record<string, number>;
+    };
+    /** The cap a run gets when it names none, in USD; `0` names none (the run is capped at its quote). */
+    default_spend_cap?: number;
+    card_on_file?: boolean;
+    /** The free trial: credits, data out and the limits that apply until a card is on file. */
+    trial?: TrialStatus;
+    /** Something about the account to act on (the card-required switch), or null. */
+    notice?: AccountNotice | null;
+    [extra: string]: unknown;
+}
+/**
+ * `Promigence-Notice` on any response, and `notice` on `me()` / `GET /billing`: an announced or
+ * active card requirement for an org on the free trial. `code` is `card_required_soon` before
+ * `effective_at`, `card_required` after it. Credits are never taken away.
+ */
+export interface AccountNotice {
+    code: "card_required_soon" | "card_required" | (string & {});
+    effective_at?: string;
+    credits_remaining?: number;
+    message?: string;
+    fix?: string;
+    docs?: string;
+    [extra: string]: unknown;
+}
+export interface TrialStatus {
+    on_trial: boolean;
+    card_on_file: boolean;
+    credits_granted: number;
+    credits_remaining: number;
+    credits_reserved?: number;
+    credits_available?: number;
+    egress_gb_used: number;
+    egress_gb_cap: number | null;
+    limits?: {
+        max_concurrency?: number | null;
+        max_session_s?: number | null;
+        egress_gb_month?: number | null;
+        smtp?: boolean;
+    };
+    policy?: {
+        mode: string;
+        card_required_from?: string | null;
+        notice_from?: string | null;
+        card_required_now?: boolean;
+    };
+    [extra: string]: unknown;
+}
+/** The response header an account notice rides on. */
+export declare const NOTICE_HEADER = "promigence-notice";
+export interface PromigenceClientOpts {
+    apiKey?: string;
+    apiUrl?: string;
+    /** Injected for tests; defaults to global `fetch`. An injected `fetch` carries every request. */
+    fetch?: FetchLike;
+    /**
+     * Send API calls over one shared HTTP/2 connection when the API offers it (Node.js only;
+     * default `true`). `false`, or `PROMIGENCE_HTTP2=0` in the environment, sends every request
+     * through `fetch`. Anything HTTP/2 cannot do safely falls back to `fetch` on its own.
+     */
+    http2?: boolean;
+    /**
+     * Per-request timeout (default 30 s). Waits are bounded separately, by `waitTimeoutMs`, and a
+     * wait is not ended by one request hitting this — see `waitLoop`.
+     *
+     * From the CLI: `promigence --request-timeout DUR` or `PROMIGENCE_REQUEST_TIMEOUT`.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * How many times a request is sent again (default 3): after a 429 or a 503, and after a 502 or
+     * 504 that is not the API's own answer when sending twice is harmless (a read, a delete, or a
+     * create with its idempotency key).
+     */
+    maxRetries?: number;
+    /** Backoff base when the server sends no `Retry-After` (default 250 ms). */
+    retryBaseMs?: number;
+    userAgent?: string;
+    /**
+     * The framework, harness or adapter driving this client: `"harbor"`, `"my-harness/2.1.0"`.
+     * Highest precedence; see `setCaller` for the rest of the order, the validation
+     * and why nothing is ever auto-detected.
+     */
+    caller?: string;
+    /**
+     * Called once per distinct account notice (`Promigence-Notice`), e.g. a card requirement that
+     * starts on a date. Default: one `process.emitWarning` per distinct notice. The latest is also
+     * on `client.notice`.
+     */
+    onNotice?: (notice: AccountNotice) => void;
+    /**
+     * Called with every answer's timing ([`Timing`]): the round trip this process saw and how long
+     * the answer took on Promigence's side. A CLI uses it to say how far away the caller is.
+     */
+    onTiming?: (timing: Timing) => void;
+}
+/** `GET /sandboxes/:id/network`. */
+export interface SandboxNetwork {
+    sandbox_id: string;
+    /** What was asked for: `"egress"`, `"none"`, or `{ allow: [...] }`. */
+    network: NetworkMode;
+    state: string;
+    /** Hosts this sandbox looked up and was refused, newest first. */
+    refused_hosts?: {
+        host: string;
+        count?: number;
+        last_unix_ns?: number;
+    }[];
+    /** The hosts this sandbox may reach for its host-bound secrets, whatever `network` says. */
+    via_secret?: {
+        secret: string;
+        hosts: string[];
+    }[];
+    /** Total refused lookups, including hosts past the list above. */
+    refused_lookups?: number;
+    /** Connections refused to an address that was never resolved for an allowed host. */
+    refused_connections?: number;
+}
+/** `POST /sandboxes/:id/network {network: "none"}`. */
+export interface SandboxNetworkCut {
+    sandbox_id: string;
+    network: {
+        mode: "none";
+    };
+    /** Whether anything changed; `false` means egress was already cut. */
+    applied: boolean;
+    state: string;
+}
+/**
+ * One stored secret, bound to the environment variable it arrives as.
+ *
+ * A plain string is the common case — the secret's name is also the variable's. The object form
+ * is what makes a per-session credential possible: ten stored secrets, ten sandboxes, **one**
+ * variable name, at the same time.
+ *
+ * ```ts
+ * secrets: ["OPENAI_API_KEY", { name: "work_secret_7", as: "ANTHROPIC_WORK_SECRET" }]
+ * ```
+ *
+ * A secret bound to hosts (`secrets.set(name, value, { hosts })`) does not put its value in the
+ * sandbox; `mode: "raw"` asks for the value itself, and is refused for one stored with `raw: "refused"`.
+ */
+export type SecretBinding = string | {
+    name: string;
+    as?: string;
+    mode?: "raw";
+};
+export interface RunStartOpts {
+    snapshot: string;
+    count: number;
+    timeoutMs?: number;
+    spendCap?: number;
+    allowPartial?: boolean;
+    verifyEach?: boolean;
+    network?: NetworkMode;
+    optimizeFor?: OptimizeFor;
+    /**
+     * Secrets for every sandbox of this run. An `exec` is no longer required: a run that names
+     * its secrets here gives them to every command run against every one of its sandboxes,
+     * foreground or background, so a long-lived credentialed worker does not have to hold a
+     * streaming exec open for its whole life.
+     */
+    secrets?: SecretBinding[];
+    labels?: Record<string, string>;
+    /** Terminal exec: run in every sandbox after hand-over; `killOnExit` ends the sandbox. */
+    exec?: {
+        argv?: string[];
+        sh?: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        killOnExit?: boolean;
+        timeoutMs?: number;
+        maxOutputBytes?: number;
+    };
+    /**
+     * Score the work after the episode, in a clean copy of the snapshot. Needs an `exec` — there
+     * is no episode to grade without a command. A snapshot may carry a default grader, in which
+     * case this can be left off.
+     */
+    grade?: {
+        cmd: string;
+        holdoutCmd?: string;
+        timeoutMs?: number;
+        score?: ScoreMode;
+    };
+    /**
+     * Keep what the grader prints: its last 16 KiB come back in each graded sandbox's
+     * `grade.output` in the run report. Never a held-out grader's. Unset: the snapshot's default
+     * grader's own setting when the run uses it, otherwise off.
+     */
+    gradeOutput?: boolean;
+    idempotencyKey?: string;
+    /**
+     * Abort the request. Whether the run was started is then unknown: send the same create again
+     * under the same `idempotencyKey` to get its answer (the API never starts it twice), then end it.
+     */
+    signal?: AbortSignal;
+    /**
+     * Hold `POST /runs` until every sandbox has left `queued`, for at most this long
+     * (`?wait_ms=`, capped at 30 s). The answer's `sandboxes[]` then already carries `ready` rows,
+     * so creating a sandbox is one round trip instead of two. A row still `queued` in the answer
+     * (the budget was spent) is the caller's cue to fall back to `runs.waitReady`.
+     */
+    waitMs?: number;
+}
+export interface ExecOpts {
+    argv?: string[];
+    sh?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    user?: string;
+    /**
+     * Stored secrets to deliver as environment variables. Names, never values.
+     *
+     * A string binds a secret to a variable of the same name; `{ name, as }` binds it to a
+     * different one, which is how two sandboxes hold two values for one variable at once.
+     */
+    secrets?: SecretBinding[];
+    /**
+     * Cancel an in-flight exec, streamed or not: the client stops waiting and the request is closed,
+     * which ends the command in the sandbox. A buffered exec then throws `TimeoutError` ("aborted by
+     * the caller's signal"); a streamed one rejects with the signal's `AbortError`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Close the sandbox on this command's verdict, exactly as `POST /runs {exec}` does.
+     *
+     * This is what `promigence run --stream` uses: the streaming composite has to own the exec (you
+     * cannot attach to a command the scheduler is already running), and without it the sandbox
+     * would be closed by the client's kill and reported `aborted_by_client` — a green run turned
+     * red by the act of watching it.
+     */
+    terminal?: boolean;
+    /** With `terminal`, kill the sandbox when the command exits. Defaults to `terminal`. */
+    killOnExit?: boolean;
+    timeoutMs?: number;
+    /**
+     * Output kept per stream, default 64 KiB. Past it the answer keeps the last bytes and says
+     * `truncated`; the rest cannot be fetched afterwards. A background exec keeps all of it.
+     */
+    maxOutputBytes?: number;
+    /**
+     * `"base64"`: the answer carries the output as its exact bytes (`stdout_b64` / `stderr_b64`,
+     * read them with `execOutputBytes`), for output that is not text. `exec` only: `execStream`
+     * already hands over bytes.
+     */
+    encoding?: "text" | "base64";
+    /**
+     * Sent as `Idempotency-Key` only when you pass one; the SDK never makes one up for a command.
+     * The API runs a buffered or background command once per key (24 h, per org) and answers a
+     * repeat with the first answer (at most 1 MiB of output kept for it; a longer one comes back cut,
+     * `replay_truncated: true`). A streamed command (`execStream`) cannot be replayed and refuses a
+     * key. The SDK itself never sends an exec that may have started a second time.
+     */
+    idempotencyKey?: string;
+}
+/** `verify: "bun typecheck"` is shorthand for `{ cmd: "bun typecheck" }`. */
+export type VerifySpec = string | {
+    cmd: string;
+    allowFast?: boolean;
+};
+/** `verify` is optional for the image forms: without it the snapshot is stored `verified: false`. */
+/**
+ * One **additional** pinned repository a world is built from, cloned before `setup` runs.
+ *
+ * `path` is optional and defaults to the repository's own name beside the workspace
+ * (`https://github.com/org/lib` → `/work/lib`). A relative path is relative to the workspace
+ * (`vendor/lib` → `/work/repo/vendor/lib`), which is what an app-plus-library layout wants.
+ */
+export interface ExtraSource {
+    repo: string;
+    /** 40 hex. A branch is not a pin. */
+    commit: string;
+    path?: string;
+}
+/** The most extra sources one snapshot may name. */
+export declare const MAX_SOURCES = 8;
+export interface SnapshotCreateOpts {
+    /**
+     * A public git URL (with `commit`), or `github:owner/name`: a repository the organization's
+     * GitHub connection can read (`github.repos()`), built at `ref` (default: its default branch).
+     */
+    repo?: string;
+    commit?: string;
+    /** `github:` repositories: a branch, a tag or a sha, resolved to a commit when the build is accepted. */
+    ref?: string;
+    /** `github:` repositories: the snapshot the build starts from (id or alias; default `promigence/base`). */
+    from?: string;
+    /**
+     * `github:` repositories with a branch and an `alias`: every push to the branch builds the
+     * snapshot again and moves the alias to it. Each automatic build is a normal build, charged.
+     */
+    track?: boolean;
+    /**
+     * Extra repositories for the `repo` form, cloned in this order into their paths before
+     * `setup` runs: a harness repo beside a task repo, an app beside the library being changed
+     * with it. Each lands in the manifest's `provenance.sources[]` with its commit, which a repo
+     * cloned inside a `setup` step never did — so a world built this way is rebuildable, and one
+     * built the old way only looked it.
+     */
+    sources?: ExtraSource[];
+    image?: string;
+    dockerfile?: {
+        context: string;
+        path?: string;
+    };
+    setup?: string[];
+    verify?: VerifySpec;
+    /** Image forms: a background process started before the snapshot, so forks inherit it running. */
+    start?: string | string[];
+    /**
+     * Image and Dockerfile forms: environment variables for every command, terminal and SSH
+     * session in this snapshot's sandboxes (and its own setup, verify and start), set over the
+     * image's `ENV` as `docker run -e` sets them. A value may build on what the image sets with
+     * `${containerEnv:NAME}` (or `${containerEnv:NAME:default}`):
+     * `{ PATH: "${containerEnv:PATH}:/opt/tools/bin" }`.
+     */
+    env?: Record<string, string>;
+    tier?: Tier;
+    /** Image forms: the name of a stored secret holding the registry credentials. */
+    registrySecret?: string;
+    /**
+     * Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes
+     * run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an
+     * image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run`
+     * does (root when it sets none).
+     */
+    user?: string;
+    /**
+     * Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example
+     * the snapshot's own `user`). Default: `root`.
+     */
+    setupUser?: string;
+    alias?: string;
+    /**
+     * A DEFAULT grader for this snapshot: a run on it with no `grade` of its own uses this one.
+     * The same shape as `runs.start({ grade })`.
+     */
+    grade?: {
+        cmd: string;
+        holdoutCmd?: string;
+        timeoutMs?: number;
+        score?: ScoreMode;
+    };
+    /** Runs that use this default grader keep what it prints (`runs.start({ gradeOutput })`). Needs `grade`. */
+    gradeOutput?: boolean;
+    idempotencyKey?: string;
+}
+export interface WaitOpts {
+    /** Bound on the wait (default 100 s). */
+    waitTimeoutMs?: number;
+    /**
+     * Force a fixed client-side poll interval. Setting this opts out of the server-side long-poll
+     * (`?wait_ms=`) entirely — use it only to pin a cadence in a test.
+     */
+    pollMs?: number;
+    signal?: AbortSignal;
+    /**
+     * Fires on every read with the run's `capacity` block, so a caller can render a waiting state
+     * that **moves** ("capacity arriving, ~28 s" -> running) instead of a
+     * spinner over a word that never changes.
+     *
+     * Passing it caps each server-side park at `PROGRESS_POLL_MS`, exactly like `onReady`: the park
+     * only ends when *every* sandbox is ready, and the point of this callback is the time before
+     * that.
+     */
+    onCapacity?: (c: Capacity) => void;
+}
+/** Per-request knobs the wait helpers pass down to `runs.get` / `runs.sandboxes`. */
+export interface ReadOpts {
+    /**
+     * Long-poll: ask the API to hold the request until the run reaches the endpoint's condition
+     * (all sandboxes out of `queued` / run finished) or `waitMs` elapse. A server that ignores the
+     * parameter answers immediately — see `waitReady`'s fallback.
+     */
+    waitMs?: number;
+    onHeaders?: (headers: Headers) => void;
+    signal?: AbortSignal;
+}
+export interface WaitReadyResult {
+    sandboxes: SandboxRef[];
+    timedOut: boolean;
+    waitedMs: number;
+}
+export interface WaitRunResult {
+    run: RunRecord;
+    timedOut: boolean;
+    waitedMs: number;
+}
+export type { CredentialStore } from "./credstore.js";
+export interface Credentials {
+    api_key?: string;
+    api_url?: string;
+}
+export declare function configDir(env?: NodeJS.ProcessEnv): string;
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Why the credentials file (or its directory) is not this user's alone, or `undefined` when it
+ * is. The CLI refuses to WRITE into a directory another user owns; the readers refuse to trust
+ * one, since a planted file names both the key and the URL every request goes to. Owned by
+ * another user, or writable by others, is refused; group-writable only when the group is not
+ * this user's own (a umask 002 system gives every user a private group, and a file the user made
+ * by hand there must keep working). No POSIX owner (Windows): nothing to check.
+ */
+export declare function credentialsTrustProblem(path: string): string | undefined;
+/**
+ * Why the credentials FILE can be read by someone else, or `undefined` when only its owner can.
+ * `promigence login` always writes it 0600, so a looser mode is
+ * a file made or copied by hand. It is still used, as it always was — refusing would break a working
+ * setup — but a secret others can read is named once, with the fix. No POSIX mode (Windows): nothing.
+ */
+export declare function credentialsExposure(path: string): string | undefined;
+/**
+ * The stored sign-in: JSON `{api_key, api_url}` (a bare key on the first line is accepted too) from
+ * the credentials file, or from the OS keychain item `promigence login` stored when there is no
+ * file. A file another user could have written is ignored, with one warning per process (see
+ * `credentialsTrustProblem`).
+ */
+export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials;
+export declare function apiUrlFromCompatUrl(url: string | undefined): string | undefined;
+export declare function apiUrlFromCompatDomain(domain: string | undefined): string | undefined;
+export declare function compatApiKey(key: string | undefined): string | undefined;
+/** Which variable a key came from, for `promigence doctor`. */
+export declare function keyOrigin(env?: NodeJS.ProcessEnv): string | undefined;
+/** `name@sha256:<64 hex>`, optionally with a tag before the `@`: a reference already pinned. */
+export declare const IMAGE_DIGEST_RE: RegExp;
+/**
+ * Why `image` is not a reference the API can pin, or `undefined` when it is.
+ *
+ * The same checks, in the same order, as the API makes (and the Python SDK's
+ * `image_ref_problem`), so a reference is refused here exactly when the server would refuse it
+ * — and a tag is accepted, because the server pins it: `POST /snapshots` resolves `python:3.12`
+ * to `python@sha256:…` itself.
+ */
+export declare function imageRefProblem(image: unknown): string | undefined;
+/**
+ * Refuse a malformed image reference before a round trip is spent on it. A tag is fine: the
+ * server pins it to a digest when the snapshot is created.
+ */
+export declare function checkImageRef(image: unknown): asserts image is string;
+/**
+ * Whether a well-formed image reference names its version: a tag (`python:3.12`) or a digest
+ * (`python@sha256:…`). `python` alone names neither, and is pinned to whatever `python:latest`
+ * is on the day it is used.
+ */
+export declare function imageRefNamesVersion(image: string): boolean;
+/**
+ * Refuse an image reference with neither a tag nor a digest, which would silently build
+ * whatever `:latest` is today. `:latest` written out is a choice and is accepted.
+ */
+export declare function checkImageVersioned(image: string): void;
+/** A git context, pinned: `https://github.com/org/app@<40 hex>`. A branch is not a pin. */
+export declare const CONTEXT_GIT_RE: RegExp;
+/**
+ * What in a repository URL can carry a credential: a user name, password or token (`https://TOKEN@…`,
+ * `https://user:pass@…`, `:token@`, a percent-encoded `@`, any `@` in a scheme URL, the scp form's
+ * `git@host:…`), a query string or a fragment. The server refuses every such URL with
+ * `repo_credentials_not_supported`; this is the same rule, so the URL is refused before it
+ * leaves this process. A public
+ * `https://host/org/repo` is `undefined`.
+ */
+export declare function repoUrlCredential(url: string): "userinfo" | "query" | "fragment" | undefined;
+/** `URL@<pin>` → `URL`; a last `@` followed by a path is not a pin, and the whole string is the URL. */
+export declare function withoutPin(s: string): string;
+export declare const REPO_CREDENTIALS_FIX: string;
+/**
+ * Refuse a repository URL that carries a credential, naming `field` and never the URL — the
+ * server's own answer, `repo_credentials_not_supported` (exit 2), raised before anything is sent.
+ */
+export declare function checkRepoUrl(url: unknown, field: string): void;
+/** Refuse a context that is neither a pinned git URL nor a packed directory. */
+export declare function checkDockerfileContext(context: unknown): asserts context is string;
+/**
+ * The `POST /snapshots` body for one of its three forms; throws `InvalidArgumentError` before
+ * anything is sent. Kept field-for-field with `sdk-py` (`_ops.snapshot_create_body`) so the two
+ * SDKs send the same bytes for the same call.
+ */
+export declare function snapshotCreateBody(opts: SnapshotCreateOpts): Record<string, unknown>;
+/** Build the right `PromigenceError` subclass for an API error `{code, message, fix, docs}`. */
+export declare function errorFor(code: string, message: string, fix: string, extra?: {
+    docs?: string;
+    status?: number;
+    requestId?: string;
+    retryAfterMs?: number;
+    category?: string;
+    retryable?: boolean;
+}): PromigenceError;
+/**
+ * Is `method path` a create that takes an `Idempotency-Key`? `path` is relative to `/v1` and may
+ * carry a query string. The list is the API reference's (generated from the operations that
+ * document the header), so a create the API keys is never sent unkeyed by this client.
+ */
+export declare function isKeyedCreate(method: string, path: string): boolean;
+/** A sandbox id as a request names it: a non-empty string, or refused before anything is sent. */
+export declare function checkSandboxId(sandboxId: unknown, call: string): asserts sandboxId is string;
+/** A spend cap in USD: a finite number, 0 or more. A negative one used to be sent and echoed back as "$-1.00". */
+export declare function checkSpendCap(spendCap: number): number;
+/** A key for ONE logical create: made once, then sent on every attempt of that create. */
+export declare function newIdempotencyKey(): string;
+/** Budget handed to one long-poll request. Shorter than the 100 s bound so a dead connection,
+ *  a redeploy or a proxy idle-timeout costs one round trip, not the whole wait. */
+export declare const LONG_POLL_MS = 5000;
+interface RequestOpts {
+    method: "GET" | "POST" | "DELETE" | "PUT" | "PATCH";
+    path: string;
+    body?: unknown;
+    idempotencyKey?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Skip the Authorization header (unauthenticated routes). */
+    anonymous?: boolean;
+    /** Called with the response headers of the attempt that answered (not of one that was retried). */
+    onHeaders?: (headers: Headers) => void;
+    /** Extra request headers (e.g. `promigence-replaced-by`). Never the authorization. */
+    headers?: Record<string, string>;
+}
+/** One answer's timing ([`PromigenceClient.lastTiming`]). */
+export interface Timing {
+    method: string;
+    path: string;
+    /** The round trip as the client saw it, in ms, until the answer's headers arrived. */
+    totalMs: number;
+    /** How long the answer took on Promigence's side, in ms; `null` when the service did not say. */
+    ourMs: number | null;
+}
+/** The `app` span of a `Server-Timing` header (`app;dur=12.35`), in ms; `null` without one. */
+export declare function serverAppMs(header: string | null | undefined): number | null;
+export declare class PromigenceClient {
+    #private;
+    readonly apiUrl: string;
+    private readonly fetchImpl;
+    private readonly ownFetch;
+    /** Set when control calls may travel over HTTP/2; each falls back to `fetchImpl` on its own. */
+    private readonly h2;
+    private readonly requestTimeoutMs;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    private readonly userAgent;
+    /** See `PromigenceClientOpts.cliErrors`. */
+    private readonly cliErrors;
+    /**
+     * The framework label this client sends (`promigence-caller`), or `undefined` when nobody set one.
+     * Resolved once, at construction; see `setCaller`.
+     */
+    readonly caller: string | undefined;
+    /** Requests attempted, retries performed — used by tests and `promigence doctor`. */
+    readonly stats: {
+        requests: number;
+        retries: number;
+    };
+    /**
+     * The most recent answer's timing: `totalMs` is the whole round trip as this process saw it,
+     * until the answer's headers arrived; `ourMs` is how long the answer took on Promigence's side
+     * (`null` when the service did not say). `totalMs − ourMs` is the network between you and us.
+     */
+    lastTiming: Timing | null;
+    /** The latest account notice any response carried (`Promigence-Notice`), if one did. */
+    notice: AccountNotice | undefined;
+    private readonly onNotice;
+    private readonly onTiming;
+    private readonly noticesSeen;
+    constructor(opts?: PromigenceClientOpts);
+    /** Read `Promigence-Notice` off a response (its raw value); tell the caller once per distinct notice. */
+    private observeNotice;
+    /** The key this client sends, if one was resolved. Read on purpose; never printed. */
+    get apiKey(): string | undefined;
+    /** True when a key was resolved from opts / env / credentials file. */
+    get authenticated(): boolean;
+    /** What `JSON.stringify` shows: where the client points and whether it has a key — not the key. */
+    toJSON(): {
+        apiUrl: string;
+        authenticated: boolean;
+    };
+    /** What `console.log` / `util.inspect` show: the same as `toJSON`. */
+    [inspect.custom](_depth: number, opts: InspectOptions): string;
+    /**
+     * Why no key was used although one was found: it belongs to another API URL than this
+     * client's, or it holds a character a header cannot carry. `undefined` when the client has a
+     * key, or when none was found at all.
+     */
+    get credentialsProblem(): PromigenceError | undefined;
+    /**
+     * Start connecting to the API now, so the first request does not wait for the connection.
+     *
+     * Never throws and never waits for the network: the one-time TLS setup runs here, and the
+     * address lookup and the handshake go on in the background. Nothing is sent: the first request
+     * is still the next call you make, and it uses this connection when it is ready (or waits for it
+     * to finish opening). Calling it again, or from other clients for the same API, opens nothing
+     * more. An unused connection closes after a few seconds and does not keep the process alive;
+     * the next request then connects as usual. Does nothing where requests do not travel over the
+     * SDK's own connection: an injected `fetch`, `http2: false`, a proxy, or a runtime other than
+     * Node.js.
+     */
+    preconnect(): void;
+    private requireKey;
+    private bearer;
+    /**
+     * How long to wait before sending a refused request again, or `undefined` to give up — the
+     * rule `request()` applies, for the calls that cannot go through it (byte transfers, the
+     * opening of an exec stream, the terminal handshake). Retried: a 429, and a 503 that says
+     * nothing started — any 503 for a request safe to send twice, else only one carrying a
+     * `Retry-After` (every refusal at the door sets one) or a refusal code — and, for a request
+     * safe to send twice, a 502 or 504 that is not the API's own answer (it carries no error
+     * code). At most `maxRetries` times, and never a `Retry-After` longer than
+     * MAX_RETRY_SLEEP_MS: that one is the caller's.
+     */
+    private refusalBackoff;
+    /** A long-poll request must outlive its own `wait_ms`; everything else keeps the default. */
+    private readExtras;
+    private guardDispatcher;
+    private dispatcherFor;
+    request<T>(opts: RequestOpts): Promise<T>;
+    /**
+     * A request whose body — in either direction — is **bytes, not JSON** (`files get|put`).
+     *
+     * `request()` does `await res.text()`, which is exactly the buffering-and-decoding an eval
+     * artefact must not go through: it would corrupt binary and cost a second copy of a file that
+     * can be gigabytes. This reads the body as an `ArrayBuffer` and hands it back untouched.
+     * Errors still arrive as JSON, so a non-2xx answer is decoded and mapped the same way.
+     */
+    private bytes;
+    /**
+     * `GET` a byte body **without holding it**: each chunk goes to `onChunk` as it arrives, and
+     * the next is not read until `onChunk` has finished with it, so a 10 GiB artefact costs one
+     * chunk of memory. Errors arrive
+     * as JSON and are mapped exactly as [`bytes`] maps them; a door refusal is sent again.
+     */
+    private stream;
+    /**
+     * `GET /health` — no key required, which is the point: `promigence doctor` must be able to tell
+     * "the API is down" from "your key is wrong", and a route that needs a key cannot.
+     */
+    health(opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<HealthResponse>;
+    /** `GET /status` — the public service view: the synthetic check window and one row per service. */
+    status(opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<StatusResponse>;
+    /**
+     * `GET /pricing` — your organization's price list, live: the per-second rates, every sandbox
+     * shape on sale and its price (a snapshot build bills at its tier's), the limits, the free credit and the plan they
+     * come from, read on every call from what billing charges. Needs a key: without one this throws
+     * `AuthError` and sends nothing. The published list prices are on the pricing page.
+     *
+     * Prices change: read them when you need them rather than keeping a copy.
+     *
+     * @param opts.newAccount No longer supported: there is no key-less price list. Passing `true`
+     *   throws `InvalidArgumentError` and sends nothing.
+     */
+    pricing(opts?: {
+        newAccount?: boolean;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<PricingView>;
+    /**
+     * The templates: ready-made starting points to fork. Neither call needs a key.
+     * `list()` — every template, each with the snapshot to fork, its version and a count of what it
+     * has installed. `get(name)` — one template with everything it has installed (each package and
+     * tool with its version) and every version with what changed.
+     */
+    readonly templates: {
+        list: (opts?: {
+            signal?: AbortSignal;
+        }) => Promise<M.TemplateSummary[]>;
+        get: (name: string, opts?: {
+            signal?: AbortSignal;
+        }) => Promise<M.TemplateDetail>;
+    };
+    me(opts?: {
+        signal?: AbortSignal;
+    }): Promise<MeResponse>;
+    /**
+     * `GET /me/outcomes?period=month` — what this organization (with a project's key: that project) got
+     * this month, measured from its own runs and sandboxes. A figure with nothing behind it is `null`.
+     */
+    outcomes(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Outcomes>;
+    readonly billing: {
+        /** `GET /billing` — plan, card, period, usage, trial, upcoming invoice. */
+        usage: () => Promise<BillingUsage>;
+        /** `GET /me/ledger?limit=N` — the metered rows the month's total is the sum of (one page). */
+        ledger: (limit?: number) => Promise<LedgerEntry[]>;
+        /**
+         * The same rows with the page kept: feed `nextCursor` back as `cursor` until it is `null`.
+         * A server that issues no cursor answers one page with `nextCursor: null`.
+         */
+        ledgerPage: (opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<LedgerEntry>>;
+        /**
+         * `GET /billing/history` — the credits the organization received and its payments, newest
+         * first (one page). `kind` narrows it to `credits` or `payments`; feed `nextCursor` back as
+         * `cursor` until it is `null`. An owner's key.
+         */
+        historyPage: (opts?: {
+            kind?: BillingHistoryKind;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<BillingHistoryEntry>>;
+        /** `POST /billing/checkout` — the hosted page that puts a card on file. */
+        checkout: () => Promise<{
+            url: string;
+            session_id?: string;
+            expires_at?: string;
+        }>;
+        /** `POST /billing/portal` — the hosted page for an existing card and past invoices. */
+        portal: () => Promise<{
+            url: string;
+        }>;
+        /** `GET /referrals` — your code and its offer, your referrals by status, what they earned. */
+        referrals: () => Promise<ReferralStatus>;
+        /** `POST /referrals/apply` — apply a referral code (an owner's key, before the first paid invoice). */
+        applyReferral: (code: string) => Promise<ReferralApplied>;
+    };
+    /**
+     * This key's API keys. With an API key the list is the key's own project's; `all` includes
+     * revoked ones.
+     */
+    readonly keys: {
+        /** `GET /keys[?all=1]`. */
+        list: (opts?: {
+            all?: boolean;
+        }) => Promise<KeyRecord[]>;
+        /**
+         * `POST /keys` — a new key in this key's project. `api_key` in the answer is the only time
+         * the secret is shown. A key minted by a key is revoked when that key is; a service key
+         * cannot mint.
+         */
+        create: (opts?: {
+            name?: string;
+        } & KeyExpiry) => Promise<KeyRecord>;
+        /**
+         * `DELETE /keys/:id` — revoke a key and every key it minted (`also_revoked` lists them).
+         * Revoking a key in another project needs that project's own key or a signed-in owner.
+         */
+        revoke: (keyId: string) => Promise<KeyRecord>;
+    };
+    /** The organization this key belongs to, its projects, members and pending invites. */
+    readonly orgs: {
+        /** `GET /orgs` — with an API key, the key's own organization. */
+        list: () => Promise<OrgRecord[]>;
+        /** `POST /orgs/:org/default` — make it the organization a sign-in and the CLI use when none is named. */
+        setDefault: (org: string) => Promise<OrgRecord>;
+        /**
+         * `POST /orgs/:org/keys` — mint a key in this key's organization. With an API key the new key
+         * stays in this key's project (`project` may name only that one); a service key, or a key in
+         * another project, needs a signed-in owner.
+         */
+        createKey: (org: string, opts?: {
+            name?: string;
+            project?: string;
+        } & KeyExpiry) => Promise<OrgKeyRecord>;
+        /** `GET /orgs/:org/members` — who belongs and their roles. */
+        members: (org: string) => Promise<MemberRecord[]>;
+        /** `GET /orgs/:org/invites` — invites nobody has accepted yet (gone after 14 days). */
+        invites: (org: string) => Promise<InviteRecord[]>;
+        /**
+         * `DELETE /orgs/:org/members/me` — leave the organization. The keys you minted for yourself
+         * there are revoked; the last owner cannot leave, and nobody can leave their only organization.
+         */
+        leave: (org: string) => Promise<{
+            org_id: string;
+            user_id: string;
+            removed: boolean;
+            keys_revoked: number;
+        }>;
+        projects: {
+            /** `GET /orgs/:org/projects`. */
+            list: (org: string) => Promise<ProjectRecord[]>;
+            /** `POST /orgs/:org/projects` — `name`: 1-40 lowercase letters, digits and dashes; not `default`. */
+            create: (org: string, name: string) => Promise<ProjectRecord>;
+            /** `PATCH /orgs/:org/projects/:project {name}` — rename it (the `default` project keeps its name). */
+            rename: (org: string, project: string, name: string) => Promise<ProjectRecord>;
+        };
+    };
+    readonly credits: {
+        /** `GET /credits/offer` — claimable (how much, until when), claimed, being checked, or none. */
+        offer: () => Promise<CreditOffer>;
+    };
+    /**
+     * The GitHub connection: install the platform's GitHub App once, then build snapshots from the
+     * repositories it can read (`snapshots.create({ repo: "github:owner/name", ref })`).
+     */
+    readonly github: {
+        /** `GET /integrations/github` — connections, installs not confirmed yet, and tracked branches. */
+        status: () => Promise<GithubStatus>;
+        /** `POST /integrations/github/connect` — the install link (15 minutes); open it in a browser. */
+        connect: () => Promise<GithubConnect>;
+        /**
+         * `POST /integrations/github/requests` — a connection started for you in the console: open
+         * `connect_url` in a browser signed in to the console as you (a 404 means the console cannot start
+         * it here: use `connect()`).
+         */
+        ticket: () => Promise<ConnectTicket>;
+        /** `GET /integrations/github/requests/:id` — one of your connection requests: `pending`, or how it ended. */
+        request: (requestId: string) => Promise<ConnectRequest>;
+        /** `DELETE /integrations/github/installations/:id` — nothing is built from that account any more. */
+        disconnect: (installationId: number | string) => Promise<GithubDisconnected>;
+        /** `GET /integrations/github/repos` — one page (at most 100) across every connection. */
+        repos: (opts?: {
+            page?: number;
+            perPage?: number;
+        }) => Promise<GithubRepos>;
+        /** `DELETE /integrations/github/tracks/:id` — the snapshot stays; pushes stop rebuilding it. */
+        untrack: (trackId: string) => Promise<GithubUntracked>;
+    };
+    /**
+     * The GitLab connection: authorize the platform's GitLab application once (read-only), have an
+     * owner confirm it, then build snapshots from the projects it can read
+     * (`snapshots.create({ repo: "gitlab:group/project", ref })`).
+     */
+    readonly gitlab: {
+        /** `GET /integrations/gitlab` — connections, authorizations waiting to be confirmed, tracked branches. */
+        status: () => Promise<GitlabStatus>;
+        /** `POST /integrations/gitlab/connect` — the authorize link (15 minutes); open it in a browser. */
+        connect: () => Promise<GitlabConnect>;
+        /**
+         * `POST /integrations/gitlab/requests` — a connection started for you in the console: open
+         * `connect_url` in a browser signed in to the console as you (a 404 means the console cannot start
+         * it here: use `connect()`).
+         */
+        ticket: () => Promise<ConnectTicket>;
+        /** `GET /integrations/gitlab/requests/:id` — one of your connection requests: `pending`, or how it ended. */
+        request: (requestId: string) => Promise<ConnectRequest>;
+        /** `DELETE /integrations/gitlab/connections/:id` — revoked on GitLab; nothing is built through it any more. */
+        disconnect: (connectionId: string) => Promise<GitlabDisconnected>;
+        /** `GET /integrations/gitlab/repos` — one page (at most 100) of one connection's projects. */
+        repos: (opts?: {
+            page?: number;
+            perPage?: number;
+            connectionId?: string;
+        }) => Promise<GitlabRepos>;
+        /** `DELETE /integrations/gitlab/tracks/:id` — the snapshot stays; new commits stop rebuilding it. */
+        untrack: (trackId: string) => Promise<GitlabUntracked>;
+    };
+    readonly runs: {
+        /** `POST /runs` — returns immediately; sandboxes start `queued`. */
+        start: (opts: RunStartOpts) => Promise<RunStartResponse>;
+        /** `GET /runs/:id`, optionally long-polled with `{ waitMs }`. */
+        get: (runId: string, opts?: ReadOpts) => Promise<RunRecord>;
+        /** `GET /runs?limit=N` — this org's runs, newest first (one page). */
+        list: (limit?: number) => Promise<RunRecord[]>;
+        /** The same route with `nextCursor` kept: feed it back as `cursor` until it is `null`. */
+        listPage: (opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<RunRecord>>;
+        /** Alias of `get`. */
+        status: (runId: string, opts?: ReadOpts) => Promise<RunRecord>;
+        /** `GET /runs/:id/sandboxes` — array or `{sandboxes:[…]}`, normalised. */
+        sandboxes: (runId: string, opts?: ReadOpts) => Promise<SandboxRef[]>;
+        /**
+         * The same read, keeping the `capacity` block the API attaches.
+         *
+         * A server that predates the block answers without it, and this returns `capacity:
+         * undefined` — a client must degrade to the old "queued" rendering rather than showing an
+         * empty progress line.
+         */
+        sandboxesWithCapacity: (runId: string, opts?: ReadOpts) => Promise<{
+            sandboxes: SandboxRef[];
+            capacity?: Capacity;
+        }>;
+        /** `GET /runs/:id/report` — the validity report. */
+        report: (runId: string) => Promise<RunReport>;
+        /** `POST /runs/:id/cancel` — stop queued starts. */
+        cancel: (runId: string) => Promise<unknown>;
+        /** `DELETE /runs/:id` — kill every sandbox of the run. */
+        kill: (runId: string) => Promise<unknown>;
+        /**
+         * `POST /runs/quote` — what the run will cost, before it starts.
+         *
+         * The only pricing promise in the pitch, and it has no side effects: no build, no fork, no
+         * row, no charge. Prices what `runs.start` would charge, at the tier the snapshot was
+         * verified at. `warnings` is the part a caller must not skip — a timeout over 15 minutes is
+         * a multiplier, not an error.
+         */
+        quote: (opts: Pick<RunStartOpts, "snapshot" | "count" | "timeoutMs"> & {
+            tier?: string;
+            spendCap?: number;
+        }) => Promise<RunQuote>;
+        /**
+         * `POST /runs/:id/replay` — re-run the environment failures of a run.
+         *
+         * Only `env_failed` sandboxes are replayable (they are never auto-retried after hand-over;
+         * a replay is a new sandbox, billed like any other), the new rows carry `replay_of`, and they are held out of
+         * `first_attempt_success_pct` / `final_success_pct` and reported under `fork.replay`. A
+         * replay never spends past what is left of `min(quote.max_cost, spend_cap)`. A command that
+         * was started with environment variables needs a value for each again (`opts.env`).
+         */
+        replay: (runId: string, sandboxIds?: string[], opts?: {
+            env?: Record<string, string>;
+        }) => Promise<ReplayResponse>;
+        captures: (runId: string) => Promise<CapturesResponse>;
+        /**
+         * `POST /runs/:id/open` — reopen a failure as a LIVE sandbox, at the moment it broke.
+         *
+         * **Not `replay`.** A replay re-runs the work from the snapshot the run started from; this
+         * forks the state the sandbox was in when it failed — the half-written file, the dead
+         * process, the database mid-migration — and hands it back running. What comes back is a new
+         * sandbox with its own id and its own billing clock, so it costs what a fork costs, and a
+         * finished run whose budget is spent needs a `spendCap` for the reopening.
+         */
+        open: (runId: string, opts?: {
+            sandboxId?: string;
+            spendCap?: number;
+            timeoutMs?: number;
+        }) => Promise<OpenResponse>;
+        /**
+         * Wait until every sandbox of the run has left `queued`.
+         *
+         * Served by the API's `?wait_ms=` long-poll, so a run that is ready is observed when it is
+         * ready rather than on the client's next poll tick. `onReady` fires once per sandbox, in the
+         * order they become ready; because the server parks until *all*
+         * of them are ready, a caller that wants per-sandbox progress caps each park at
+         * `PROGRESS_POLL_MS` so partial readiness still streams at (at least) the old cadence.
+         */
+        waitReady: (runId: string, opts?: WaitOpts & {
+            onReady?: (s: SandboxRef) => void;
+        }) => Promise<WaitReadyResult>;
+        /**
+         * Wait until the run's work is over: the run reached a terminal state, or every sandbox has
+         * ended or outlived its command (`killOnExit: false`, `command_outcome` set). Long-polled.
+         *
+         * A kept sandbox does not end when its command does — it stays live until it is killed or
+         * expires — so waiting for it to END waited out its whole timeout.
+         */
+        waitDone: (runId: string, opts?: WaitOpts) => Promise<WaitRunResult>;
+    };
+    /**
+     * The loop behind `waitReady` / `waitDone`.
+     *
+     * Each iteration hands the API a `wait_ms` budget and lets *it* hold the request until the
+     * state we are blocked on arrives, so the client adds no poll interval of its own to the wait.
+     * A server that ignores `wait_ms` answers immediately without the `promigence-waited-ms` marker;
+     * after two such answers we stop asking and fall back to the adaptive ladder below, which is
+     * also what an explicit `pollMs` selects up front.
+     *
+     * Bounded by `waitTimeoutMs` (default 100 s) exactly as before: on expiry the caller still gets
+     * `timedOut: true` with the last body it saw, and nothing is killed.
+     */
+    private waitLoop;
+    readonly sandboxes: {
+        /** `POST /sandboxes/:id/execs` — foreground exec, inline output up to `maxOutputBytes`. */
+        exec: (sandboxId: string, opts: ExecOpts) => Promise<ExecResponse>;
+        /**
+         * `POST /sandboxes/:id/execs` with `Accept: text/event-stream`.
+         *
+         * Calls `on` for every frame as it arrives and resolves with the same `ExecResponse` shape
+         * the inline form returns, assembled from the stream. Output payloads are base64 because a
+         * chunk boundary lands mid-UTF-8 as often as not; `on.stdout`/`on.stderr` are handed the
+         * decoded bytes so the caller never has to know that.
+         *
+         * Uses `fetch`'s streaming body rather than `res.text()`, which is what `request()` does and
+         * why it cannot be reused here: `await res.text()` is precisely the buffering this removes.
+         */
+        execStream: (sandboxId: string, opts: ExecOpts, on?: {
+            stdout?: (chunk: Uint8Array) => void;
+            stderr?: (chunk: Uint8Array) => void;
+            heartbeat?: () => void;
+        }) => Promise<ExecResponse>;
+        /**
+         * `POST /sandboxes/:id/execs {background: true}` — start a command and return its handle
+         * record immediately. Output is buffered server-side (up to `maxOutputBytes` per stream,
+         * default 1 MiB) and read by range with `execs.read`; `execs.get(…, {waitMs})` parks until
+         * it ends.
+         *
+         * `secrets` are allowed here. Background output is served by byte range, and that range is
+         * masked before it leaves the service, so a credentialed worker can run in the
+         * background instead of holding a foreground stream open for its whole life.
+         */
+        execBackground: (sandboxId: string, opts: Omit<ExecOpts, "terminal" | "killOnExit" | "signal"> & {
+            stdin?: boolean;
+            follow?: boolean;
+        }) => Promise<BackgroundExecRecord>;
+        /** Background execs of one sandbox (`GET|POST|DELETE /sandboxes/:id/execs/:exec_id…`). */
+        execs: {
+            /** Every background exec this sandbox has started and not forgotten, newest first. */
+            list: (sandboxId: string) => Promise<BackgroundExecRecord[]>;
+            /** Status; with `waitMs` the API parks until the exec ends or the wait (≤ 30 s) is spent. */
+            get: (sandboxId: string, execId: string, opts?: {
+                waitMs?: number;
+                signal?: AbortSignal;
+            }) => Promise<BackgroundExecRecord>;
+            /**
+             * One range of one stream. `eof` is true only once the exec has ended **and** the range
+             * reached the end — a reader that has caught up with a running process is not at EOF.
+             */
+            read: (sandboxId: string, execId: string, stream: "stdout" | "stderr", opts?: {
+                offset?: number;
+                len?: number;
+                waitMs?: number;
+                untilOutput?: boolean;
+                signal?: AbortSignal;
+            }) => Promise<{
+                data: Uint8Array;
+                offset: number;
+                eof: boolean;
+                skipped: number;
+                record: BackgroundExecRecord;
+            }>;
+            /**
+             * Write to a running background exec's standard input, and/or close it.
+             *
+             * `data` travels base64 because the point of stdin is usually that it is **not** text: a
+             * JSON string cannot carry an arbitrary byte, and a client that pretended otherwise would
+             * corrupt the first binary payload anyone sent. `{ data, eof: true }` in one call is the
+             * common "write this and close", which is what a process reading to EOF is waiting for.
+             *
+             * Refusals worth branching on: `no_stdin` (started without `stdin: true` — its input is
+             * /dev/null and cannot be opened now) and the usage error for an exec that has already
+             * ended. Neither wrote anything.
+             */
+            stdin: (sandboxId: string, execId: string, opts?: {
+                data?: string | Uint8Array;
+                eof?: boolean;
+            }) => Promise<{
+                ok: boolean;
+                sandbox_id: string;
+                exec_id: string;
+                written: number;
+                eof: boolean;
+            }>;
+            /**
+             * Send a signal (number or name; default SIGTERM). Resolves `delivered: false,
+             * already_ended: true` for an exec that had already ended — the process is gone either way.
+             */
+            signal: (sandboxId: string, execId: string, signal?: number | string) => Promise<{
+                ok: boolean;
+                exec_id: string;
+                signal: number;
+                delivered: boolean;
+                already_ended?: boolean;
+            }>;
+            /** SIGKILL if still running, then drop the handle and its buffered output. */
+            forget: (sandboxId: string, execId: string) => Promise<{
+                ok: boolean;
+                exec_id: string;
+            }>;
+        };
+        /**
+         * Preview URLs for ports inside the sandbox. A URL is a capability — anyone holding it reaches
+         * that port — and dies with `revoke`, with a pause, or with the sandbox.
+         */
+        ports: {
+            expose: (sandboxId: string, port: number) => Promise<PortRecord>;
+            list: (sandboxId: string) => Promise<PortRecord[]>;
+            /** A token revokes that URL; a port number revokes every URL for that port. */
+            revoke: (sandboxId: string, tokenOrPort: string | number) => Promise<{
+                ok: boolean;
+                sandbox_id: string;
+                revoked: string[];
+            }>;
+        };
+        ssh: {
+            /**
+             * `POST /sandboxes/:id/ssh` — authorise an `ssh-ed25519` public key and mint the
+             * short-lived credential its tunnel authenticates with.
+             *
+             * Two credentials come back. `token` is what the tunnel accepts: it reaches this sandbox
+             * only and expires, so it is safe in a `~/.ssh/config`. `host_key` is the sandbox's own,
+             * minted for it and gone with it — pin it rather than turning host verification off.
+             */
+            open: (sandboxId: string, opts: {
+                publicKey: string;
+                ttlS?: number;
+                idleTimeoutS?: number;
+            }) => Promise<SshAccess>;
+            /** `GET /sandboxes/:id/ssh` — the keys this sandbox will accept, and for how long. */
+            list: (sandboxId: string) => Promise<SshAccessList>;
+            /** `DELETE /sandboxes/:id/ssh/:key_id` — by key id or fingerprint. Idempotent. */
+            revoke: (sandboxId: string, keyIdOrFingerprint: string) => Promise<SshRevoked>;
+            /**
+             * `GET /sandboxes/:id/ssh/connect` — the raw tunnel, for a `ProxyCommand`.
+             *
+             * Almost nobody calls this directly: `promigence sandbox ssh <id> --proxy` is what an
+             * `ssh` config points at. It is here because the SDK should be able to do everything the
+             * CLI can.
+             */
+            connect: (sandboxId: string, opts: {
+                token?: string;
+                onData: (data: Uint8Array) => void;
+                onClose: () => void;
+                timeoutMs?: number;
+            }) => Promise<SshTunnel>;
+        };
+        /**
+         * `GET /sandboxes/:id/pty` — an interactive terminal over a WebSocket. Resolves once the
+         * terminal exists. `cmd` defaults to a login shell (`/bin/sh -l`, `TERM=xterm-256color`).
+         */
+        pty: (sandboxId: string, opts?: {
+            cols?: number;
+            rows?: number;
+            cmd?: string;
+            /** Stored secret names, or `{name, as}` bindings, put into the terminal's environment
+             *  by the server. Names travel in a header; values never leave the service. */
+            secrets?: SecretBinding[];
+            onData?: (data: Uint8Array) => void;
+            onExit?: (exit: PtyExit) => void;
+            timeoutMs?: number;
+            /** Pick the same terminal up again when its connection drops or the service is updated;
+             *  see `PtyConnectOpts.resume`. Default: on. */
+            resume?: boolean;
+            /** Reconnect in a new shell when the service is updated (a WebSocket `Close` 1012) and the
+             *  terminal cannot be picked up again; see `PtyConnectOpts.reconnect`. Default: on without
+             *  `cmd`, off with one. */
+            reconnect?: boolean;
+            /** Called after each reconnect: `resumed` says whether it is the same terminal or a new
+             *  shell. */
+            onReconnected?: (how: {
+                resumed: boolean;
+            }) => void;
+        }) => Promise<PtySession>;
+        /** `GET /sandboxes/:id`. */
+        get: (sandboxId: string) => Promise<SandboxRecord>;
+        /**
+         * `POST /sandboxes/:id/pause` — park the sandbox and stop its billing clock.
+         *
+         * Billing: a paused sandbox bills no seconds. The paused interval is subtracted from the
+         * billed span, and both the spend cap's boundary and the sandbox's own `timeoutMs` move with
+         * it, so a sandbox paused overnight is not killed two seconds after it resumes.
+         *
+         * A pause can take seconds on a large, busy sandbox (under a second on a small, quiet one);
+         * this call's timeout allows for it. `took_ms` in the answer is how long it took.
+         *
+         * Files and memory are kept. Background execs end at the pause (`background_execs_killed`
+         * counts them; their ids answer not found after resume); anything else you started keeps
+         * running when the sandbox resumes.
+         */
+        pause: (sandboxId: string) => Promise<PauseResult>;
+        /**
+         * `POST /sandboxes/:id/resume` — bring it back as it was and restart the clock.
+         * `optimizeFor` left out keeps the sandbox's own setting. `spendCap`: for a sandbox paused at
+         * its run's spend cap (`pause_reason: "spend_cap"`), the run's new cap in US dollars, above
+         * the one it reached; the sandbox goes on with what the new cap leaves.
+         */
+        resume: (sandboxId: string, opts?: {
+            optimizeFor?: OptimizeFor;
+            spendCap?: number;
+        }) => Promise<ResumeResult>;
+        /**
+         * `POST /sandboxes/:id/snapshot` — photograph a running sandbox and keep it running.
+         *
+         * Unlike `pause`, this does not end the sandbox: you get back an ordinary snapshot id you
+         * can fork, and the sandbox you called it on carries on. Background processes are ended to
+         * take it, and the count comes back in `background_execs_killed` rather than silently.
+         *
+         * The same ten-minute budget as `pause`: on a large sandbox it can take seconds.
+         *
+         * A sandbox that has been given the value of a secret is refused with `secrets_in_snapshot`
+         * (409): the snapshot, and every sandbox started from it, could contain that value. Pass
+         * `force: true` to take it anyway; the answer then carries a `secrets_in_saved_state`
+         * warning.
+         *
+         * An `alias` another snapshot already has is refused (`usage`, 400) unless `moveAlias: true`
+         * moves it to the new snapshot; the other one stays, unnamed, reachable by id.
+         */
+        snapshot: (sandboxId: string, opts?: {
+            alias?: string;
+            force?: boolean;
+            moveAlias?: boolean;
+        }) => Promise<SandboxSnapshotResult>;
+        /**
+         * `GET /sandboxes?limit=[&labels=][&state=][&cursor=]` — this org's sandboxes, newest run
+         * first, as a plain array.
+         *
+         * `list({ labels: { session: "x" } })` narrows it **on the server**. That is the shape you
+         * want for "find the sandbox for this session, or make one": filtering the array yourself
+         * cannot see past `limit`. `state` is the same deal.
+         *
+         * One page, and the cursor that follows it is dropped. Use [`listPage`] to walk past the
+         * first page; this form stays an array because every existing caller iterates it.
+         *
+         * The number form (`list(100)`) is the original signature and still works.
+         */
+        list: (opts?: number | SandboxListOptions) => Promise<SandboxRecord[]>;
+        /**
+         * The same route with the page kept whole: `{ items, nextCursor, limit }`.
+         *
+         * This used to be impossible to offer — the route issued no cursor, and a paginator over a
+         * single page is a promise that has to be broken later. It issues one now, so the promise is
+         * real: feed `nextCursor` back as `cursor` until it is `null`.
+         */
+        listPage: (opts?: number | SandboxListOptions) => Promise<Page<SandboxRecord>>;
+        /**
+         * `POST /sandboxes/:id/probe` — is this environment still the one that was verified?
+         *
+         * Compares the sandbox's files under the paths its snapshot's verification recorded with what
+         * was recorded. It is the same check a failed run gets, which decides whether the failure was
+         * the environment's (`integrity_mismatch`, not billed) or a path the snapshot's own `verify`
+         * never covered (`verify_did_not_cover`, billed). Asking for it up front is cheaper than
+         * spending a run to find out.
+         *
+         * `first_bad_path` names the **first differing path**, which is the only part of a failed
+         * probe anyone can act on.
+         */
+        probe: (sandboxId: string, opts?: {
+            paths?: string[];
+        }) => Promise<{
+            sandbox_id: string;
+            ok: boolean;
+            ms: number;
+            checked: string | string[];
+            first_bad_path?: string | null;
+        }>;
+        /** `DELETE /sandboxes/:id`. */
+        kill: (sandboxId: string) => Promise<unknown>;
+        /**
+         * `GET /sandboxes/:id/network` — what this sandbox may reach, and every host it asked for
+         * and was refused.
+         *
+         * `refused_hosts` is the field worth reading. A sandbox started with `network: {allow: [...]}`
+         * whose build will not install anything has usually asked for one host nobody thought of;
+         * this names it, with a count, instead of leaving a call to hang.
+         */
+        network: (sandboxId: string) => Promise<SandboxNetwork>;
+        /**
+         * `POST /sandboxes/:id/network {network: "none"}` — cut a running sandbox's egress.
+         *
+         * The pattern this exists for: fork with the network on, install the dependencies, cut egress,
+         * *then* let the agent run. Before this the policy was fixed at fork, so that sequence needed
+         * two sandboxes or a network the agent could still reach.
+         *
+         * One direction. There is no call that turns egress back on — a sandbox whose network can
+         * re-open on request is not one whose egress you can reason about.
+         */
+        setNetworkNone: (sandboxId: string) => Promise<SandboxNetworkCut>;
+        /**
+         * `PATCH /sandboxes/:id` — extend one live sandbox, set its idle rule, or both.
+         *
+         * `timeoutMs` is the **total** lifetime, not an offset from now. It throws
+         * `SpendCapError` (409, exit 5) when the added seconds (× the per-second rate) do not fit in
+         * the cap you set (the run's `spendCap`, or the org's default cap) − charged −
+         * live_commitment, and nothing changes. The launch quote is not a bound.
+         *
+         * `autoPauseS` is how long the sandbox may sit idle before it pauses itself; `0` turns that
+         * off, and the server keeps a floor under the rest (a sandbox that spends more time pausing
+         * than it saves is worse than no rule). A sandbox with a command still running is not idle,
+         * so a long build is never cut short by it.
+         *
+         * `autoPauseMode` says what idle means (`AutoPauseMode`); unset leaves it as it is.
+         *
+         * The two are separate promises and either may be sent alone: the timeout is the bound the
+         * customer committed to spend, the idle rule is what stops them spending it on nothing.
+         */
+        patch: (sandboxId: string, opts: {
+            timeoutMs?: number;
+            autoPauseS?: number;
+            autoPauseMode?: AutoPauseMode;
+        }) => Promise<SandboxPatchResponse>;
+        /**
+         * `get` streams: the body is handed back as bytes and never parsed, because an eval
+         * artefact, a trace or a run log is exactly what this is for. `put` sends the file as the
+         * body rather than base64 inside JSON.
+         */
+        files: {
+            /**
+             * A directory, each entry as `lstat` reports it, in one request. `recursive` walks below it,
+             * `depth` bounds that walk, `hidden: false` drops dotfiles; `truncated` past `limit`
+             * (10,000 by default).
+             */
+            list: (sandboxId: string, path?: string, opts?: DirListOpts) => Promise<DirListing>;
+            /**
+             * Find files by name glob (`pattern`), by literal content (`contains`), or both.
+             *
+             * At least one of the two is required, and that is checked here rather than after a round
+             * trip: a search with neither is a full walk of the tree that answers nothing.
+             */
+            search: (sandboxId: string, path: string, opts?: SearchOpts) => Promise<SearchResult>;
+            /**
+             * `mkdir`. `parents` is `mkdir -p`: the intermediate directories, and no error if it is
+             * already there.
+             */
+            mkdir: (sandboxId: string, path: string, opts?: {
+                mode?: number | string;
+                parents?: boolean;
+            }) => Promise<FileInfo>;
+            /** Rename or move, inside the sandbox. `overwrite` replaces an existing `to`. */
+            move: (sandboxId: string, from: string, to: string, opts?: {
+                overwrite?: boolean;
+            }) => Promise<FileInfo>;
+            /** Copy, inside the sandbox. `recursive` for a directory. */
+            copy: (sandboxId: string, from: string, to: string, opts?: {
+                recursive?: boolean;
+                overwrite?: boolean;
+            }) => Promise<FileInfo>;
+            /**
+             * Mode and/or ownership. At least one of `mode`, `uid`, `gid` is required — a chmod that
+             * changes nothing is a round trip that answers nothing, and the API refuses it.
+             */
+            chmod: (sandboxId: string, path: string, opts: {
+                mode?: number | string;
+                uid?: number;
+                gid?: number;
+                recursive?: boolean;
+            }) => Promise<FileInfo>;
+            /**
+             * Tar a directory **into the sandbox** and answer with the tar's path and size.
+             *
+             * The archive deliberately does not cross the wire here: the transfer is the ordinary
+             * `get`/`put` byte path, which has no size ceiling, and a route that returned the bytes
+             * would have one. `exclude` is a list of name globs (`[".git", "node_modules"]`). The tar
+             * carries the source directory under its own name, so an `extract` of it wants `strip: 1`.
+             */
+            archive: (sandboxId: string, path: string, opts?: {
+                out?: string;
+                exclude?: string[];
+            }) => Promise<ArchiveResult>;
+            /** Unpack a tar that is **already inside** the sandbox. `strip` drops leading path components. */
+            extract: (sandboxId: string, archive: string, into: string, opts?: {
+                strip?: number;
+            }) => Promise<ExtractResult>;
+            stat: (sandboxId: string, path: string) => Promise<{
+                sandbox_id: string;
+                path: string;
+                stat: FileStat;
+            }>;
+            get: (sandboxId: string, path: string, opts?: {
+                signal?: AbortSignal;
+                timeoutMs?: number;
+            }) => Promise<Uint8Array>;
+            /**
+             * `get` without holding the file: every chunk goes to `onChunk` as it arrives (write it to
+             * disk, hash it, pipe it), and the next is read only once `onChunk` resolves. Memory is one
+             * chunk whatever the size. Resolves with the byte count.
+             */
+            download: (sandboxId: string, path: string, onChunk: (chunk: Uint8Array) => void | Promise<void>, opts?: {
+                signal?: AbortSignal;
+                timeoutMs?: number;
+            }) => Promise<{
+                bytes: number;
+            }>;
+            /** `text` is a convenience over `get` for logs and JSON traces. */
+            text: (sandboxId: string, path: string, opts?: {
+                signal?: AbortSignal;
+                timeoutMs?: number;
+            }) => Promise<string>;
+            /**
+             * Write a file of **any size**, in [`FILE_PUT_CHUNK_BYTES`] requests.
+             *
+             * Chunk 0 goes without `?offset=`, which means "this is the file" (create, truncate);
+             * every later chunk carries one, which appends, so a file has no size limit here.
+             *
+             * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file. Re-running the
+             * same `put` is safe: chunk 0 truncates.
+             *
+             * `mode` (`0o755`) sets the file's permission bits. Without it a file that already exists
+             * keeps its mode, as a shell `>` does, and a new one is `0o644`.
+             */
+            put: (sandboxId: string, path: string, data: string | Uint8Array, opts?: {
+                mode?: number;
+                signal?: AbortSignal;
+                timeoutMs?: number;
+            }) => Promise<{
+                ok: boolean;
+                sandbox_id: string;
+                path: string;
+                bytes: number;
+                mode: string;
+                chunks: number;
+            }>;
+            /**
+             * `put` from a source read one chunk at a time — a file on disk of any size, without
+             * holding it (a 2 GiB put was refused and a 1.5 GB one peaked at 3.3 GB RSS).
+             * `read(offset, len)` returns up to `len` bytes at `offset`; `size` is the total.
+             */
+            putFrom: (sandboxId: string, path: string, source: {
+                size: number;
+                read: (offset: number, len: number) => Uint8Array | Promise<Uint8Array>;
+            }, opts?: {
+                mode?: number;
+                signal?: AbortSignal;
+                timeoutMs?: number;
+            }) => Promise<{
+                ok: boolean;
+                sandbox_id: string;
+                path: string;
+                bytes: number;
+                mode: string;
+                chunks: number;
+            }>;
+            delete: (sandboxId: string, path: string, opts?: {
+                recursive?: boolean;
+            }) => Promise<{
+                ok: boolean;
+                path: string;
+                deleted: boolean;
+                existed: boolean;
+            }>;
+        };
+        /**
+         * Output for one `exec_id`, the payload behind `truncated` and `stdout_ref`.
+         *
+         * Resolution: one `GET /execs/:id`, checked against an explicit `sandboxId` or `runId`. A
+         * `runId` used to scan that run's sandboxes one request each: ~28 s for a 100-wide run, and
+         * an exec of an ended sandbox could still be missed.
+         */
+        output: (execId: string, opts?: {
+            sandboxId?: string;
+            runId?: string;
+            range?: {
+                from?: number;
+                to?: number;
+            };
+        }) => Promise<ExecOutput>;
+    };
+    /** Bound helpers for one sandbox (kept from the 0.0.0 shape). */
+    sandbox(id: string): {
+        id: string;
+        exec: (opts: ExecOpts) => Promise<CommandResult>;
+        get: () => Promise<SandboxRecord>;
+        kill: () => Promise<unknown>;
+        pause: () => Promise<PauseResult>;
+        resume: (opts?: {
+            optimizeFor?: OptimizeFor;
+            spendCap?: number;
+        }) => Promise<ResumeResult>;
+        patch: (opts: {
+            timeoutMs?: number;
+            autoPauseS?: number;
+            autoPauseMode?: AutoPauseMode;
+        }) => Promise<SandboxPatchResponse>;
+        files: {
+            get: (path: string) => Promise<Uint8Array<ArrayBufferLike>>;
+            text: (path: string) => Promise<string>;
+            put: (path: string, data: string | Uint8Array, opts?: {
+                mode?: number;
+            }) => Promise<{
+                ok: boolean;
+                sandbox_id: string;
+                path: string;
+                bytes: number;
+                mode: string;
+                chunks: number;
+            }>;
+            stat: (path: string) => Promise<{
+                sandbox_id: string;
+                path: string;
+                stat: FileStat;
+            }>;
+            delete: (path: string) => Promise<{
+                ok: boolean;
+                path: string;
+                deleted: boolean;
+                existed: boolean;
+            }>;
+        };
+        probe: (opts?: {
+            paths?: string[];
+        }) => Promise<{
+            sandbox_id: string;
+            ok: boolean;
+            ms: number;
+            checked: string | string[];
+            first_bad_path?: string | null;
+        }>;
+    };
+    /**
+     * Org-scoped secrets. The value is **write-only**: nothing in this namespace —
+     * or in the API behind it — hands one back. `list` returns names and byte counts so a caller
+     * can tell "is this the key I meant" without being able to read it.
+     *
+     * Names are validated here rather than at the server: an environment variable that cannot
+     * exist is a client-side mistake, and finding out after a round trip helps nobody.
+     */
+    readonly secrets: {
+        set: (name: string, value: string, opts?: SecretSetOpts) => Promise<SecretRecord>;
+        list: () => Promise<{
+            secrets: SecretRecord[];
+        }>;
+        delete: (name: string) => Promise<{
+            name: string;
+            deleted: boolean;
+        }>;
+    };
+    /**
+     * Container images, as far as we need to know about them: what digest does this tag name?
+     */
+    readonly images: {
+        /**
+         * `POST /images/resolve` — `python:3.12` → `python@sha256:…`, resolved **by the server**.
+         *
+         * You need no container runtime on this machine to call it. That is the entire point:
+         * `snapshots.create({ image })` takes a digest, and the only way to get one used to be
+         * `docker buildx imagetools inspect` locally — a Docker install demanded of somebody who is
+         * renting sandboxes so as not to need one.
+         *
+         * `image` in the answer is the pinned reference to pass straight to `snapshots.create`. For
+         * a multi-arch tag it carries the **index** digest, which is what a pull of that tag
+         * fetches; `platform_digest` names the `linux/amd64` child beside it, and a tag with no
+         * `linux/amd64` build is refused here rather than at build time.
+         *
+         * An already-pinned reference is returned unchanged without a registry call, so this is
+         * safe to call unconditionally.
+         *
+         * `registrySecret` names a stored secret (`secrets.set`) holding `user:password` for a
+         * private registry.
+         */
+        resolve: (image: string, opts?: {
+            registrySecret?: string;
+        }) => Promise<ResolvedImage>;
+    };
+    readonly captures: {
+        /**
+         * `DELETE /captures/:snapshot_id` — destroy a preserved failure now, before it expires.
+         *
+         * The bytes go; `bytes` is what was freed. A customer must be able to destroy
+         * their own forensics on demand and be told what was destroyed.
+         */
+        delete: (snapshotId: string) => Promise<{
+            ok: boolean;
+            snapshot_id: string;
+            deleted: boolean;
+            bytes: number;
+            deleted_at: string;
+        }>;
+    };
+    readonly snapshots: {
+        /**
+         * `POST /snapshots` — 202 with a `build_id`, or 200 with the existing snapshot when an
+         * identical build already ran. Nothing is built synchronously: a build is
+         * minutes, so the caller polls `status` (or `waitBuild`).
+         */
+        create: (opts: SnapshotCreateOpts) => Promise<SnapshotBuild>;
+        /** `GET /snapshots/builds/:build_id`, optionally long-polled with `{ waitMs }`. */
+        status: (buildId: string, opts?: ReadOpts) => Promise<SnapshotBuild>;
+        /** `GET /snapshots/builds/:build_id/build-log` — the build log, tail first. */
+        buildLog: (buildId: string, tail?: number) => Promise<string[]>;
+        /**
+         * `GET /snapshots/builds?limit=N` — the build history, newest first.
+         *
+         * A build that was rejected keeps its row and its reason, so this is the list you go to after a build
+         * that produced nothing.
+         */
+        builds: (limit?: number) => Promise<SnapshotBuild[]>;
+        /** The same route with `nextCursor` kept: feed it back as `cursor` until it is `null`. */
+        buildsPage: (opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<SnapshotBuild>>;
+        /** `GET /snapshots/:id` — `snap_<id>` | `<alias>` | `<alias>@<commit7>`. */
+        get: (idOrAlias: string) => Promise<SnapshotRecord>;
+        /** `GET /snapshots` — this org's snapshots plus every public one (public needs no key). */
+        list: (opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<SnapshotRecord[]>;
+        /** The same route with `nextCursor` kept: feed it back as `cursor` until it is `null`. */
+        listPage: (opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<SnapshotRecord>>;
+        /**
+         * `GET /snapshots` with **no** Authorization header — the list an agent with no key sees,
+         * which is exactly what `promigence examples` must show. Filtered to `visibility: "public"`
+         * because a server that answers the anonymous call with more than that is misconfigured and
+         * the CLI should not repeat its mistake.
+         */
+        public: (limit?: number) => Promise<SnapshotRecord[]>;
+        /**
+         * `DELETE /snapshots/:id` — take one of your own snapshots out of the catalogue.
+         *
+         * The snapshot leaves your catalogue at once; the space it used is reclaimed later.
+         * Finished runs keep their reports. Refused (`usage`) while a sandbox forked from it is
+         * still alive — kill those first.
+         */
+        delete: (idOrAlias: string) => Promise<{
+            snapshot_id: string;
+            alias?: string | null;
+            deleted: boolean;
+        }>;
+        /** `PUT /snapshots/:id/alias` — the sidecar's one mutable field. */
+        alias: (idOrAlias: string, alias: string | null) => Promise<SnapshotRecord>;
+        /**
+         * Wait for a build to leave `running`, bounded by `waitTimeoutMs` (default 100 s).
+         *
+         * `timedOut: true` means exactly that and nothing else: the build is untouched and still
+         * running — come back with `status(buildId)`.
+         */
+        waitBuild: (buildId: string, opts?: WaitOpts) => Promise<{
+            build: SnapshotBuild;
+            timedOut: boolean;
+            waitedMs: number;
+        }>;
+        /**
+         * `POST /snapshots/:id/verify` — re-run the snapshot's recorded `verify` in a fresh fork.
+         *
+         * stores a snapshot only if its `verify` passed on the machine that built it; this asks
+         * whether that is still true — after a move, after a month, before
+         * trusting a number that came out of it. It is an ordinary one-sandbox run, so it goes
+         * through the same report and the same ledger, and bills per second at the snapshot's tier, at most
+         * `price` (in the reply, to print before waiting like `build_price`).
+         */
+        verify: (id: string, opts?: {
+            timeoutMs?: number;
+            spendCap?: number;
+        }) => Promise<SnapshotVerifyResponse>;
+        /** `GET /snapshots/:id/manifest` — the snapshot's sealed manifest and what can be verified of it. */
+        manifest: (idOrAlias: string) => Promise<SnapshotManifestResponse>;
+        /**
+         * The `.promigence` bundle for a snapshot: the sealed form, which names exactly one
+         * environment and verifies offline (`verifyBundle`). This client composes it from the
+         * snapshot's sealed manifest (`served_by: "client"`); the API serves no bundle of its own.
+         */
+        bundle: (idOrAlias: string, opts?: {
+            alias?: string;
+        }) => Promise<{
+            bundle: Bundle;
+            served_by: "client";
+            record?: SnapshotRecord;
+        }>;
+    };
+}
+export declare function toCommandResult(r: ExecResponse): CommandResult;