promigence 0.1.0-beta.8 → 0.1.0-beta.9

package/README.md

@@ -62,6 +62,12 @@ Every command takes `--json`.
 
 ## From TypeScript
 
+In your project (the global install gives you the command only):
+
+```sh
+npm i promigence
+```
+
 ```ts
 import { Sandbox } from "promigence";
 

package/dist/commands.d.ts

@@ -1,5 +1,6 @@
-import { PromigenceClient, type ExecResponse, type OptimizeFor, type RunReport, type SandboxRef, type ScoreMode, type SecretRecord } from "./sdk/index.js";
+import { PromigenceClient, type ExecResponse, type OptimizeFor, type RunReport, type SandboxRef, type ScoreMode, type SecretRecord, type SnapshotBuild } from "./sdk/index.js";
 import { type Mode } from "./io.js";
+import { type BuildPrice } from "./pricing.js";
 import { type Command, type NextHint } from "./surface.js";
 export interface Ctx {
     cmd: Command;
@@ -46,6 +47,7 @@ export declare function gradeOpts(ctx: Ctx): {
     score?: ScoreMode;
 } | undefined;
 export declare function secretListLines(s: SecretRecord): string[];
+export declare function buildPriceOf(b: SnapshotBuild): BuildPrice | undefined;
 export declare function verifyTiming(v: Record<string, unknown> | undefined): string | undefined;
 export declare function buildLogLines(log: string[] | undefined, state: string): string[];
 export declare function snapshotSource(s: {

package/dist/commands.js

@@ -10,7 +10,7 @@ import { DevcontainerError, detectOne, load, planJson, planLines, planSetup, res
 import { detect, ecosystemOfCommands, imageCreateCommand, readConfig } from "./init.js";
 import { CREDENTIAL_REMEDY, confirmOverride, credentialRefusal, emitUploadList, localTarNoMetadataArgs } from "./uploadguard.js";
 import { emit, errorEnvelope, errorTextLines, exitWith, forkLine, forkSummary, gradeLine, ms, noCommandFix, okEnvelope, parseMaxOutput, recordNotice, sandboxGrade, parseCommandTimeout, parseCount, parseDuration, parseUsd, pickExit, reportSummaryLines, toPromigenceError, totalsLine, usageError, write, writeBytes, } from "./io.js";
-import { buildPrice } from "./pricing.js";
+import { buildPrice, buildPriceWords } from "./pricing.js";
 import { DOCS_URL, WAIT_TIMEOUT_DEFAULT } from "./surface.js";
 import { escapeLine, fieldForTerminal, forTerminal, jsonLine, sh, shellArg } from "./term.js";
 import { snapshotArg } from "./bundle.js";
@@ -430,6 +430,10 @@ function buildFields(b) {
         out["source"] = b.source;
     if (typeof b.verified === "boolean")
         out["verified"] = b.verified;
+    for (const k of ["build_price", "per_second_usd", "max_seconds", "billable_seconds", "cost_usd"]) {
+        if (typeof b[k] === "number")
+            out[k] = b[k];
+    }
     const ab = b;
     if (ab.alias_requested !== undefined)
         out["alias_requested"] = ab.alias_requested;
@@ -440,6 +444,11 @@ function buildFields(b) {
 function isBuilding(b) {
     return b.state === "queued" || b.state === "running";
 }
+export function buildPriceOf(b) {
+    return typeof b.build_price === "number" && typeof b.per_second_usd === "number" && typeof b.max_seconds === "number"
+        ? { most_usd: b.build_price, per_second_usd: b.per_second_usd, max_s: b.max_seconds }
+        : undefined;
+}
 function buildExit(b) {
     if (b.state === "verified" || b.state === "built")
         return 0;
@@ -474,9 +483,15 @@ function buildLines(b) {
     const timing = verifyTiming(b.verification);
     if (timing)
         lines.push(`  verify: ${timing}`);
+    const cost = typeof b.cost_usd === "number" && !isBuilding(b) ? b.cost_usd : undefined;
+    const ran = typeof b.billable_seconds === "number" ? ` for the ${b.billable_seconds} s it ran` : "";
     if (b.error) {
         lines.push(`  ${b.error.guard ? `guard ${b.error.guard}: ` : ""}${b.error.message ?? b.error.code ?? "rejected"}`);
-        lines.push(`  nothing was stored${b.error.stored === false ? "" : "?"} and nothing was charged`);
+        const stored = `nothing was stored${b.error.stored === false ? "" : "?"}`;
+        lines.push(cost !== undefined && cost > 0 ? `  ${stored}; billed ${usd(cost)}${ran}` : `  ${stored} and nothing was charged`);
+    }
+    else if (cost !== undefined && cost > 0) {
+        lines.push(`  billed ${usd(cost)}${ran}`);
     }
     for (const w of b.warnings ?? [])
         lines.push(`  warning: ${w}`);
@@ -875,14 +890,22 @@ const snapshotCreate = async (ctx) => {
     const reused = started.deduped === true;
     const joinedBuild = started.joined === true;
     const replay = buildReplayNote(started, str(ctx, "--idempotency-key") !== undefined);
-    const charged = reused || joinedBuild || replay !== undefined ? 0 : (typeof started.build_price === "number" ? started.build_price : await buildPrice(c));
+    const free = reused || joinedBuild || replay !== undefined;
+    const builtAt = tier ?? (typeof started["tier"] === "string" ? started["tier"] : undefined);
+    const perSecond = buildPriceOf(started);
+    const flat = !free && perSecond === undefined && typeof started.build_price === "number" ? started.build_price : undefined;
+    const said = free || flat !== undefined ? perSecond : (perSecond ?? await buildPrice(c, builtAt));
+    const charged = free ? 0 : flat ?? said?.most_usd ?? 0;
     submitted["build_price"] = charged;
-    if (reused || joinedBuild || replay !== undefined)
+    if (!free && said !== undefined)
+        Object.assign(submitted, { per_second_usd: said.per_second_usd, max_seconds: said.max_s });
+    if (free)
         submitted["charged"] = false;
     Object.assign(submitted, replayFields(started));
     await write(process.stderr, ctx.mode === "json"
         ? JSON.stringify({
             hint: "build_price", build_price: charged, unit: "USD", ...(tier === undefined ? {} : { tier }),
+            ...(!free && said !== undefined ? { per_second_usd: said.per_second_usd, max_seconds: said.max_s } : {}),
             ...(reused ? { deduped: true } : {}), ...(joinedBuild ? { joined: true } : {}),
             ...(replay === undefined ? {} : { replayed: true }),
         }) + "\n"
@@ -892,7 +915,9 @@ const snapshotCreate = async (ctx) => {
                 ? `build_price: $0.00 - an identical build already ran (${started.build_id}); reusing it, nothing charged\n`
                 : joinedBuild
                     ? `build_price: $0.00 - joining an identical build already running (${started.build_id}); it is charged once\n`
-                    : `build_price: $${charged.toFixed(2)} (tier ${tier ?? "default"}) - building ${label}\n`);
+                    : flat !== undefined
+                        ? `build_price: $${flat.toFixed(2)} (tier ${tier ?? "default"}) - building ${label}\n`
+                        : `build_price: ${buildPriceWords(said, builtAt ?? "default")} - building ${label}\n`);
     if (sources.length && ctx.mode !== "json" && !reused) {
         await write(process.stderr, sources
             .map((s) => `  also      ${s.repo}@${s.commit.slice(0, 7)} -> ${s.path ?? "beside the workspace, under its own name"}`)
@@ -920,7 +945,7 @@ const snapshotCreate = async (ctx) => {
         const follow = sh `promigence snapshot status ${started.build_id} --wait`;
         const err = new PromigenceError({
             code: "aborted_by_client",
-            message: `interrupted by ${sig}; build ${started.build_id} goes on and nothing was cancelled (it is charged once it verifies)`,
+            message: `interrupted by ${sig}; build ${started.build_id} goes on and nothing was cancelled (it is billed per second until it ends)`,
             fix: `Follow it: ${follow}.`,
             exitCode: 130,
         });
@@ -1587,7 +1612,8 @@ async function runImageSnapshot(ctx, c) {
     checkImageRef(image);
     const count = parseCount(required(ctx, "--count", "Pass --count N (number of sandboxes to fork)."), "--count");
     const cap = await spendCap(ctx, c);
-    const price = await buildPrice(c);
+    const most = await buildPrice(c);
+    const price = most.most_usd;
     const timeout = str(ctx, "--timeout");
     const quoted = await c.runs.quote({
         snapshot: DEFAULT_SNAPSHOT, count, ...(timeout === undefined ? {} : { timeoutMs: parseDuration(timeout, "--timeout") }),
@@ -1595,29 +1621,43 @@ async function runImageSnapshot(ctx, c) {
     const needed = Math.ceil((price + (quoted ?? 0)) * 100) / 100;
     if (cap < price + (quoted ?? 0)) {
         const existing = (quoted ?? 0) <= cap ? await existingImageSnapshot(c, image) : undefined;
-        throw new SpendCapError(`a new image's snapshot build costs ${moneyUsd(price)} on top of the run` +
+        throw new SpendCapError(`a new image's snapshot build can cost up to ${moneyUsd(price)} on top of the run` +
             `${quoted === undefined ? "" : ` (about ${moneyUsd(quoted)})`}, over --cap ${moneyUsd(cap)}; nothing was built or started`, (existing === undefined ? "" : `This image already has snapshot ${existing}: run it under this cap with ${sh `promigence run --snapshot ${existing}`} instead of --image (any start command or settings it was made with come with it). Or `) +
-            `${existing === undefined ? "Pass" : "pass"} --cap ${needed.toFixed(2)} or more (a build is charged once, only when this image has no snapshot yet, and reused free after), ` +
+            `${existing === undefined ? "Pass" : "pass"} --cap ${needed.toFixed(2)} or more (a build is billed per second while it runs, only when this image has no snapshot yet, and reused free after), ` +
             `or build it first, ${sh `promigence snapshot create --image ${image} --wait`}, and run its snapshot with --snapshot.`);
     }
     await write(process.stderr, ctx.mode === "json"
         ? jsonLine(process.stderr, { hint: "image snapshot", image })
         : `image ${image}: creating or reusing its snapshot (a first build takes minutes)\n`);
     let charged = 0;
+    let perSecond = false;
     let buildId;
     const buildOpts = { image, allowBuild: true };
     const snapshotId = await imageSnapshot(c, buildOpts, {
         onBuild: async (b) => {
             const free = b.deduped === true || b.joined === true || b.idempotent_replay === true || b.state === "verified" || b.state === "built";
+            const said = buildPriceOf(b);
+            perSecond = !free && said !== undefined;
             charged = free ? 0 : (typeof b.build_price === "number" ? b.build_price : price);
             buildId = b.build_id;
             await write(process.stderr, ctx.mode === "json"
-                ? jsonLine(process.stderr, { hint: "build_price", build_price: charged, unit: "USD", image, ...(b.build_id ? { build_id: b.build_id } : {}), ...(free ? { charged: false } : {}) })
+                ? jsonLine(process.stderr, {
+                    hint: "build_price", build_price: charged, unit: "USD", image,
+                    ...(perSecond && said ? { per_second_usd: said.per_second_usd, max_seconds: said.max_s } : {}),
+                    ...(b.build_id ? { build_id: b.build_id } : {}), ...(free ? { charged: false } : {}),
+                })
                 : free
                     ? `build_price: $0.00 - this image's snapshot already exists; reusing it, nothing charged\n`
-                    : `build_price: $${charged.toFixed(2)} - building ${image}'s snapshot (charged once it verifies; counted in --cap)\n`);
+                    : perSecond && said
+                        ? `build_price: ${buildPriceWords(said)} - building ${image}'s snapshot (billed per second while it builds; counted in --cap)\n`
+                        : `build_price: $${charged.toFixed(2)} - building ${image}'s snapshot (charged once it verifies; counted in --cap)\n`);
         },
     });
+    if (perSecond && buildId !== undefined) {
+        const done = await c.snapshots.status(buildId).catch(() => undefined);
+        if (done !== undefined && typeof done.cost_usd === "number" && !isBuilding(done))
+            charged = done.cost_usd;
+    }
     await write(process.stderr, ctx.mode === "json"
         ? jsonLine(process.stderr, { hint: "image snapshot ready", image, snapshot_id: snapshotId })
         : fieldForTerminal(process.stderr, `image ${image}: snapshot ${snapshotId}`) + "\n");

package/dist/generated.d.ts

@@ -20,7 +20,7 @@ export interface TierEntry {
     per_second_usd: number;
 }
 export declare const TIERS: readonly TierEntry[];
-export declare const BUILD_PRICE = 1;
+export declare const BUILD_MAX_S = 3600;
 export declare const PRICING: {
     readonly vcpu_second_usd: 0.000014;
     readonly gib_second_usd: 0.0000045;

package/dist/generated.js

@@ -158,12 +158,12 @@ export const ERRORS = [
     { code: "capacity_limit", category: "env", http: 409, exit: 3, billed: "no",
         message: "{requested} {tier} sandboxes at once is more than one run can start at once; at most {max_at_once}",
         fix: "Not billed; nothing started. Run at most {max_at_once} at once (lower `--count`), or use a smaller tier." },
-    { code: "build_timeout", category: "other", http: 422, exit: 4, billed: "no",
+    { code: "build_timeout", category: "other", http: 422, exit: 4, billed: "yes",
         message: "the build ran past its {limit_min}-minute limit",
-        fix: "Not billed; nothing stored. Shorten `setup` (at most 64 steps, {limit_min} minutes in all) or bake the slow part into the image." },
-    { code: "dockerfile_build_failed", category: "other", http: 400, exit: 2, billed: "no",
+        fix: "Nothing was stored; the {limit_min} minutes it ran are billed. Shorten `setup` (at most 64 steps, {limit_min} minutes in all) or bake the slow part into the image." },
+    { code: "dockerfile_build_failed", category: "other", http: 400, exit: 2, billed: "yes",
         message: "your image could not be built from the Dockerfile: {detail}",
-        fix: "Nothing was stored and nothing was billed. Fix the Dockerfile (the lines above are the end of your own build output) and run `promigence snapshot create --dockerfile PATH ...` again." },
+        fix: "Nothing was stored; the time the build ran is billed. Fix the Dockerfile (the lines above are the end of your own build output) and run `promigence snapshot create --dockerfile PATH ...` again." },
     { code: "image_unresolvable", category: "other", http: 422, exit: 2, billed: "no",
         message: "`{image}` could not be resolved to a digest: {detail}",
         fix: "Nothing was stored and nothing was billed. Check the name and tag; a private image needs `registry_secret` naming a stored secret that holds `user:password` (`promigence secrets set`). You can also pass the image already pinned as NAME@sha256:<digest>." },
@@ -263,9 +263,9 @@ export const CLIENT_ERRORS = [
     { code: "env_failed", category: "env", http: 0, exit: 3, billed: "no",
         message: "the sandbox ended before hand-over",
         fix: "Ours, not billed. The run's report names the failure's own code (`promigence run report RUN`); start the sandbox again." },
-    { code: "snapshot_rejected", category: "other", http: 0, exit: 6, billed: "no",
+    { code: "snapshot_rejected", category: "other", http: 0, exit: 6, billed: "unless_ours",
         message: "a build guard refused it; nothing was stored",
-        fix: "Not charged. Read the build log (`promigence snapshot status BUILD --log 80`): the guard named in the error says what to change (verify exited non-zero, a setup step failed, a time or size bound), then build again." },
+        fix: "The time the build ran is billed, unless it ended on our side. Read the build log (`promigence snapshot status BUILD --log 80`): the guard named in the error says what to change (verify exited non-zero, a setup step failed, a time or size bound), then build again." },
     { code: "build_failed", category: "env", http: 0, exit: 3, billed: "no",
         message: "the build could not finish; nothing was stored",
         fix: "Not charged. Build again; if it repeats, email support@promigence.ai with the build id." },
@@ -291,7 +291,7 @@ export const TIERS = [
     { name: "bench-8x16", vcpus: 8, mem_gib: 16, disk_gib: 20, sellable: false, per_second_usd: 0 },
     { name: "bench-4x8", vcpus: 4, mem_gib: 8, disk_gib: 40, sellable: false, per_second_usd: 0 },
 ];
-export const BUILD_PRICE = 1;
+export const BUILD_MAX_S = 3600;
 export const PRICING = {
     vcpu_second_usd: 0.000014,
     gib_second_usd: 0.0000045,

package/dist/github.js

@@ -119,7 +119,7 @@ const githubStatus = async (ctx) => {
         lines.push("pending:", ...s.pending.map((p) => `  installation ${p.installation_id}${p.account ? ` (${p.account})` : ""}: ${p.message}`));
     }
     if (s.tracks.length)
-        lines.push("tracked branches (each push rebuilds, at the build price):", ...s.tracks.map(trackLine));
+        lines.push("tracked branches (each push rebuilds, billed per second):", ...s.tracks.map(trackLine));
     const next = s.connections.length
         ? nexts(["promigence repos", "the repositories the connection can read"])
         : nexts(["promigence github connect", "install the App on your GitHub account"]);
@@ -289,12 +289,12 @@ export async function githubCreate(ctx) {
     };
     if (track) {
         const branch = ref ?? "the default branch";
-        const each = await buildPrice(client(ctx));
+        const each = (await buildPrice(client(ctx), tier)).most_usd;
         await write(process.stderr, ctx.mode === "json"
             ? jsonLine(process.stderr, { hint: "track", repo, branch, alias, build_price_each: each, unit: "USD" })
             : glPath
-                ? `tracking: every new commit on ${branch} (checked every minute) rebuilds this snapshot and moves ${alias} to it, at the build price ($${each.toFixed(2)} per build), charged to your org; stop with \`${sh `promigence gitlab untrack ${alias}`}\`\n`
-                : `tracking: every push to ${branch} rebuilds this snapshot and moves ${alias} to it, at the build price ($${each.toFixed(2)} per build), charged to your org; stop with \`${sh `promigence github untrack ${alias}`}\`\n`);
+                ? `tracking: every new commit on ${branch} (checked every minute) rebuilds this snapshot and moves ${alias} to it, each build billed per second while it runs (up to $${each.toFixed(2)}), charged to your org; stop with \`${sh `promigence gitlab untrack ${alias}`}\`\n`
+                : `tracking: every push to ${branch} rebuilds this snapshot and moves ${alias} to it, each build billed per second while it runs (up to $${each.toFixed(2)}), charged to your org; stop with \`${sh `promigence github untrack ${alias}`}\`\n`);
     }
     return { opts, label, submitted, tier };
 }

package/dist/gitlab.js

@@ -120,7 +120,7 @@ const gitlabStatus = async (ctx) => {
         lines.push("waiting for an owner's confirmation:", ...s.pending.map((p) => `  ${p.username} (${p.connection_id}): ${p.message}`));
     }
     if (s.tracks.length) {
-        lines.push("tracked branches (each new commit rebuilds, at the build price; checked every minute):", ...s.tracks.map(trackLine));
+        lines.push("tracked branches (each new commit rebuilds, billed per second; checked every minute):", ...s.tracks.map(trackLine));
     }
     if (s.connections.length) {
         lines.push("optional, for instant rebuilds: a project webhook (push events) with each connection's URL and token in --json (webhook_url, webhook_token)");

package/dist/guide.js

@@ -1,4 +1,4 @@
-import { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_PRICE, PRICING, } from "./generated.js";
+import { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_MAX_S, PRICING, } from "./generated.js";
 export const BILLED_TEXT = {
     no: "no: nothing is billed for this",
     yes: "yes: the time used is billed",
@@ -55,7 +55,7 @@ function renderCore() {
         "    verify → snapshot → fork(N) → exec → validity report",
         "",
         "- **snapshot** — an image (pinned) + ordered `setup` steps + a `verify` command that, if given, must exit 0.",
-        "  If verify fails nothing is stored and nothing is charged. A branch is not a pin.",
+        "  If verify fails nothing is stored; the build's own time is billed. A branch is not a pin.",
         "- **fork** — a warm copy of that workspace, with its `start` service ready;",
         "  N at once, each checked before you get it.",
         "- **validity report** — per sandbox, and this split is the product: **env** failures are ours",
@@ -245,7 +245,8 @@ function renderCost(prices) {
     const vcpu = prices?.vcpu_second_usd ?? PRICING.vcpu_second_usd;
     const gib = prices?.gib_second_usd ?? PRICING.gib_second_usd;
     const granularity = prices?.granularity_seconds ?? PRICING.granularity_seconds;
-    const build = prices?.build_usd ?? BUILD_PRICE;
+    const buildMax = prices?.build_max_s ?? BUILD_MAX_S;
+    const buildHours = buildMax % 3600 === 0 ? `${buildMax / 3600} h` : `${Math.ceil(buildMax / 60)} min`;
     const view = prices?.view;
     const source = prices === undefined
         ? "List prices when this CLI was built. Live, and your plan's: `promigence pricing`."
@@ -269,8 +270,10 @@ function renderCost(prices) {
         ...tiers.map((t) => `| \`${t.name}\` | ${t.vcpus} | ${t.mem_gib} GiB | ${t.disk_gib} GiB | $${t.per_second_usd} | ${perHour(t.per_second_usd)} |`),
         ...(typeof limit === "number" ? ["", `Your plan runs sandboxes of up to ${limit} vCPU.`] : []),
         "",
-        `Building a snapshot costs $${build.toFixed(2)} once, printed on stderr **before** the build starts.`,
-        "A build that fails `verify` or a guard stores nothing and is not charged.",
+        `Building a snapshot bills per second at its tier's rate while it runs, at most ${buildHours} (the most it can`,
+        "cost is printed on stderr **before** the build starts; what it cost, when it ends). A build that",
+        "fails `verify` or a guard stores nothing and is billed the time it ran; one that fails on our",
+        "side is not billed, and reusing an identical build is free.",
         "",
         "`env` failures (`promigence agent-guide --section errors`): one before hand-over is not billed,",
         "e.g. " + ERRORS.filter((e) => e.category === "env").slice(0, 3).map((e) => `\`${e.code}\``).join(", ") + ". After hand-over, a failure our",

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { SCHEMA, GUIDE_POINTER, GOLDEN_PATH, COMMANDS, LISTED_COMMANDS, GROUPS,
 export { ALL_ERROR_CODES, BILLED_TEXT, BUDGETS, SECTIONS, estimateTokens, guideJson, lookupError, renderGuide, renderLlmsTxt, 
 renderGuide as renderAgentGuide, } from "./guide.js";
 export type { Section } from "./guide.js";
-export { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_PRICE, PRICING } from "./generated.js";
+export { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_MAX_S, PRICING } from "./generated.js";
 export type { ErrorEntry, TierEntry } from "./generated.js";
 export { FENCE_BEGIN, FENCE_END, FENCE_MAX_LINES, fenceBody, install, spliceFence } from "./install.js";
 export type { Artifact, InstallResult } from "./install.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export * from "./sdk/index.js";
 export { SCHEMA, GUIDE_POINTER, GOLDEN_PATH, COMMANDS, LISTED_COMMANDS, GROUPS, GLOBAL_FLAGS, EXIT_CODES, LIVE_COMMANDS, LIVE_SUMMARY, NOT_LIVE_SUMMARY, STATUS_LINE, DESCRIPTION, compactNames, EXIT_PRECEDENCE, EXIT_PRECEDENCE_TEXT, OUTPUT_MODE_PRECEDENCE, WAIT_TIMEOUT_DEFAULT, REQUEST_TIMEOUT_DEFAULT, GUIDE_COMMON_ERRORS, findCommand, knownFlags, nearestFlag, unknownFlags, renderHelp, renderCommandHelp, signInLine, notReleasedEnvelope, notReleasedLines, } from "./surface.js";
 export { ALL_ERROR_CODES, BILLED_TEXT, BUDGETS, SECTIONS, estimateTokens, guideJson, lookupError, renderGuide, renderLlmsTxt, renderGuide as renderAgentGuide, } from "./guide.js";
-export { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_PRICE, PRICING } from "./generated.js";
+export { CLIENT_ERRORS, CLIENT_ERROR_BY_CODE, ERRORS, ERROR_BY_CODE, TIERS, BUILD_MAX_S, PRICING } from "./generated.js";
 export { FENCE_BEGIN, FENCE_END, FENCE_MAX_LINES, fenceBody, install, spliceFence } from "./install.js";
 export { detect, gitFacts, normalizeRemote, readConfig, renderConfig, stripRemoteCredentials } from "./init.js";
 export { DEVCONTAINER_NAMES, DEVCONTAINER_SPEC, DevcontainerError, detectOne, discover, load, parseJsonc, planJson, planLines, planSetup, resolveGiven, shellQuote, snapshotEnv, snapshotUsers, substituteString, translate, workspaceRootFor, wrapCommand, } from "./devcontainer.js";

package/dist/init.js

@@ -344,7 +344,7 @@ export function renderConfig(c, notes = [], build) {
     ];
     if (c.alias)
         lines.push(`alias = ${tomlString(c.alias)}`);
-    lines.push("", "# Ordered; each must exit 0.", `setup = ${tomlArray(c.setup)}`, "", "# The command that decides whether the snapshot exists at all. If it does not exit 0,", "# nothing is stored and nothing is charged.", `verify = ${tomlString(c.verify)}`, "", "[guards]", "# Checked by the builder before anything is stored. A failed guard names itself.", `toolchain_present = ${tomlArray(c.toolchain)}`);
+    lines.push("", "# Ordered; each must exit 0.", `setup = ${tomlArray(c.setup)}`, "", "# The command that decides whether the snapshot exists at all. If it does not exit 0,", "# nothing is stored (the build's time is billed).", `verify = ${tomlString(c.verify)}`, "", "[guards]", "# Checked by the builder before anything is stored. A failed guard names itself.", `toolchain_present = ${tomlArray(c.toolchain)}`);
     if (c.lockfile)
         lines.push(`lockfile_unchanged = ${tomlString(c.lockfile)}`);
     lines.push("install_sane = true", "verify_warm_ratio = true", "");

package/dist/mcp.js

@@ -138,7 +138,7 @@ export const MCP_TOOLS = [
             type: "object",
             properties: {
                 snapshot: { type: "string", description: "snap_<id>, an alias, or alias@commit7. Default promigence/base. Not with image." },
-                image: { type: "string", description: "a tag such as python:3.12 (the API pins it to a digest) or registry/name@sha256:<64 hex>. A new image's snapshot is built on first use (minutes, charged at your build price: \`promigence pricing\`) and reused free after." },
+                image: { type: "string", description: "a tag such as python:3.12 (the API pins it to a digest) or registry/name@sha256:<64 hex>. A new image's snapshot is built on first use (minutes, billed per second while it builds at its tier's rate: \`promigence pricing\`) and reused free after." },
                 tier: { type: "string", description: "Machine size for an image's snapshot; a snapshot already has one.", enum: ["xsmall", "small", "medium", "large"] },
                 timeout_s: seconds("Sandbox lifetime", "; it is killed when this expires (default 15 minutes)"),
                 network,
@@ -158,7 +158,9 @@ export const MCP_TOOLS = [
             }
             const asked = typeof a["cap_usd"] === "number" ? a["cap_usd"] : undefined;
             const capped = asked !== undefined && s.cap !== undefined ? Math.min(asked, s.cap) : asked ?? s.cap;
-            const build = typeof a["image"] === "string" && capped !== undefined ? await buildPrice(s.client()) : 0;
+            const build = typeof a["image"] === "string" && capped !== undefined
+                ? (await buildPrice(s.client(), typeof a["tier"] === "string" ? a["tier"] : undefined)).most_usd
+                : 0;
             let runCost = 0;
             if (typeof a["image"] === "string" && capped !== undefined) {
                 const p = await livePricing(s.client());
@@ -171,7 +173,7 @@ export const MCP_TOOLS = [
                 const needed = (Math.ceil((build + runCost) * 100) / 100).toFixed(2);
                 throw new PromigenceError({
                     code: "cap_exceeded",
-                    message: `a new image's snapshot build costs $${build.toFixed(2)}, over ${which} $${capped.toFixed(2)}` +
+                    message: `a new image's snapshot build can cost up to $${build.toFixed(2)}, over ${which} $${capped.toFixed(2)}` +
                         `${capped >= build ? ` with the sandbox's own cost (about $${runCost.toFixed(2)})` : ""}; nothing was built or started`,
                     fix: `Pass snapshot instead (build it once outside the agent: ${sh `promigence snapshot create --image ${a["image"]} --alias NAME`}), or ` +
                         (which === "cap_usd" ? `pass cap_usd ${needed} or more.` : `start the server with --cap ${needed} or more.`),

package/dist/pricing.d.ts

@@ -22,17 +22,27 @@ export interface Prices {
     preemptible_vcpu_second_usd: number;
     preemptible_gib_second_usd: number;
     build_usd: number;
+    build_max_s: number;
     granularity_seconds: number;
     tiers: PriceTier[];
 }
 export declare function publishedPrices(): Prices;
+export declare const DEFAULT_BUILD_TIER = "small";
 export declare function compiledPrices(note?: string, reason?: string): Prices;
 export declare function pricesFrom(view: PricingView): Prices;
 export declare function livePricing(c: PromigenceClient, opts?: {
     newAccount?: boolean;
     strict?: boolean;
 }): Promise<Prices>;
-export declare function buildPrice(c: PromigenceClient): Promise<number>;
+export interface BuildPrice {
+    most_usd: number;
+    per_second_usd: number;
+    max_s: number;
+}
+export declare function buildPriceIn(p: Prices, tier?: string): BuildPrice;
+export declare function buildPrice(c: PromigenceClient, tier?: string): Promise<BuildPrice>;
+export declare function buildLimit(s: number): string;
+export declare function buildPriceWords(p: BuildPrice, tier?: string): string;
 export declare function quickClient(ctx: Ctx): PromigenceClient;
 export declare function rate(n: number): string;
 export declare function pricingLines(p: Prices, opts?: {

package/dist/pricing.js

@@ -1,6 +1,6 @@
 import { PromigenceClient } from "./sdk/index.js";
 import { bool, clientOpts, nexts } from "./commands.js";
-import { BUILD_PRICE, PRICING, TIERS } from "./generated.js";
+import { BUILD_MAX_S, PRICING, TIERS } from "./generated.js";
 import { emit, okEnvelope, recordNotice } from "./io.js";
 import { usd } from "./money.js";
 export const COMPILED_NOTE = "list prices at build time; could not reach the API";
@@ -9,10 +9,12 @@ const nano = (n) => Math.round(n * 1e9) / 1e9;
 export function publishedPrices() {
     return { ...compiledPrices(PUBLISHED_NOTE), source: "published" };
 }
+export const DEFAULT_BUILD_TIER = "small";
 export function compiledPrices(note = COMPILED_NOTE, reason) {
     const perSecond = (v, g) => (t) => nano(t.vcpus * v + t.mem_gib * g);
     const od = perSecond(PRICING.vcpu_second_usd, PRICING.gib_second_usd);
     const pe = perSecond(PRICING.preemptible_vcpu_second_usd, PRICING.preemptible_gib_second_usd);
+    const buildTier = TIERS.find((t) => t.name === DEFAULT_BUILD_TIER);
     return {
         source: "compiled",
         note,
@@ -21,7 +23,8 @@ export function compiledPrices(note = COMPILED_NOTE, reason) {
         gib_second_usd: PRICING.gib_second_usd,
         preemptible_vcpu_second_usd: PRICING.preemptible_vcpu_second_usd,
         preemptible_gib_second_usd: PRICING.preemptible_gib_second_usd,
-        build_usd: BUILD_PRICE,
+        build_usd: buildTier ? nano(od(buildTier) * BUILD_MAX_S) : 0,
+        build_max_s: BUILD_MAX_S,
         granularity_seconds: PRICING.granularity_seconds,
         tiers: TIERS.filter((t) => t.sellable)
             .slice()
@@ -41,6 +44,7 @@ export function pricesFrom(view) {
         preemptible_vcpu_second_usd: view.rates.preemptible_vcpu_second_usd,
         preemptible_gib_second_usd: view.rates.preemptible_gib_second_usd,
         build_usd: view.rates.build_usd,
+        build_max_s: view.limits?.build_max_s ?? BUILD_MAX_S,
         granularity_seconds: view.granularity_seconds,
         tiers: view.tiers.map((t) => ({ ...t })),
     };
@@ -72,8 +76,22 @@ export async function livePricing(c, opts = {}) {
         return compiledPrices(COMPILED_NOTE, err?.message ?? String(e));
     }
 }
-export async function buildPrice(c) {
-    return (await livePricing(c)).build_usd;
+export function buildPriceIn(p, tier) {
+    const t = tier === undefined ? undefined : p.tiers.find((x) => x.name === tier);
+    const max = p.build_max_s > 0 ? p.build_max_s : BUILD_MAX_S;
+    if (t !== undefined) {
+        return { most_usd: nano(t.per_second_usd * max), per_second_usd: t.per_second_usd, max_s: max };
+    }
+    return { most_usd: p.build_usd, per_second_usd: nano(p.build_usd / max), max_s: max };
+}
+export async function buildPrice(c, tier) {
+    return buildPriceIn(await livePricing(c), tier);
+}
+export function buildLimit(s) {
+    return hours(s);
+}
+export function buildPriceWords(p, tier) {
+    return `up to ${usd(p.most_usd)} (${tier === undefined ? "" : `tier ${tier}, `}${rate(p.per_second_usd)}/s for at most ${buildLimit(p.max_s)})`;
 }
 export function quickClient(ctx) {
     const opts = clientOpts(ctx);
@@ -97,7 +115,7 @@ export function pricingLines(p, opts = {}) {
         head,
         `  rates     ${rate(p.vcpu_second_usd)} per vCPU-second + ${rate(p.gib_second_usd)} per GiB-second, billed per second (rounded up to ${p.granularity_seconds} s)`,
         `  preempt.  ${rate(p.preemptible_vcpu_second_usd)} per vCPU-second + ${rate(p.preemptible_gib_second_usd)} per GiB-second (preemptible runs)`,
-        `  build     ${usd(p.build_usd)} per new snapshot build, charged once it verifies`,
+        `  build     a new snapshot build is billed per second at its tier's rate while it runs, at most ${hours(p.build_max_s)} (up to ${usd(p.build_usd)} at ${DEFAULT_BUILD_TIER}); not billed when it fails on our side`,
     ];
     if (v) {
         const eg = v.rates.egress_gb_usd;

package/dist/runners-spec.js

@@ -4,9 +4,11 @@ export const ACTIONS_RUNNER_SHA256 = "70920811a4f8ad4328818682bca5c6469c1c942fab
 export const GITLAB_RUNNER_VERSION = "19.4.1";
 export const GITLAB_RUNNER_SHA256 = "5a159b36c5ff54fda9248e00bb0cdfb62c1112ab3741f5282c04a41e94da1306";
 export const GITLAB_RUNNER_DEB_SHA256 = "47d2fd991e0b17af6f85af8fe3cc0cc429aae782d4f9982724c1f11a4de4a47c";
+export const RUNNER_NODE_VERSION = "v24.21.0";
+export const RUNNER_NODE_SHA256 = "fd8e59d5a511510f6a298afb548f18c7d2b1be404d8b4a27d94fbe49f56cb2d6";
 export const GITLAB_HELPER_IMAGE = `registry.gitlab.com/gitlab-org/gitlab-runner/gitlab-runner-helper:x86_64-v${GITLAB_RUNNER_VERSION}`;
 export const GITLAB_DEFAULT_JOB_IMAGE = "ubuntu:24.04";
-export const RUNNER_SPEC_REV = { github: 4, gitlab: 4 };
+export const RUNNER_SPEC_REV = { github: 5, gitlab: 4 };
 export const RUNNER_TIERS = ["small", "medium", "large"];
 export const GITHUB_CONFIG_PATH = "/root/.ci-runner-config";
 export const GITLAB_CONFIG_PATH = "/etc/gitlab-runner/config.toml";
@@ -79,8 +81,12 @@ export function runnerBuildSteps(s) {
 export function runnerImageSpec(kind, tier) {
     if (kind === "github") {
         const url = `https://github.com/actions/runner/releases/download/v${ACTIONS_RUNNER_VERSION}/actions-runner-linux-x64-${ACTIONS_RUNNER_VERSION}.tar.gz`;
+        const nodeUrl = `https://nodejs.org/dist/${RUNNER_NODE_VERSION}/node-${RUNNER_NODE_VERSION}-linux-x64.tar.xz`;
         const setup = [
             APT_STEP,
+            `set -eu; curl -fsSL --retry 3 -o /tmp/node.tar.xz ${nodeUrl}; sha256sum /tmp/node.tar.xz; ` +
+                `echo '${RUNNER_NODE_SHA256}  /tmp/node.tar.xz' | sha256sum -c -; ` +
+                "tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1 --no-same-owner; rm -f /tmp/node.tar.xz",
             "set -eu; id -u runner >/dev/null 2>&1 || useradd --create-home --shell /bin/bash --uid 1001 runner; " +
                 "groupadd -f docker; usermod -aG docker runner; " +
                 "printf 'runner ALL=(ALL) NOPASSWD:ALL\\nDefaults:runner !requiretty\\n' > /etc/sudoers.d/runner; " +
@@ -95,6 +101,8 @@ export function runnerImageSpec(kind, tier) {
         ];
         const verify = `set -eu; cd ${GITHUB_RUNNER_ROOT}; setpriv --reuid=runner --regid=runner --init-groups env HOME=/home/runner ./config.sh --version; ` +
             "git --version; jq --version; python3 --version; lsb_release -rs; " +
+            `test "$(node --version)" = ${RUNNER_NODE_VERSION}; ` +
+            "setpriv --reuid=runner --regid=runner --init-groups env HOME=/home/runner sh -c 'node --version && npm --version && npx --version'; " +
             "setpriv --reuid=runner --regid=runner --init-groups env HOME=/home/runner sh -c 'docker --version && docker compose version && docker buildx version'; " +
             `sudo -n -u runner true; id runner; test -x ${GITHUB_LAUNCHER}`;
         const platform_setup = [

package/dist/runners.js

@@ -3,10 +3,10 @@ import { chmodSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, wr
 import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { configDir, PromigenceError } from "./sdk/index.js";
-import { bool, client, nexts, str } from "./commands.js";
+import { bool, buildPriceOf, client, nexts, str } from "./commands.js";
 import { fitLine } from "./capacity.js";
 import { TIERS } from "./generated.js";
-import { COMPILED_NOTE, livePricing } from "./pricing.js";
+import { buildPriceIn, buildPriceWords, COMPILED_NOTE, livePricing } from "./pricing.js";
 import { emit, errorEnvelope, errorTextLines, okEnvelope, parseCount, parseDuration, parseUsd, usageError, write } from "./io.js";
 import { escapeLine, jsonLine, sh } from "./term.js";
 import { GITHUB_CONFIG_PATH, GITHUB_LAUNCHER, GITLAB_CONFIG_PATH, GITLAB_LAUNCHER, RUNNER_TIERS, isRunnerTier, runnerAlias, runnerBuildSteps, runnerImageSpec, } from "./runners-spec.js";
@@ -900,7 +900,8 @@ async function ensureSnapshot(ctx, c, kind, tier, mid) {
             throw e;
     }
     const prices = await livePricing(c);
-    const price = usd(prices.build_usd);
+    const most = buildPriceIn(prices, tier);
+    const price = `up to ${usd(most.most_usd)}, billed per second while it builds`;
     const listed = prices.source === "compiled" ? ` (${COMPILED_NOTE})` : "";
     const yes = bool(ctx, "--yes");
     const what = `the ${kind === "github" ? "GitHub Actions" : "GitLab"} runner snapshot for ${tier} (${shape(tier)})`;
@@ -909,17 +910,21 @@ async function ensureSnapshot(ctx, c, kind, tier, mid) {
         if (!interactive) {
             if (mid)
                 return undefined;
-            throw usageError(`${what} is not built yet: building it costs ${price} once (about two minutes)${listed}`, `Pass --yes to build it, or build it first: ${sh `promigence runners ${kind} --prepare --tier ${tier} --yes`}`);
+            throw usageError(`${what} is not built yet: building it once costs ${price} (about two minutes)${listed}`, `Pass --yes to build it, or build it first: ${sh `promigence runners ${kind} --prepare --tier ${tier} --yes`}`);
         }
         const ok = await confirm(`${what} is not built yet. Build it now? One time, ${price}${listed}, about two minutes. [y/N] `);
         if (!ok)
             return undefined;
     }
     const b = await c.snapshots.create({ image: s.image, setup: runnerBuildSteps(s), verify: { cmd: s.verify }, tier, alias: s.alias });
-    const charged = b.deduped || b.joined ? 0 : typeof b.build_price === "number" ? b.build_price : prices.build_usd;
+    const charged = b.deduped || b.joined ? 0 : typeof b.build_price === "number" ? b.build_price : most.most_usd;
+    const said = buildPriceOf(b);
     await write(process.stderr, ctx.mode === "json"
-        ? jsonLine(process.stderr, { hint: "build_price", build_price: charged, unit: "USD", tier, alias: s.alias, build_id: b.build_id })
-        : `building ${s.alias}: ${usd(charged)}${charged === 0 ? " (an identical build exists)" : ""}, build ${b.build_id}; jobs start once it is verified\n`);
+        ? jsonLine(process.stderr, {
+            hint: "build_price", build_price: charged, unit: "USD", tier, alias: s.alias, build_id: b.build_id,
+            ...(charged > 0 && said ? { per_second_usd: said.per_second_usd, max_seconds: said.max_s } : {}),
+        })
+        : `building ${s.alias}: ${charged === 0 ? `${usd(0)} (an identical build exists)` : said ? buildPriceWords(said) : usd(charged)}, build ${b.build_id}; jobs start once it is verified\n`);
     let build = b;
     if (!(b.deduped || b.state === "verified")) {
         const w = await c.snapshots.waitBuild(b.build_id, { waitTimeoutMs: BUILD_WAIT_MS });
@@ -933,7 +938,7 @@ async function ensureSnapshot(ctx, c, kind, tier, mid) {
         throw new PromigenceError({
             code: "env_failed",
             message: `the runner snapshot build ${b.build_id} ended ${build.state}${build.error?.message ? `: ${build.error.message}` : ""}${log.length ? ` (last log line: ${log[log.length - 1]})` : ""}`,
-            fix: `Nothing was charged for a build that did not verify. Read ${sh `promigence snapshot status ${b.build_id} --log 80`}, and tell support@promigence.ai if it is not your network.`,
+            fix: `${typeof build.cost_usd === "number" && build.cost_usd > 0 ? `Nothing was stored; the time it ran was billed (${usd(build.cost_usd)}).` : "Nothing was stored or charged."} Read ${sh `promigence snapshot status ${b.build_id} --log 80`}, and tell support@promigence.ai if it is not your network.`,
             exitCode: 3,
         });
     }
@@ -1208,7 +1213,7 @@ const runnersGithub = async (ctx) => {
             if (snapshots.has(t))
                 return snapshots.get(t);
             if (!bool(ctx, "--yes")) {
-                poolRef?.note(`a job asks for promigence-${t}: its runner snapshot is not built (${sh `promigence runners github --prepare --tier ${t} --yes`}, ${usd(setup.prices.build_usd)} once)`);
+                poolRef?.note(`a job asks for promigence-${t}: its runner snapshot is not built (${sh `promigence runners github --prepare --tier ${t} --yes`}, once: up to ${usd(buildPriceIn(setup.prices, t).most_usd)}, billed per second)`);
                 return undefined;
             }
             if (building.has(t))

package/dist/sdk/client.d.ts

@@ -420,7 +420,19 @@ export interface SnapshotBuild {
     /** `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>;
@@ -847,7 +859,10 @@ export interface PricingView {
         gib_second_usd: number;
         preemptible_vcpu_second_usd: number;
         preemptible_gib_second_usd: number;
-        /** One snapshot build, charged once it verifies. */
+        /**
+         * 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;
@@ -872,6 +887,8 @@ export interface PricingView {
         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: {
@@ -1447,7 +1464,11 @@ export interface PromigenceClientOpts {
      * From the CLI: `promigence --request-timeout DUR` or `PROMIGENCE_REQUEST_TIMEOUT`.
      */
     requestTimeoutMs?: number;
-    /** Retries on 429/503 only (default 3). */
+    /**
+     * 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;
@@ -1885,7 +1906,7 @@ interface RequestOpts {
     signal?: AbortSignal;
     /** Skip the Authorization header (unauthenticated routes). */
     anonymous?: boolean;
-    /** Called with the response headers of the attempt that answered (not of a retried 429/503). */
+    /** 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>;
@@ -1960,8 +1981,10 @@ export declare class PromigenceClient {
      * 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. At most `maxRetries`
-     * times, and never a `Retry-After` longer than MAX_RETRY_SLEEP_MS: that one is the caller's.
+     * `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. */
@@ -1998,7 +2021,7 @@ export declare class PromigenceClient {
     }): Promise<StatusResponse>;
     /**
      * `GET /pricing` — your organization's price list, live: the per-second rates, every sandbox
-     * shape on sale and its price, the build price, the limits, the free credit and the plan they
+     * 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.
      *

package/dist/sdk/client.js

@@ -837,7 +837,8 @@ export class PromigenceClient {
     refusalBackoff(status, retryAfterMs, code, attempt, replayable, signal) {
         if (attempt >= this.maxRetries || signal?.aborted)
             return undefined;
-        if (status !== 429 && status !== 503)
+        const gateway = (status === 502 || status === 504) && replayable && code === undefined;
+        if (status !== 429 && status !== 503 && !gateway)
             return undefined;
         if ((retryAfterMs ?? 0) > MAX_RETRY_SLEEP_MS)
             return undefined;
@@ -960,12 +961,17 @@ export class PromigenceClient {
                 throw new UnreachableError(`cannot reach ${url}: ${transportDetail(e)}`);
             }
             const retryAfterMs = parseRetryAfter(headerOf(res, "retry-after"));
-            let retryable = (res.status === 429 || res.status === 503) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
+            const gateway = (res.status === 502 || res.status === 504) && replayable;
+            let retryable = (res.status === 429 || res.status === 503 || gateway) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
             let body;
             if (retryable && res.status === 503 && !replayable && retryAfterMs === undefined) {
                 body = await res.text().catch(() => "");
                 retryable = REFUSED_503_CODES.has(errorCodeOf(body) ?? "");
             }
+            if (retryable && gateway) {
+                body = await res.text().catch(() => "");
+                retryable = errorCodeOf(body) === undefined;
+            }
             if (retryable && attempt < this.maxRetries) {
                 const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
                 const jitter = Math.random();
@@ -973,6 +979,8 @@ export class PromigenceClient {
                     ? retryAfterMs + jitter * Math.min(250, this.retryBaseMs)
                     : backoff * (0.5 + jitter * 0.5);
                 this.stats.retries++;
+                if (gateway && opts.method === "DELETE")
+                    resentDelete = true;
                 if (body === undefined)
                     try {
                         await res.text();

package/dist/sdk/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.8";
+export declare const VERSION = "0.1.0-beta.9";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
@@ -14,12 +14,14 @@ export declare const WAIT_TIMEOUT_MS = 100000;
  */
 export declare const IMAGE_BUILD_TIMEOUT_MS: number;
 /**
- * The list price of one new snapshot build this SDK was built with, in USD (charged once it
- * verifies; a dedupe or a join is free). Prices change: the live one is `client.pricing()`'s
- * `rates.build_usd` (this key's organization's), and a build's own arrives as `build_price` in
- * the `POST /snapshots` answer. This is only the fallback when the API cannot be asked.
+ * The most one new snapshot build of the default tier can cost at the list prices this SDK was
+ * built with, in USD: its time limit (an hour) at that tier's per-second rate. A build is billed per
+ * second for the time it runs; reusing or joining an identical build is free. Prices change: the
+ * live figure is `client.pricing()`'s `rates.build_usd` (this key's organization's), and a build's
+ * own arrives as `build_price` in the `POST /snapshots` answer. This is only the fallback when the
+ * API cannot be asked.
  */
-export declare const IMAGE_BUILD_LIST_PRICE = 1;
+export declare const IMAGE_BUILD_LIST_PRICE = 0.1656;
 /** Inline output budget for an exec before `truncated` + `_ref`. */
 export declare const MAX_OUTPUT_BYTES_DEFAULT: number;
 /** One request of a `files.put`. **Not a file-size limit** — `put` loops. */

package/dist/sdk/core.js

@@ -1,12 +1,12 @@
 import { hintArg } from "./hint.js";
-export const VERSION = "0.1.0-beta.8";
+export const VERSION = "0.1.0-beta.9";
 export const DOCS_URL = "https://promigence.ai";
 export const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 export const DEFAULT_API_URL = "https://api.promigence.ai/v1";
 export const KEY_CONTACT = "support@promigence.ai";
 export const WAIT_TIMEOUT_MS = 100_000;
 export const IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
-export const IMAGE_BUILD_LIST_PRICE = 1.0;
+export const IMAGE_BUILD_LIST_PRICE = 0.1656;
 export const MAX_OUTPUT_BYTES_DEFAULT = 64 * 1024;
 export const FILE_PUT_CHUNK_BYTES = 16 * 1024 * 1024;
 const PREVIEWS_OFF = /^previews are not enabled on this deployment\.?$/i;

package/dist/sdk/github.d.ts

@@ -34,7 +34,7 @@ export interface GithubPending {
     state: string;
     message: string;
 }
-/** A snapshot that follows a branch: every push builds it again (at the build price). */
+/** A snapshot that follows a branch: every push builds it again (each build billed per second). */
 export interface GithubTrack {
     track_id: string;
     repo: string;

package/dist/sdk/gitlab.d.ts

@@ -37,7 +37,7 @@ export interface GitlabPending {
     expires_at: string;
     message: string;
 }
-/** A snapshot that follows a GitLab branch: each new commit builds it again (at the build price). */
+/** A snapshot that follows a GitLab branch: each new commit builds it again (each build billed per second). */
 export interface GitlabTrack {
     track_id: string;
     repo: string;

package/dist/sdk/models.gen.d.ts

@@ -346,16 +346,29 @@ export interface BuildJoined {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when the running build carries another. It was not applied;
-     * `warnings` says what to do once the build verifies.
+     * The alias that was asked for, when the build in progress was to carry another, or none.
+     * The build carries it now (`alias_applied: true`) and its snapshot is stored under it;
+     * `warnings` names the alias the build was to carry.
      */
     alias_requested?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -378,10 +391,20 @@ export interface BuildJoined {
      * Always true here.
      */
     joined: boolean;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -412,8 +435,8 @@ export interface BuildJoined {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
-     * is charged if the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -455,7 +478,8 @@ export interface BuildQueued {
     alias?: string | null;
     build_id: string;
     /**
-     * What the build costs, in USD, said before it runs.
+     * The most the build can cost, in USD, said before it runs: `max_seconds` at
+     * `per_second_usd`. It is billed per second for the time it runs.
      */
     build_price: number;
     commit: string;
@@ -469,10 +493,18 @@ export interface BuildQueued {
      * given, so a client can say which earlier request this repeats.
      */
     idempotent_replay_age_s?: number | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate.
+     */
+    per_second_usd?: number | null;
     repo: string;
     /**
      * What it is being built from. The `kind` field says which of the three forms it is.
@@ -511,12 +543,24 @@ export interface BuildView {
      * the snapshot is deleted: the name may belong to another snapshot by then.
      */
     alias?: string | null;
+    /**
+     * Once the build has ended, the seconds it is billed for: the time it ran, whether it was
+     * stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed
+     * on our side. Absent while it is queued or running, and for a build priced per build.
+     */
+    billable_seconds?: number | null;
     build_id: string;
     /**
-     * What the build cost, in USD.
+     * The most the build can cost, in USD, as said when it was started: `max_seconds` at
+     * `per_second_usd`. What it was billed is `cost_usd`.
      */
     build_price: number;
     commit: string;
+    /**
+     * Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it
+     * is queued or running.
+     */
+    cost_usd?: number | null;
     /**
      * RFC 3339.
      */
@@ -529,10 +573,20 @@ export interface BuildView {
      * RFC 3339.
      */
     finished_at?: string | null;
+    /**
+     * The longest the build may run, in seconds: it is billed for at most this long. Absent for
+     * a build priced per build.
+     */
+    max_seconds?: number | null;
     /**
      * What to do next, ready to run.
      */
     next: Array<string>;
+    /**
+     * What one second of the build costs, in USD: its tier's per-second rate. Absent for a build
+     * priced per build, before builds were billed per second.
+     */
+    per_second_usd?: number | null;
     repo: string;
     setup: Array<string>;
     /**
@@ -563,8 +617,8 @@ export interface BuildView {
     /**
      * True when the build finished `verified` and its verification command passed. False while
      * it is queued or running, when it failed or was rejected, and for an image built without
-     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored and nothing
-     * is charged if the command exits non-zero.
+     * `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the
+     * command exits non-zero; the time the build ran is billed.
      */
     verified: boolean;
     /**
@@ -2460,7 +2514,7 @@ export interface LedgerEntryView {
      */
     seconds: number;
     /**
-     * What was charged: a sandbox id or a build id.
+     * What was charged: a sandbox id or a build id; for credit, what it is for (e.g. "Credit from Promigence").
      */
     subject: string;
     tier: string;
@@ -3103,6 +3157,11 @@ export interface PricingFreeCredit {
  * The limits in force.
  */
 export interface PricingLimits {
+    /**
+     * The longest a snapshot build may run, in seconds, and so the most seconds one build is
+     * billed for.
+     */
+    build_max_s?: number | null;
     /**
      * A sandbox's timeout when its run names none, in seconds.
      */
@@ -3161,8 +3220,11 @@ export interface PricingPlan {
  */
 export interface PricingRates {
     /**
-     * One snapshot build, charged once it verifies. A build that fails `verify` stores nothing
-     * and is not charged; reusing an identical build is free.
+     * The most one snapshot build of the default tier can cost: `limits.build_max_s` seconds at
+     * that tier's per-second rate. A build is billed per second at its own tier's rate (`tiers`)
+     * for the time it runs, whether it is stored, its own `setup` or `verify` fails, or it runs to
+     * its time limit; a failure on our side, and reusing or joining an identical build, cost
+     * nothing.
      */
     build_usd: number;
     /**
@@ -5201,8 +5263,7 @@ export interface SnapshotCreate {
  */
 export type SnapshotCreated = BuildQueued | BuildJoined | SnapshotDeduped;
 /**
- * Inputs that are already built: the existing snapshot, and whether the alias that was asked
- * for could be applied to it.
+ * Inputs that are already built: the existing snapshot, named with the alias that was asked for.
  */
 export interface SnapshotDeduped {
     /**
@@ -5211,8 +5272,10 @@ export interface SnapshotDeduped {
     alias?: string | null;
     alias_applied?: boolean | null;
     /**
-     * The alias that was asked for, when it differs from the snapshot's. An unnamed snapshot
-     * takes the name (`alias_applied: true`); a named one keeps its own and `warnings` says so.
+     * The alias that was asked for, when the snapshot did not hold it. The snapshot takes it
+     * (`alias_applied: true`) as a new build would: another snapshot of the project that had it
+     * keeps its row, without a name. A snapshot has one alias, so a name it had before gives
+     * way, and `warnings` says which.
      */
     alias_requested?: string | null;
     /**

package/dist/sdk/sandbox.d.ts

@@ -136,7 +136,7 @@ export interface SandboxCreateOpts extends SandboxOpts {
     /**
      * A container image instead of a snapshot — a tag (`python:3.12`, pinned to its digest by the
      * API) or `registry/name@sha256:<64 hex>`: the snapshot of this image is built on first use
-     * (a new build is charged your build price once it verifies, `client.pricing()`; pass
+     * (a new build is billed per second while it runs, at its tier's rate, `client.pricing()`; pass
      * `allowBuild: true` to allow it) and
      * reused after (same digest + same inputs → the same snapshot). A name with no tag or digest is
      * refused: it would pin whatever `:latest` is today. The fields below shape that snapshot and
@@ -156,17 +156,17 @@ export interface SandboxCreateOpts extends SandboxOpts {
     buildTimeoutMs?: number;
     /**
      * Let `Sandbox.create({ image })` build the image's snapshot when none exists yet. A new build
-     * costs `build_price` (your plan's, `client.pricing()`; charged once it verifies); reusing a snapshot already built
-     * is free. Without it, a create from an image is refused before anything is sent: whether the
+     * is billed per second while it runs, at most `build_price` (your plan's rates, `client.pricing()`);
+     * reusing a snapshot already built is free. Without it, a create from an image is refused before anything is sent: whether the
      * image's snapshot exists is only known once a build is submitted, and a submitted build cannot
      * be withdrawn. The other way to pay once and on purpose: `promigence snapshot create --image
      * REF --alias NAME`, then `Sandbox.create("NAME")`.
      */
     allowBuild?: boolean;
     /**
-     * Called with the `POST /snapshots` answer before any wait: `build_price`, and `deduped` or
-     * `joined` when nothing new is charged. Without it, a new build's price is reported as a
-     * process warning (stderr) before the build is waited for.
+     * Called with the `POST /snapshots` answer before any wait: `build_price` (the most the build can
+     * cost) and `per_second_usd`, and `deduped` or `joined` when nothing new is charged. Without it,
+     * a new build's price is reported as a process warning (stderr) before the build is waited for.
      */
     onBuild?: (build: SnapshotBuild) => void | Promise<void>;
     /**
@@ -198,9 +198,8 @@ export interface SandboxCreateOpts extends SandboxOpts {
  */
 export declare function imageSnapshot(client: PromigenceClient, opts: Pick<SandboxCreateOpts, "image" | "setup" | "verify" | "start" | "tier" | "alias" | "registrySecret" | "buildTimeoutMs">, hooks?: {
     /**
-     * The `POST /snapshots` answer, before any wait: `build_price` and whether it was `deduped`
-     * or `joined` (nothing new charged). An implicit build costs money, so a caller
-     * that prints prices prints this one too.
+     * The `POST /snapshots` answer, before any wait: `build_price` (the most it can cost) and
+     * whether it was `deduped` or `joined` (nothing new charged). An implicit build costs money, so a caller that prints prices prints this one too.
      */
     onBuild?: (build: SnapshotBuild) => void | Promise<void>;
     /** Ends the wait for a build at once; the build itself, once submitted, is not withdrawn. */
@@ -375,7 +374,7 @@ export declare class Sandbox {
     /**
      * Fork of 1 from a snapshot (`snap_<id>` | `<alias>` | `<alias>@<commit7>`), or from the
      * snapshot of an image: `Sandbox.create({ image: 'python:3.12', allowBuild: true })` builds it
-     * on first use (a new build at your build price, bounded by `buildTimeoutMs`, default 15 min) and reuses it
+     * on first use (a new build billed per second at its tier's rate, bounded by `buildTimeoutMs`, default 15 min) and reuses it
      * free after. An image needs `allowBuild: true` and a tag or digest; without either it is
      * refused before any request.
      *

package/dist/sdk/sandbox.js

@@ -65,12 +65,16 @@ function buildNotice(image) {
     return (b) => {
         if (buildIsFree(b))
             return;
-        const price = typeof b.build_price === "number" ? `build_price $${b.build_price.toFixed(2)}` : "charged your build price";
-        process.emitWarning(`building a snapshot of ${image}: ${price}, charged once it verifies (later creates from this image reuse it free)`, { code: "PROMIGENCE_BUILD" });
+        const price = typeof b.build_price === "number"
+            ? typeof b.per_second_usd === "number"
+                ? `billed per second while it builds ($${Number(b.per_second_usd.toPrecision(12))}/s), at most $${b.build_price.toFixed(2)}`
+                : `build_price $${b.build_price.toFixed(2)}, charged once it verifies`
+            : "billed at your plan's rates";
+        process.emitWarning(`building a snapshot of ${image}: ${price} (later creates from this image reuse it free)`, { code: "PROMIGENCE_BUILD" });
     };
 }
 function buildNotAllowed(image) {
-    return new InvalidArgumentError(`Sandbox.create({ image: ${JSON.stringify(image)} }) builds that image's snapshot unless one already exists, and a new build is charged your build price once it verifies (\`promigence pricing\` shows it; reusing a snapshot already built is free). Nothing was sent.`, `To allow the build: Sandbox.create({ image: ${JSON.stringify(image)}, allowBuild: true }). Or build it once, ` +
+    return new InvalidArgumentError(`Sandbox.create({ image: ${JSON.stringify(image)} }) builds that image's snapshot unless one already exists, and a new build is billed per second while it runs (\`promigence pricing\` shows the rates; reusing a snapshot already built is free). Nothing was sent.`, `To allow the build: Sandbox.create({ image: ${JSON.stringify(image)}, allowBuild: true }). Or build it once, ` +
         `\`promigence snapshot create --image ${hintArg(image)} --alias NAME\`, and create from its name: Sandbox.create("NAME").`);
 }
 export async function imageSnapshot(client, opts, hooks = {}) {

package/dist/surface.js

@@ -975,7 +975,7 @@ export const COMMANDS = [
             { name: "--idle-timeout", arg: "DUR", summary: "stop an on-demand runner no job took (90s)" },
             { name: "--kill-on-exit", summary: "Ctrl-C cancels running jobs instead of waiting" },
             { name: "--prepare", summary: "build the --tier runner snapshot, then exit" },
-            { name: "--yes", summary: "build a missing runner snapshot (the build price, per size) without asking" },
+            { name: "--yes", summary: "build a missing runner snapshot (billed per second, per size) without asking" },
             { name: "--github-api", arg: "URL", summary: "GitHub Enterprise Server's API URL" },
             { name: "--poll", arg: "DUR", summary: "how often GitHub is asked for queued jobs", hidden: true },
             json,
@@ -1001,7 +1001,7 @@ export const COMMANDS = [
             { name: "--idle-timeout", arg: "DUR", summary: "with --api-token-env: a runner no job took exits (90s)" },
             { name: "--kill-on-exit", summary: "Ctrl-C cancels running jobs instead of waiting" },
             { name: "--prepare", summary: "build the --tier runner snapshot, then exit" },
-            { name: "--yes", summary: "build a missing runner snapshot (the build price) without asking" },
+            { name: "--yes", summary: "build a missing runner snapshot (billed per second) without asking" },
             { name: "--poll", arg: "DUR", summary: "how often GitLab is asked for pending jobs", hidden: true },
             json,
         ],

package/llms.txt

@@ -1,4 +1,4 @@
-# Promigence — promigence@0.1.0-beta.8
+# Promigence — promigence@0.1.0-beta.9
 
 > Verified, reproducible, forkable execution environments for agents. The CLI is the
 > `promigence` command (package `promigence`, which is also the TypeScript SDK).
@@ -127,7 +127,7 @@
 
 ---
 
-# Promigence — agent guide (promigence@0.1.0-beta.8)
+# Promigence — agent guide (promigence@0.1.0-beta.9)
 
 Promigence is an **environment runtime**: verified, reproducible, forkable execution
 environments, billed per second (vCPU + memory). The model is one line:
@@ -135,7 +135,7 @@ environments, billed per second (vCPU + memory). The model is one line:
     verify → snapshot → fork(N) → exec → validity report
 
 - **snapshot** — an image (pinned) + ordered `setup` steps + a `verify` command that, if given, must exit 0.
-  If verify fails nothing is stored and nothing is charged. A branch is not a pin.
+  If verify fails nothing is stored; the build's own time is billed. A branch is not a pin.
 - **fork** — a warm copy of that workspace, with its `start` service ready;
   N at once, each checked before you get it.
 - **validity report** — per sandbox, and this split is the product: **env** failures are ours
@@ -205,5 +205,5 @@ Highest-precedence code wins: 2 > 5 > 6 > 7/8/9/10 > 11 > 3 > 12 > 4 > 1 > 0.
 · `promigence <command> --help` · https://promigence.ai
 Same surface as MCP tools: `promigence mcp` (stdio; `claude mcp add promigence -- promigence mcp`).
 
-Live in v0.1.0-beta.8: login · signup · logout · auth login · keys list/create/revoke · org list/create/switch/members/invite/invites/uninvite/resend/role/remove/leave/join/audit/rename/delete · project list/create/rename/delete/cap/move · me · billing card/usage/history/portal · doctor · ping · init · examples · templates +show · agent-guide · mcp · snapshot create/status/list/inspect/verify/export/delete/builds/alias · image resolve · github connect/status/disconnect/untrack · repos · gitlab connect/status/disconnect/untrack · run +quote/report/status/cancel/kill/replay/open/captures/list · fork · exec +output/ps/stdin/kill · files put/get/ls/search/mkdir/mv/cp/chmod/rm · agent start · sandbox kill/network/shell/ssh/list/pause/resume/snapshot/info/extend/autopause/probe · secrets set/list/delete · bench burst · runners github/gitlab · status · referrals +apply · pricing · credits +claim
+Live in v0.1.0-beta.9: login · signup · logout · auth login · keys list/create/revoke · org list/create/switch/members/invite/invites/uninvite/resend/role/remove/leave/join/audit/rename/delete · project list/create/rename/delete/cap/move · me · billing card/usage/history/portal · doctor · ping · init · examples · templates +show · agent-guide · mcp · snapshot create/status/list/inspect/verify/export/delete/builds/alias · image resolve · github connect/status/disconnect/untrack · repos · gitlab connect/status/disconnect/untrack · run +quote/report/status/cancel/kill/replay/open/captures/list · fork · exec +output/ps/stdin/kill · files put/get/ls/search/mkdir/mv/cp/chmod/rm · agent start · sandbox kill/network/shell/ssh/list/pause/resume/snapshot/info/extend/autopause/probe · secrets set/list/delete · bench burst · runners github/gitlab · status · referrals +apply · pricing · credits +claim
 Not on the hosted service yet: port expose/list/revoke (preview URLs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promigence",
-  "version": "0.1.0-beta.8",
+  "version": "0.1.0-beta.9",
   "description": "The fastest sandboxes for AI agents and code. Snapshot an environment once, fork it as often as you need, run commands in every copy, and get a report that tells environment failures from task failures. Billed per second, with a quote before a run and a hard spend cap. One package: the promigence command and the TypeScript SDK.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",