promigence 0.1.0-beta.7 → 0.1.0-beta.9

package/README.md

@@ -21,15 +21,13 @@ own (`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to your `
 
 ## Create your account
 
-Promigence is in private beta: you need an invite code.
-
 ```sh
 promigence signup
 ```
 
-It asks for your invite code, then opens your browser to create the account. Your API key is saved
-in your system keychain, or in `~/.config/promigence/credentials` (mode 0600) where there is none. On
-another machine, use `promigence login`: it signs you in with a code we email you, or your password. In CI or on an
+It opens your browser to create the account. Your API key is saved in your system keychain, or in
+`~/.config/promigence/credentials` (mode 0600) where there is none.
+On another machine, use `promigence login`: it signs you in with a code we email you. In CI or on an
 agent's machine, set `PROMIGENCE_API_KEY` instead. `promigence doctor` checks the setup.
 
 ## First commands
@@ -57,13 +55,19 @@ promigence fork --snapshot py --count 5 --cap 2
 
 ## For AI agents
 
-Run `promigence agent-guide` (about 1.2k tokens) before driving the CLI: it covers the model, the
+Run `promigence agent-guide` (about 1.4k tokens) before driving the CLI: it covers the model, the
 JSON output contract, exit codes and errors. `promigence agent-guide --install` writes the same
 guidance into your repo for coding agents, and `promigence mcp` serves the CLI as an MCP server.
 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/account.js

@@ -223,6 +223,7 @@ const billingUsage = async (ctx) => {
         usage,
         card_on_file: b.card_on_file ?? false,
         ...(b.card ? { card: b.card } : {}),
+        ...(b.card_note ? { card_note: b.card_note } : {}),
         ...(b.trial ? { trial: b.trial } : {}),
         ...(b.suspended ? { suspended: true, suspend_reason: b.suspend_reason ?? null } : {}),
         upcoming_invoice: b.upcoming_invoice ?? null,
@@ -260,6 +261,8 @@ const billingUsage = async (ctx) => {
     if (trial?.credits_remaining !== undefined)
         lines.push(`  trial credits left: ${usd(trial.credits_remaining)}`);
     lines.push(`  card: ${b.card_on_file ? paymentMethodText(b.card) : `none on file${billingOff ? " (card payments are not open yet)" : ""}`}`);
+    if (b.card_note)
+        lines.push(`  ${b.card_note}`);
     if (b.upcoming_invoice?.amount_due !== undefined && b.upcoming_invoice?.amount_due !== null) {
         lines.push(`  next invoice: ${usd(b.upcoming_invoice.amount_due)}`);
     }
@@ -282,6 +285,86 @@ const billingPortal = async (ctx) => {
     const next = nexts(["promigence billing usage", "this month's spend without leaving the terminal"]);
     return emit(ctx.mode, okEnvelope(ctx.cmd.name, { url: res.url }, next), ["promigence billing portal: open this page to manage the card and past invoices:", `  ${res.url}`], 0, ctx.pointer);
 };
+const HISTORY_KINDS = ["all", "credits", "payments"];
+const CREDIT_WHAT = {
+    free_credit: "Free credit",
+    card_bonus: "Card bonus",
+    referral: "Referral reward",
+    plan: "Included with your plan",
+    from_promigence: "Credit from Promigence",
+    service_restart: "Credit for a service restart",
+    confirmation_credit: "Credit for the $1 confirmation",
+};
+const CREDIT_ENDED = { used: "used", expired: "expired", taken_back: "taken back" };
+const PAYMENT_WHAT = {
+    invoice_paid: "Invoice paid",
+    payment_failed: "Payment failed",
+    refund: "Refund",
+};
+const PAYMENT_STATUS = {
+    paid: "paid",
+    retrying: "will be retried",
+    failed: "not paid",
+    refunded: "refunded",
+    confirmed: "confirmed",
+};
+const wordFor = (m, k) => k && Object.prototype.hasOwnProperty.call(m, k) ? m[k] : undefined;
+const unpaid = (status) => status === "retrying" || status === "failed";
+export function historyLines(entries) {
+    return entries.map((e) => {
+        const day = (e.at ?? "").slice(0, 10);
+        const c = e.credit;
+        if (c) {
+            const state = wordFor(CREDIT_ENDED, c.status) ??
+                `${usd(c.remaining_usd)} left, ${c.expires_at ? `expires ${c.expires_at.slice(0, 10)}` : "no expiry"}`;
+            return `  ${day}  ${wordFor(CREDIT_WHAT, c.kind) ?? "Credit"}  ${usd(c.granted_usd)}  ${state}`;
+        }
+        const p = e.payment;
+        if (!p)
+            return `  ${day}  (a row this version cannot show: see --json)`;
+        const check = p.kind === "method_check";
+        const what = check
+            ? `$${Number.isInteger(p.amount_usd) ? String(p.amount_usd) : p.amount_usd.toFixed(2)} to confirm ${p.method || "your payment method"}`
+            : (wordFor(PAYMENT_WHAT, p.kind) ?? "Payment");
+        const detail = [p.plan ? `${p.plan} plan` : null, p.invoice_number ? `invoice ${p.invoice_number}` : null]
+            .filter(Boolean)
+            .join(", ");
+        const status = check && p.status === "failed" ? "failed" : (wordFor(PAYMENT_STATUS, p.status) ?? p.status);
+        const url = typeof p.invoice_url === "string" && p.invoice_url.startsWith("https://") ? p.invoice_url : null;
+        const link = url && !check ? ` · ${unpaid(p.status) ? "pay at" : "receipt"} ${url}` : "";
+        return `  ${day}  ${what}${detail ? ` (${detail})` : ""}  ${usd(p.amount_usd)}  ${status}${link}`;
+    });
+}
+const billingHistory = async (ctx) => {
+    const kind = str(ctx, "--kind") ?? "all";
+    if (!HISTORY_KINDS.includes(kind)) {
+        throw usageError(`--kind: '${kind}' is not a kind`, `Pass one of ${HISTORY_KINDS.join(" | ")}.`);
+    }
+    const limit = limitOf(ctx, 50, 100);
+    const cursor = str(ctx, "--cursor");
+    const page = await client(ctx).billing.historyPage({
+        kind: kind,
+        limit,
+        ...(cursor === undefined ? {} : { cursor }),
+    });
+    const entries = page.items;
+    const more = page.nextCursor;
+    const owed = entries.some((e) => e.payment && e.payment.kind !== "method_check" && unpaid(e.payment.status));
+    const next = nexts(...(more
+        ? [[`${sh `promigence billing history --limit ${String(limit)}`}${kind === "all" ? "" : sh ` --kind ${kind}`}${sh ` --cursor ${more}`}`, "the next page"]]
+        : []), ...(owed
+        ? [["promigence billing portal", "pay the open invoice, or update the card on file"]]
+        : [["promigence billing usage", "this month's spend and credit"]]));
+    const empty = { all: "no credits or payments yet", credits: "no credit yet", payments: "no payments yet" };
+    const noun = kind === "all" ? "" : ` ${entries.length === 1 ? kind.slice(0, -1) : kind}`;
+    const lines = [
+        `promigence billing history: ${entries.length}${noun}, newest first`,
+        ...historyLines(entries),
+        ...(entries.length ? [] : [`  (${empty[kind]})`]),
+        ...(more ? [`  more: --cursor ${more}`] : []),
+    ];
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { kind, entries, count: entries.length, next_cursor: more }, next), lines, 0, ctx.pointer);
+};
 const referrals = async (ctx) => {
     const r = await client(ctx).billing.referrals();
     const next = r.code
@@ -745,6 +828,7 @@ export const ACCOUNT_HANDLERS = {
     status,
     "billing usage": billingUsage,
     "billing portal": billingPortal,
+    "billing history": billingHistory,
     referrals,
     "referrals apply": referralsApply,
     "snapshot delete": snapshotDelete,

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/errfix.js

@@ -106,6 +106,7 @@ function notFoundFor(kind, ctx, apiFix) {
 const BILLING_CMD = /`promigence billing (?:card|portal)`/;
 export function withoutBilling(text) {
     return text
+        .replace(/Owners: update the card with `promigence billing portal`; the hold lifts once the invoice is paid\.(?: For a disputed payment, write to support@promigence\.ai\.)?/, `To lift it, email ${SUPPORT}.`)
         .replace(/,? or move to a plan that allows it: `promigence billing (?:card|portal)`\.?/, `, or email ${SUPPORT} for a plan that allows it.`)
         .replace(/or add a card to lift it: `promigence billing (?:card|portal)`/, `or email ${SUPPORT} to lift it`)
         .replace(/adding a card raises it \(owners: `promigence billing (?:card|portal)`\)\.?/, `to raise it, email ${SUPPORT}.`)

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

@@ -106,7 +106,7 @@ export const ERRORS = [
         fix: "Set PROMIGENCE_API_KEY or run `promigence auth login --from-env VAR`. No key yet: `promigence login` (sign in) or https://promigence.ai." },
     { code: "forbidden", category: "other", http: 403, exit: 7, billed: "no",
         message: "{detail}",
-        fix: "Do what the message names: sign in (`promigence login`), use a key from that org, or ask an owner." },
+        fix: "Do what the message names: sign in (`promigence login`), use a full-access key (`promigence keys create`) or one from that org, or ask an owner." },
     { code: "not_found", category: "other", http: 404, exit: 8, billed: "no",
         message: "{kind} `{id}` not found",
         fix: "Check the id; aliases resolve in your org first, then public snapshots (`promigence examples`)." },
@@ -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>." },
@@ -191,7 +191,7 @@ export const ERRORS = [
     { code: "concurrency_limit", category: "other", http: 409, exit: 5, billed: "no",
         message: "{live} live + {requested} requested sandboxes is over your limit of {limit}",
         fix: "Wait for sandboxes to end or lower `--count` (`--allow-partial` covers the spend cap only); a retry of the same request fails the same way. Trial orgs get {trial_limit}; to raise it, email support@promigence.ai." },
-    { code: "egress_cap_reached", category: "other", http: 403, exit: 10, billed: "no",
+    { code: "egress_cap_reached", category: "other", http: 403, exit: 5, billed: "no",
         message: "monthly data-out cap reached: {used_gb} of {cap_gb} GB",
         fix: "Use `--network none` (still allowed) or wait for the 1st (UTC). For more data out a month, email support@promigence.ai." },
     { code: "project_cap_reached", category: "cap", http: 403, exit: 5, billed: "no",
@@ -199,7 +199,10 @@ export const ERRORS = [
         fix: "Ask for less (`--count`, `--cap`, a shorter extension), wait for the 1st (UTC), or have an owner raise it: `promigence project cap {project} <usd>`." },
     { code: "spend_limit_reached", category: "cap", http: 402, exit: 5, billed: "no",
         message: "today's spend limit {limit} has {remaining} left; this needs {needed}",
-        fix: "Running sandboxes finish. The limit resets at 00:00 UTC and grows with each paid invoice; ask for less, or email support@promigence.ai. After a failed payment, new work waits until it is paid (owners: `promigence billing portal`)." },
+        fix: "Running sandboxes finish. The limit resets at 00:00 UTC and grows with each paid invoice; ask for less, or email support@promigence.ai." },
+    { code: "billing_hold", category: "other", http: 402, exit: 5, billed: "no",
+        message: "new work is on hold: {reason}",
+        fix: "Running sandboxes finish. Owners: update the card with `promigence billing portal`; the hold lifts once the invoice is paid. For a disputed payment, write to support@promigence.ai." },
     { code: "tier_over_plan", category: "other", http: 403, exit: 2, billed: "no",
         message: "the {tier} tier ({vcpus} vCPU) is over the {limit} vCPU per-sandbox limit of your {plan} plan",
         fix: "Use a tier of at most {limit} vCPU (`promigence snapshot create … --tier {max_tier}` is the largest; a fork runs on its snapshot's), or move to a plan that allows it: `promigence billing portal`." },
@@ -260,12 +263,15 @@ 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." },
+    { code: "service_restart", category: "env", http: 0, exit: 3, billed: "no",
+        message: "a service restart stopped the command while its output was streaming",
+        fix: "Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe." },
     { code: "not_connected", category: "other", http: 0, exit: 7, billed: "no",
         message: "the connection request ended without connecting anything",
         fix: "Nothing was connected. Do what the message names, then run the connect command again; `promigence github status` (or `gitlab status`) lists what is connected." },
@@ -285,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,15 +1,15 @@
-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",
     credited: "no: ours, credited back",
     unless_ours: "the time used is billed, unless the cause is shown to be ours: then it is credited back",
 };
-import { DOCS_URL, EXIT_CODES, EXIT_PRECEDENCE_TEXT, GOLDEN_PATH, GROUPS, GUIDE_COMMON_ERRORS, LISTED_COMMANDS, LIVE_SUMMARY, NOT_LIVE_SUMMARY, SCHEMA, VERSION, WAIT_TIMEOUT_DEFAULT, } from "./surface.js";
+import { DOCS_URL, EXIT_CODES, EXIT_PRECEDENCE_TEXT, GOLDEN_PATH, GROUPS, GUIDE_COMMON_ERRORS, LISTED_COMMANDS, NOT_LIVE_SUMMARY, SCHEMA, VERSION, WAIT_TIMEOUT_DEFAULT, compactNames, } from "./surface.js";
 export const SECTIONS = ["core", "commands", "errors", "cost"];
 export const BUDGETS = {
-    core: 1200,
-    commands: 4475,
+    core: 1500,
+    commands: 4500,
     errors: 2325,
     cost: 600,
 };
@@ -20,7 +20,25 @@ export function lookupError(code) {
 export const ALL_ERROR_CODES = [...ERRORS, ...CLIENT_ERRORS].map((e) => e.code);
 export const estimateTokens = (s) => Math.ceil(s.length / 4);
 const exitLine = EXIT_CODES.filter((e) => e.code !== 125 && e.code !== 13).map((e) => `${e.code} ${e.name}`).join(" · ");
+const codesOn = (n) => ERRORS.filter((e) => e.exit === n).map((e) => e.code).join(", ");
+const EXIT_NOTE = {
+    7: codesOn(7),
+    10: `${codesOn(10)} only: retry after Retry-After`,
+    12: `some sandboxes ${codesOn(12)}`,
+    13: "agent-guide --check: files would change",
+    125: "exec --sandbox: ours; else the command's code",
+};
+const exitLegend = EXIT_CODES.map((e) => `${e.code} ${e.name}${EXIT_NOTE[e.code] ? ` (${EXIT_NOTE[e.code]})` : ""}`).join(" · ");
 const liveNames = new Set(LISTED_COMMANDS.map((c) => c.name));
+const HOSTED_LIVE = compactNames(LISTED_COMMANDS.filter((c) => !c.notOnHosted).map((c) => c.name));
+const NOT_ON_HOSTED = LISTED_COMMANDS.filter((c) => c.notOnHosted);
+const COUNT_WORDS = ["no", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten"];
+const exitOf = (code) => {
+    const e = ERROR_BY_CODE[code];
+    if (!e)
+        throw new Error(`the guide names ${code}, which is not a known error code`);
+    return e.exit;
+};
 function renderCore() {
     const common = GUIDE_COMMON_ERRORS.map((code) => {
         const e = ERROR_BY_CODE[code];
@@ -37,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",
@@ -63,15 +81,22 @@ function renderCore() {
         "Progress, prices and diagnostics go to **stderr** — never parse them. `next[].cmd` is",
         "id-based, runnable verbatim (fill any UPPERCASE word); use it, never invent one.",
         "",
-        `Exit codes: ${exitLine}.`,
+        `Exit codes: ${exitLegend}.`,
         `Highest-precedence code wins: ${EXIT_PRECEDENCE_TEXT}.`,
         "",
-        "## The six you will actually hit",
+        `## The ${COUNT_WORDS[common.length] ?? common.length} you will actually hit`,
         "",
         "(`{name}` in a fix is filled from the failure's evidence.)",
         "",
         ...common,
         "",
+        "## Limits and stops",
+        "",
+        `- \`setup_required\` (exit ${exitOf("setup_required")}): answer the account's setup questions in the console first.`,
+        `- \`egress_cap_reached\` (exit ${exitOf("egress_cap_reached")}): the month's data out is spent; \`--network none\` still starts; it resets on the 1st (UTC).`,
+        "- A paused sandbox is kept 30 days (`pause_expires_at`); resuming keeps it, else it is deleted (`expired`).",
+        `- \`stopped_by_support\` (exit ${exitOf("stopped_by_support")}): support stopped it; the message says why.`,
+        "",
         "## Do",
         "",
         "- Pass `--cap USD` on every `fork`/`run`: a run over it is refused (exit 5) before anything starts.",
@@ -99,7 +124,10 @@ function renderCore() {
         `· \`promigence <command> --help\` · ${DOCS_URL}`,
         "Same surface as MCP tools: `promigence mcp` (stdio; `claude mcp add promigence -- promigence mcp`).",
         "",
-        `Live in v${VERSION}: ${LIVE_SUMMARY}`,
+        `Live in v${VERSION}: ${HOSTED_LIVE}`,
+        ...(NOT_ON_HOSTED.length
+            ? [`Not on the hosted service yet: ${compactNames(NOT_ON_HOSTED.map((c) => c.name))} (${[...new Set(NOT_ON_HOSTED.map((c) => c.notOnHosted))].join(", ")}).`]
+            : []),
         ...(NOT_LIVE_SUMMARY ? ["Every other command exits 1 `not_released` in the same envelope."] : []),
         "",
     ].join("\n");
@@ -217,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`."
@@ -241,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",
@@ -320,7 +351,7 @@ export function renderLlmsTxt() {
         "",
         "## Index",
         "",
-        ...LISTED_COMMANDS.map((c) => `- \`promigence ${c.name}\` — ${c.summary}`),
+        ...LISTED_COMMANDS.map((c) => `- \`promigence ${c.name}\` — ${c.summary}${c.notOnHosted ? ` (not on the hosted service yet)` : ""}`),
         "",
         "- `promigence agent-guide` — this document's first section",
         "- `promigence agent-guide --section commands` — every command with its flags",

package/dist/handlers.js

@@ -1,6 +1,6 @@
 import { existsSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { BUNDLE_EXT, DEFAULT_SNAPSHOT, PromigenceError, VERSION as SDK_VERSION, configDir, credentialsPath, compatApiKey, platformOf, readCredentialsWithStore, renderBundle, verifyBundle, } from "./sdk/index.js";
+import { BUNDLE_EXT, DEFAULT_SNAPSHOT, PromigenceError, VERSION as SDK_VERSION, configDir, credentialsPath, platformOf, readCredentialsWithStore, renderBundle, verifyBundle, } from "./sdk/index.js";
 import { storeLabel } from "./sdk/credstore.js";
 import { bool, client, list, nexts, positional, required, str, } from "./commands.js";
 import { emit, exitWith, forkSummary, markGuideSeen, ms, okEnvelope, parseCount, parseDuration, parseUsd, pickExit, usageError, write, } from "./io.js";
@@ -30,7 +30,7 @@ const agentGuide = async (ctx) => {
         const skipped = res.artifacts.find((a) => a.action === "skipped");
         const next = nexts(...(skipped
             ? [["promigence agent-guide --install --create", "create AGENTS.md and write the fence into it"]]
-            : []), ["promigence agent-guide", "the guide itself (~1.2k tokens)"], ["promigence examples", "what you can fork with no build (the built-in base)"]);
+            : []), ["promigence agent-guide", "the guide itself (~1.4k tokens)"], ["promigence examples", "what you can fork with no build (the built-in base)"]);
         const env = okEnvelope(ctx.cmd.name, {
             mode: checking ? "check" : "install",
             dir: res.dir,
@@ -259,9 +259,6 @@ function keySource(ctx) {
     if (creds.api_key) {
         return { source: store === "file" || store === undefined ? credentialsPath() : `${storeLabel(store)} (item ${credentialsPath()})`, present: true };
     }
-    if (compatApiKey(process.env["E2B_API_KEY"])) {
-        return { source: "E2B_API_KEY (compatibility)", present: true };
-    }
     return { source: "none", present: false };
 }
 async function clientChecks(ctx) {

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";