withruntime 0.11.2 → 0.12.0

package/dist/cli.js

@@ -11,15 +11,19 @@ import { Sandbox as SandboxHandle } from "./sandbox.js";
 import { NotFoundError, RuntimeError } from "./errors.js";
 import { NETWORK_PRODUCTS, networkProductCommand } from "./network-cli.js";
 import { billingCommand } from "./billing-cli.js";
-import { cliRefusal, describeRecord, newestCpu, topicHelp } from "./cli-words.js";
+import { cliRefusal, describeRecord, newestCpu, productWords, topicHelp } from "./cli-words.js";
 import { envFetch } from "./proxy.js";
+import { logStream, terminalSafe, terminalSafeLines } from "./terminal.js";
 import { VERSION } from "./transport.js";
+/** A log stream's text (a sandbox process's, an image build's, a job run's)
+ * as stdout shows it: escaped on a terminal unless --raw (terminal.ts). */
+const logText = (args) => (text) => process.stdout.isTTY && !has(args, "raw") ? terminalSafeLines(text) : text;
 const HELP = `Runtime Cloud CLI ${VERSION}
 
 Usage: runtime <product> <command> [options]      runtime <command> [options]
 
 Start
-  sandbox run [--keep] [create options] -- <command>
+  sandboxes run [--keep] [create options] -- <command>
                                                A fresh sandbox runs one command, then stops
 
 Account
@@ -53,13 +57,15 @@ Account
   secrets rm <NAME>                            Delete a secret, every copy
   keys create [--name <name>] [--read-only] [--daily-limit <usd>] [--account-wide]
                                                A new API key for CI, approved by an owner in the browser
-  referrals                                    Your referral link: you both get up to $500
+  referrals                                    Your referral link: you both get up to $1,000, then
+                                               you earn 10% of what they spend for 12 months
   compare --from <provider> [--days 30]        What your usage would cost at e2b, daytona, vercel,
                                                modal, cloudflare, fly, blaxel, lambda-microvms,
                                                freestyle, prime and others, and what you save
   switch [--from <provider>]                   Moving from e2b, daytona, vercel, modal, cloudflare, fly
-                                               or blaxel: record it before your first top-up, and
-                                               that top-up is matched, up to $100
+                                               or blaxel: record it before your first top-up.
+                                               Credit you add within 30 days of signing up is
+                                               matched, up to $1,000 in total
   ls                                           Everything you run, every product
   feedback "<text>" [--kind bug|missing_feature|competitor_gap|migration_blocker|docs|pricing|praise|other]
                    [--detail <text>] [--competitor <name>] [--request-id <req_...>]
@@ -72,13 +78,13 @@ Account
   mcp                                          Serve MCP on stdio for agents that need it
 
 Connect
-  sandbox ssh <id|name> [-- <command...>]      Log in over SSH; \`runtime sandbox ssh help\` for editors
-  sandbox ssh config [--install]               Make \`ssh <id|name>.runtime\` work (VS Code, JetBrains)
-  sandbox port-forward <id|name> <port|local:remote>...
+  sandboxes ssh <id|name> [-- <command...>]    Log in over SSH; \`runtime sandboxes ssh help\` for editors
+  sandboxes ssh config [--install]             Make \`ssh <id|name>.runtime\` work (VS Code, JetBrains)
+  sandboxes port-forward <id|name> <port|local:remote>...
                                                Forward local ports to ports in a sandbox
 
 Observability
-  sandbox metrics <id> [--range 1h]            CPU and memory over time (15m 1h 6h 24h 7d 30d)
+  sandboxes metrics <id> [--range 1h]          CPU and memory over time (15m 1h 6h 24h 7d 30d)
   events [--sandbox <id>] [--type <type>]      Lifecycle events, newest first
   webhooks ls | create <url> [--events a,b] | test <id> | deliveries <id>
            | update <id> [--url u] [--events a,b] [--enable|--disable]
@@ -88,22 +94,23 @@ Observability
                                                Events and metrics to an OpenTelemetry endpoint
 
 Products
-  sandbox   Linux microVMs: exec, shell, files, code, previews, network, desktop, browser
-  snapshot  Saved sandboxes, disk and memory, to start or fork from
-  image     Custom images from a Dockerfile, any public or private image, or a package list
-  volume    Persistent disks to attach to sandboxes
-  job       A command in a fresh sandbox, once or on a cron schedule, with its logs
-  domain    Your own hostname for a sandbox's port, with HTTPS
-  port      A public TCP port to a sandbox: databases, game servers
-  address   A dedicated outbound address, for allow-lists
-  tunnel    A WireGuard tunnel from your own network into your sandboxes
-  network   Account-wide network settings: your own proxy, sandboxes reaching each other by name
-  Each has its own help: \`runtime sandbox help\`, \`runtime image help\`...
+  sandboxes  Linux microVMs: exec, shell, files, code, previews, network, desktop, browser
+  snapshots  Saved sandboxes, disk and memory, to start or fork from
+  images     Custom images from a Dockerfile, any public or private image, or a package list
+  volumes    Persistent disks to attach to sandboxes
+  jobs       A command in a fresh sandbox, once or on a cron schedule, with its logs
+  domains    Your own hostname for a sandbox's port, with HTTPS
+  ports      A public TCP port to a sandbox: databases, game servers
+  ips        A dedicated outbound address, for allow-lists
+  networks   Your networks: a WireGuard tunnel in, your own proxy out, sandboxes reaching
+             each other by name
+  Each has its own help: \`runtime sandboxes help\`, \`runtime images help\`...
+  The singular (\`runtime sandbox\`) is a shortcut for the same product.
 
 Every command takes --json. Keys: RUNTIME_API_KEY, or the connection from \`runtime login\`.
 Behind a proxy: HTTPS_PROXY and NO_PROXY are read, on Node and Bun alike.
 `;
-const SANDBOX_HELP = `runtime sandbox <command>
+const SANDBOX_HELP = `runtime sandboxes <command>
 
   Every <id> below can also be the sandbox's name.
 
@@ -112,7 +119,7 @@ const SANDBOX_HELP = `runtime sandbox <command>
   port-forward <id|name> <port|local:remote>...               Forward local ports to ports in it
   create [--name n] [--label k=v]... [--env K=V]... [--vcpu 2] [--memory 4096] [--disk 4096]
          [--cpu shared|reserved] [--cpu-floor <thousandths>] [--max-cost <usd>] [--max-total-cost <usd>]
-         [--timeout <seconds>] [--on-timeout pause|stop] [--trial|--paid] [--no-wait]
+         [--timeout <60-86400>] [--on-timeout pause|stop|delete] [--no-wait]
          [--no-internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
          [--image <name:tag|imageId> | --snapshot <snapshotId>] [--volume <volumeId>:/data[:snapshot]]...
          [--idle-pause <seconds>] [--no-auto-wake] [--persistent] [--get-or-create]
@@ -123,7 +130,9 @@ const SANDBOX_HELP = `runtime sandbox <command>
                                               Run and stream output; exits with its code
   spawn <id> [--pty] -- <command...>          Start in the background; prints a process id
   ps <id>                                     Running and recent processes
-  logs <id> <processId> [-f]                  A process's output so far; -f follows it to the end
+  logs <id> <processId> [-f] [--raw]          A process's output so far; -f follows it to the end;
+                                              on a terminal control characters show as \\uXXXX
+                                              unless --raw
   kill <id> <processId> [--signal SIGTERM]
   shell <id> [--command "bash -l"]            An interactive terminal
   cp <src> <dst>                              Copy files or directories; name a sandbox
@@ -144,7 +153,7 @@ const SANDBOX_HELP = `runtime sandbox <command>
   update <id> [--name n] [--label k=v]... [--env K=V]... [--unset-env K]... [--idle-pause <seconds>] [--auto-wake on|off]
               [--persistent on|off] [--max-total-cost <usd>|none]
                                               Change its settings; persistent keeps it running until stopped
-  snapshot <id> [--name n] [--retention days] Keep its whole machine; prints the snapshot id
+  snapshot <id> [--name n] [--retention days|credit] Keep its whole machine; prints the snapshot id
   mount <id> <s3|r2|gcs>://<bucket>[/prefix] <path> [--secret NAME] [--region r]
         [--endpoint https://...] [--account-id id] [--read-only]
                                               Your bucket as a directory; the proxy signs, the sandbox never sees the key
@@ -152,7 +161,7 @@ const SANDBOX_HELP = `runtime sandbox <command>
   tailscale up <id> --auth-key-secret NAME [--hostname h] [--tag tag:x]...
                                               Join your tailnet (paid); the key is a secret set with --jobs
   tailscale status <id> | tailscale down <id> Its tailnet address; take it off the tailnet
-  fork <id> [--count 3] [--name n] [--keep-snapshot] [--trial|--paid]
+  fork <id> [--count 3] [--name n] [--keep-snapshot]
                                               Copies of it as it is now, running; prints their ids
   run-code <id> <file|-> [--lang python|javascript|typescript|r|java|bash|go] [--context c] [--out-dir .]
                                               Run a notebook-style cell; charts saved as PNG
@@ -188,10 +197,10 @@ const SANDBOX_HELP = `runtime sandbox <command>
                                               Chromium for CDP agents: prints its cdpUrl
 
 Examples
-  id=$(runtime sandbox create)
-  runtime sandbox cp ./invoice.py $id:/workspace/invoice.py
-  runtime sandbox exec $id -- python3 /workspace/invoice.py
-  runtime sandbox stop $id
+  id=$(runtime sandboxes create)
+  runtime sandboxes cp ./invoice.py $id:/workspace/invoice.py
+  runtime sandboxes exec $id -- python3 /workspace/invoice.py
+  runtime sandboxes stop $id
 `;
 /** A command's options. Reading one its parse() did not declare is a bug in
  * this file, and says so, so a test that runs the command finds it. */
@@ -270,6 +279,8 @@ function unknownOption(name, known) {
 }
 const flag = (args, name) => args.flags.get(name)?.at(-1);
 const has = (args, name) => args.flags.get(name)?.at(-1) === "true";
+/** Days, or the word `credit` for null: kept while the account has credit. */
+const daysOrCredit = (args, name) => flag(args, name) === "credit" ? null : integer(args, name);
 const integer = (args, name) => {
     const value = flag(args, name);
     if (value === undefined)
@@ -360,16 +371,15 @@ const COMMANDS = [
     "support",
     "docs",
     "mcp",
-    "sandbox",
-    "snapshot",
-    "image",
-    "volume",
-    "job",
-    "domain",
-    "port",
-    "address",
-    "tunnel",
-    "network",
+    "sandboxes",
+    "snapshots",
+    "images",
+    "volumes",
+    "jobs",
+    "domains",
+    "ports",
+    "ips",
+    "networks",
     "webhooks",
     "otel",
     "events",
@@ -378,30 +388,20 @@ const COMMANDS = [
 ];
 /** Commands with a help of their own: `runtime <command> help`. */
 const OWN_HELP = [
-    "sandbox",
     "sandboxes",
     "sbx",
-    "snapshot",
     "snapshots",
-    "image",
     "images",
-    "volume",
     "volumes",
-    "job",
     "jobs",
     "keys",
     "webhooks",
     "webhook",
     "billing",
-    "domain",
     "domains",
-    "port",
     "ports",
-    "address",
-    "addresses",
-    "tunnel",
-    "tunnels",
-    "network",
+    "ips",
+    "networks",
 ];
 /** Sandbox commands that once sat at the top level. */
 const SANDBOX_MOVED = ["run", "ssh", "port-forward", "forward"];
@@ -506,6 +506,14 @@ function table(rows) {
         .trimEnd())
         .join("\n");
 }
+/** When a sandbox ends by itself (0300, 0381). A paid-ahead lease, expiresAt,
+ * is not its time limit; only an older server, which sends no endsAt, gives
+ * the end of a limited sandbox's time as expiresAt. */
+function sandboxEnd(info) {
+    if (info.endsAt === null || (info.endsAt === undefined && !info.timeoutSeconds))
+        return "no limit";
+    return info.endsAt ?? info.expiresAt ?? "-";
+}
 function describe(info) {
     return table([
         ["id", info.id],
@@ -515,19 +523,9 @@ function describe(info) {
             "shape",
             `${info.vcpu} vCPU, ${info.memoryMiB} MiB memory, ${info.diskMiB} MiB disk (${info.cpu})`,
         ],
-        ["funding", info.funding],
         ["region", info.region],
-        // A sandbox with no time limit runs while it works (0300): endsAt is
-        // null. An older server sends no endsAt; its expiresAt was the end.
         ["time limit", info.timeoutSeconds ? `${info.timeoutSeconds} s` : "none"],
-        [
-            "ends",
-            info.endsAt === null
-                ? info.state === "running"
-                    ? "when idle, stopped or out of credit"
-                    : "-"
-                : (info.endsAt ?? info.expiresAt ?? "-"),
-        ],
+        ["ends", sandboxEnd(info)],
         ["at its end", info.onLeaseEnd ?? "-"],
         // Why a sandbox is no longer running (troubleshooting.md, "A sandbox
         // stopped on its own"); `get` left both out until 30 September 2026.
@@ -560,17 +558,22 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     // Only what comes before -- is the CLI's: a --json after it is the
     // command's, whether or not the CLI was given its own.
     const dash = argv.indexOf("--");
-    const [first, ...remaining] = argv.filter((arg, index) => arg !== "--json" || (dash !== -1 && index > dash));
+    // CLOUD.md section 4: the plural names the product, the singular is a
+    // typing shortcut, and an old word works for 30 days with a warning.
+    const words = productWords(argv.filter((arg, index) => arg !== "--json" || (dash !== -1 && index > dash)));
+    if (words.warning)
+        out.error(`Warning: ${named(words.warning)}`);
+    const [first, ...remaining] = words.argv;
     // Sandbox is one product of several, so its commands live under it
-    // (AGENTS.md, 23 September 2026): `runtime sandbox run`, `sandbox ssh` and
+    // (AGENTS.md, 23 September 2026): `runtime sandboxes run`, `sandbox ssh` and
     // `sandbox port-forward`. The old top-level forms were removed, not aliased.
     if (first && SANDBOX_MOVED.includes(first))
-        throw usage(`\`${me} ${first}\` is now \`${me} sandbox ${first === "forward" ? "port-forward" : first}\`.`);
+        throw usage(`\`${me} ${first}\` is now \`${me} sandboxes ${first === "forward" ? "port-forward" : first}\`.`);
     const nested = (first === "sandbox" || first === "sandboxes" || first === "sbx") &&
         SANDBOX_MOVED.includes(remaining[0] ?? "");
     const command = nested ? remaining[0] : first;
     const rest = nested ? remaining.slice(1) : remaining;
-    // `runtime sandbox create --help` is how an agent asks what a command takes:
+    // `runtime sandboxes create --help` is how an agent asks what a command takes:
     // answer with the product's help, never by running the command.
     const cut = remaining.indexOf("--");
     const asked = (cut < 0 ? remaining : remaining.slice(0, cut)).some((arg) => arg === "--help" || arg === "-h") ||
@@ -603,10 +606,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             ? JSON.stringify({ connected, usage: HELP })
             : `Runtime Cloud ${VERSION}. ${start}
 
-  ${me} sandbox run -- python3 < invoice.py
+  ${me} sandboxes run -- python3 < invoice.py
                                    Run a local invoice script, then stop the sandbox
-  ${me} sandbox create                   A sandbox that stays; prints its id
-  ${me} sandbox exec <id> -- <command>   Run in it
+  ${me} sandboxes create                 A sandbox that stays; prints its id
+  ${me} sandboxes exec <id> -- <command> Run in it
   ${me} help                             Everything else
 `);
         return 0;
@@ -616,14 +619,15 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "run") {
-        const args = parse(rest, [...CREATE_FLAGS, "keep"], [...CREATE_VALUES, "cwd", "env"], `${me} sandbox run -- python3 < invoice.py`);
+        const args = parse(rest, [...CREATE_FLAGS, "keep"], [...CREATE_VALUES, "cwd", "env"], `${me} sandboxes run -- python3 < invoice.py`);
         const commandLine = args.rest ?? args.positional;
         if (!commandLine.length)
-            throw usage(`Give the command after --: ${me} sandbox run -- python3 < invoice.py`);
+            throw usage(`Give the command after --: ${me} sandboxes run -- python3 < invoice.py`);
         const runtime = await client(env);
         const timeout = integer(args, "timeout");
         const { timeoutSeconds: _lease, ...input } = createInput(args);
-        const sbx = await runtime.sandboxes.create(input, { onCapacityWait: waiting(out) });
+        const onCapacityWait = waiting(out);
+        const sbx = await withVolumeRelease((options) => runtime.sandboxes.create(input, { ...options, onCapacityWait }), out);
         let cleanup;
         // SIGINT and normal completion share one stop. Keep an absolute deadline
         // across the stop retries and final state check, so cleanup cannot hang.
@@ -642,7 +646,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
                     code: "cleanup_failed",
                     status: 0,
                     message: `Could not confirm that sandbox ${sbx.id} stopped. ${error instanceof Error ? error.message : String(error)}`,
-                    hint: `Check it and retry cleanup with: ${me} sandbox stop ${sbx.id}`,
+                    hint: `Check it and retry cleanup with: ${me} sandboxes stop ${sbx.id}`,
                     cause: error,
                 }), out.json));
                 return false;
@@ -658,7 +662,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         finally {
             try {
                 if (has(args, "keep"))
-                    out.error(`Kept sandbox ${sbx.id}. Run more with: ${me} sandbox exec ${sbx.id} -- <command>`);
+                    out.error(`Kept sandbox ${sbx.id}. Run more with: ${me} sandboxes exec ${sbx.id} -- <command>`);
                 else if (!(await stop()) && code === 0)
                     code = 1;
             }
@@ -881,7 +885,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "billing";
         const origins = connectionOrigins(env);
         const { claimWalletAccount, openWalletAccount } = await import("./wallet.js");
-        return billingCommand(rest, parse(rest, ["wait", "new-account", "accept-terms"], []), out, () => client(env), undefined, {
+        return billingCommand(rest, parse(rest, ["wait", "new-account", "accept-terms"], ["below", "amount", "monthly"]), out, () => client(env), undefined, {
             open: (input) => {
                 checkBrowserOrigins(origins);
                 return openWalletAccount(input, { authUrl: origins.auth });
@@ -905,21 +909,24 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         });
     }
     if (command === "referrals") {
+        parse(rest, [], []);
         const r = await (await client(env)).referrals.get();
         const usd = (micros) => `$${(Number(BigInt(micros) / 10000n) / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
         print([
             `Your link: ${r.link}`,
             "",
-            `When a company signs up with it and makes its first top-up of ${usd(r.minPurchaseMicros)} or more,`,
-            `you each get credit equal to that top-up: at least ${usd(r.rewardMicros)}, at most ${usd(r.maxRewardMicros)}`,
-            `(up to ${usd(r.yearlyCapMicros)} a year for you).`,
+            `A company that signs up with it has each payment in its first ${r.windowDays} days matched, up to ${usd(r.maxRewardMicros)},`,
+            `and you get the same; its first payment of ${usd(r.minPurchaseMicros)} or more gives each of you at least ${usd(r.rewardMicros)}.`,
+            `Then for ${r.shareMonths} months you earn ${r.shareBasisPoints / 100}% of what it spends from credit it paid for`,
+            `(up to ${usd(r.yearlyCapMicros)} a year for you, matches and share together).`,
             ...(r.enabled ? [] : ["The program is paused: new sign-ups are not counted right now."]),
             "",
             table([
                 ["signed up", String(r.signedUp)],
-                ["waiting for a first top-up", String(r.pending)],
-                ["paid", String(r.paid)],
+                ["waiting for a first payment", String(r.pending)],
+                ["paying", String(r.payingCompanies)],
                 ["earned", usd(r.earnedMicros)],
+                ["of which share", usd(r.shareEarnedMicros)],
                 [`left this year (${r.year})`, usd(r.capRemainingMicros)],
             ]),
         ].join("\n"), r);
@@ -1001,7 +1008,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         ]);
         print(rows.length
             ? table([["ID", "PRODUCT", "NAME", "STATE", "CREATED"], ...rows])
-            : "Nothing yet. Start with: runtime sandbox create", items);
+            : "Nothing yet. Start with: runtime sandboxes create", items);
         return 0;
     }
     if (command === "ssh") {
@@ -1032,11 +1039,13 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "job";
         return jobCommand(rest, env, out);
     }
-    const networkProduct = { domains: "domain", ports: "port", addresses: "address", tunnels: "tunnel" }[command] ??
-        command;
-    if (NETWORK_PRODUCTS.includes(networkProduct)) {
+    // WireGuard is inside networks: `runtime networks wireguard peer add`.
+    const wireguard = command === "networks" && rest[0] === "wireguard";
+    const networkProduct = wireguard ? "wireguard" : command;
+    const networkRest = wireguard ? rest.slice(1) : rest;
+    if (command !== "wireguard" && NETWORK_PRODUCTS.includes(networkProduct)) {
         product = networkProduct;
-        return networkProductCommand(networkProduct, rest, parse(rest, ["ipv6"], ["sandbox", "subnet", "public-key", "route", "out", "host", "secret"]), out, () => client(env));
+        return networkProductCommand(networkProduct, networkRest, parse(networkRest, ["ipv6"], ["sandbox", "subnet", "public-key", "route", "out", "host", "secret"]), out, () => client(env));
     }
     throw unknown("command", command, COMMANDS);
 }
@@ -1112,6 +1121,43 @@ function allowanceRows(allowances) {
         `${amount(a.left)} of ${amount(a.quantity)} ${a.unit}s left`,
     ]);
 }
+/** What Runtime for Startups includes as `runtime usage` says it, in the
+ * console's words: machine time left of what it gave, storage as the GB kept
+ * free each month and the GB kept now, and what it runs at once. */
+function potRows(pot, limits) {
+    const amount = (n) => n.toLocaleString("en-US", { maximumFractionDigits: 1 });
+    const day = (iso) => {
+        const at = new Date(iso);
+        const month = at.toLocaleString("en-US", { month: "short", timeZone: "UTC" });
+        return `${at.getUTCDate()} ${month} ${at.getUTCFullYear()}`;
+    };
+    const NAMES = {
+        "machine-cpu": "vCPU-hours",
+        "machine-memory": "memory",
+        "saved-copies": "saved copies kept free",
+        disks: "volumes",
+    };
+    const ORDER = ["machine-cpu", "machine-memory", "saved-copies", "disks"];
+    const rank = (pool) => (ORDER.includes(pool) ? ORDER.indexOf(pool) : ORDER.length);
+    const rows = [...pot]
+        .sort((a, b) => rank(a.pool) - rank(b.pool))
+        .map((p) => {
+        const name = `${p.period === "month" ? "Runtime for Startups" : "startup hours"}: ${NAMES[p.pool] ?? p.pool.replace(/-/g, " ")}`;
+        const until = p.expiresAt ? ` until ${day(p.expiresAt)}` : "";
+        if (p.period === "month") {
+            const kept = p.keptGB ?? 0;
+            const over = kept > p.quantity ? `; past ${amount(p.quantity)} GB bills at the published rate` : "";
+            return [
+                name,
+                `${amount(p.quantity)} GB kept free${until} · ${amount(kept)} GB kept now${over}`,
+            ];
+        }
+        return [name, `${amount(p.left ?? 0)} of ${amount(p.quantity)} ${p.unit}s left${until}`];
+    });
+    if (limits)
+        rows.push(["Runtime for Startups: sandboxes at once", amount(limits.sandboxesAtOnce)], ["Runtime for Startups: image builds at once", amount(limits.buildsAtOnce)]);
+    return rows;
+}
 /** What a pilot gives, as `runtime whoami` and `runtime limits` say it: the
  * sandboxes it runs free and until when, past which credit does not run
  * them. */
@@ -1155,6 +1201,16 @@ function usageSummary(u) {
         rows.push(["free time", trialLeft(u.trial)]);
     if (u.allowances)
         rows.push(...allowanceRows(u.allowances));
+    // Only a data property is an older server's answer. Do not invoke SDK
+    // compatibility getters when a server sends neither generation of fields.
+    const pot = "startupIncluded" in u
+        ? u.startupIncluded
+        : Object.getOwnPropertyDescriptor(u, "pot")?.value;
+    const potLimits = "startupLimits" in u
+        ? u.startupLimits
+        : Object.getOwnPropertyDescriptor(u, "potLimits")?.value;
+    if (pot?.length || potLimits)
+        rows.push(...potRows(pot ?? [], potLimits));
     if (u.pilot)
         rows.push(["pilot sandbox hours", pilotLeft(u.pilot)]);
     if (u.outbound) {
@@ -1233,10 +1289,21 @@ async function outputSoFar(runtime, sandboxId, processId) {
         processId,
         state: latest?.state ?? null,
         exitCode: latest?.exitCode ?? null,
+        ...(latest?.outOfMemory ? { outOfMemory: latest.outOfMemory } : {}),
         truncated,
         chunks,
     };
 }
+/** What a person reads when the sandbox's out-of-memory killer ended a
+ * command: the API's message and hint, on standard error. A bare exit -9 (or
+ * 137) said nothing of memory until 9 October 2026. */
+export function outOfMemoryLines(memory) {
+    // The words come from an answer, not this CLI: escaped like a log line, so
+    // nothing in them can drive the terminal (terminal.ts).
+    return memory && typeof memory.message === "string" && typeof memory.hint === "string"
+        ? `runtime: ${terminalSafe(memory.message)}\nHint: ${terminalSafe(memory.hint)}`
+        : undefined;
+}
 /** Dollars from integer microdollars: cents from a dollar up, four places
  * below one, and every place below a hundredth of a cent, so a short trial
  * test never reads as $0.0000. */
@@ -1309,36 +1376,60 @@ const longDate = (iso) => new Date(iso).toLocaleDateString("en-GB", {
     year: "numeric",
     timeZone: "UTC",
 });
-/** One line on the switching credit: how to claim it, or what it did. A
- * switch already on record is named with its provider and date, so it never
+/** One line on the welcome match: while it is open, how much of it credit
+ * added now can still get; after, what it got. Undefined when there is
+ * nothing to say: the offer ended unused. */
+function welcomeLine(summary) {
+    const w = summary.welcome;
+    // A server from before the welcome match (0433) answers without it.
+    if (!w)
+        return undefined;
+    const whole = (micros) => dollars(micros).replace(/\.00$/, "");
+    if (w.eligible) {
+        // A server from before 0435 answers without what is left.
+        const left = w.leftMicros ?? (BigInt(w.maxMicros) - BigInt(w.creditMicros)).toString();
+        return BigInt(w.creditMicros) > 0n
+            ? `${whole(w.creditMicros)} of ${whole(w.maxMicros)} matched so far; credit you add by ${longDate(w.endsAt)} is matched, up to ${whole(left)} more.`
+            : `Credit you add by ${longDate(w.endsAt)} is matched, up to ${whole(w.maxMicros)} in total.`;
+    }
+    switch (w.status) {
+        case "paid":
+            return `Your credit was matched: ${dollars(w.creditMicros)} of credit.`;
+        case "superseded":
+            return "Your payments are matched by your referral instead, which is never less.";
+        case "reversed":
+            return "The payments that were matched were refunded, so the match was taken back.";
+        case "refused":
+            return "Your credit was not matched. Ask support if you think that is wrong.";
+    }
+    return undefined;
+}
+/** What `switch` says: the switch on record, if any, and the welcome match.
+ * A switch already on record is named with its provider and date, so it never
  * reads as if this command recorded it, or recorded the provider it names. */
 function switchingLine(summary, provider) {
-    const cap = dollars(summary.maxMicros);
     const sw = summary.switch;
+    const welcome = welcomeLine(summary);
     if (!sw) {
-        if (!summary.eligible || !provider)
-            return undefined;
-        return `Switching from ${RIVAL_NAMES[provider]}? Run \`${me} switch --from ${provider}\` before your first top-up and we match that top-up, up to ${cap}.`;
+        if (!provider || !summary.eligible)
+            return welcome;
+        return [
+            `Switching from ${RIVAL_NAMES[provider]}? Run \`${me} switch --from ${provider}\` before your first top-up to record it.`,
+            welcome,
+        ]
+            .filter(Boolean)
+            .join(" ");
     }
     const from = RIVAL_NAMES[sw.provider];
-    const recorded = `This organization's switch from ${from} was recorded on ${longDate(sw.recordedAt)}`;
     const once = provider && provider !== sw.provider
         ? ` A switch is recorded once, so it stays ${from}, not ${RIVAL_NAMES[provider]}.`
         : "";
-    switch (sw.status) {
-        case "pending":
-            return `${recorded}: its first top-up is matched, up to ${cap}, once the payment settles.${once}`;
-        case "paid":
-            return `${recorded} and matched its first top-up: ${dollars(sw.creditMicros)} of credit.${once}`;
-        case "superseded":
-            return `${recorded}; its first top-up was matched by a referral instead, which is never less than the switching credit.${once}`;
-        case "reversed":
-            return `${recorded}; the top-up it matched was refunded, so the credit was taken back.${once}`;
-        case "refused":
-            return sw.refusedReason === "program_off"
-                ? `${recorded}; the switching credit was paused when its first top-up arrived.${once}`
-                : `${recorded}; its first top-up was not matched. Ask support if you think that is wrong.${once}`;
-    }
+    return [
+        `This organization's switch from ${from} was recorded on ${longDate(sw.recordedAt)}.${once}`,
+        welcome,
+    ]
+        .filter(Boolean)
+        .join(" ");
 }
 /** Running time in the largest unit that keeps it above zero: a short
  * trial test is seconds, not "0 hours". */
@@ -1378,10 +1469,13 @@ async function switching(command, argv, env, out) {
     if (command === "switch") {
         if (!from) {
             const summary = await api.get();
-            print(switchingLine(summary) ??
-                (summary.eligible
-                    ? `Moving from a rival? Run \`${me} switch --from <provider>\` (${summary.providers.join(", ")}) before your first top-up, and that top-up is matched, up to ${dollars(summary.maxMicros)}.`
-                    : "The switching credit matches a first top-up, and this organization has made one already."), summary);
+            const record = summary.eligible
+                ? `Moving from a rival? Run \`${me} switch --from <provider>\` (${summary.providers.join(", ")}) before your first top-up to record it.`
+                : undefined;
+            print((summary.switch
+                ? switchingLine(summary)
+                : [record, welcomeLine(summary)].filter(Boolean).join(" ")) ||
+                "A switch is recorded before the first top-up, and this organization has made one already.", summary);
             return 0;
         }
         const provider = SWITCH_FROM[from];
@@ -1389,7 +1483,7 @@ async function switching(command, argv, env, out) {
             throw unknown("provider", from, Object.keys(RIVAL_NAMES));
         const summary = await api.record({ provider });
         print([
-            `Recorded: switching from ${RIVAL_NAMES[provider]}. ${switchingLine(summary) ?? ""}`.trim(),
+            `Recorded: switching from ${RIVAL_NAMES[provider]}. ${welcomeLine(summary) ?? ""}`.trim(),
             ...dropInLines(provider),
         ].join("\n"), summary);
         return 0;
@@ -1507,9 +1601,9 @@ async function sandbox(argv, env, out) {
     switch (verb) {
         case "create": {
             const args = parse(rest, CREATE_FLAGS, CREATE_VALUES);
-            const sbx = await runtime.sandboxes.create(createInput(args), {
-                onCapacityWait: waiting(out),
-            });
+            const input = createInput(args);
+            const onCapacityWait = waiting(out);
+            const sbx = await withVolumeRelease((options) => runtime.sandboxes.create(input, { ...options, onCapacityWait }), out);
             print(sbx.id, sbx.info);
             return 0;
         }
@@ -1534,24 +1628,21 @@ async function sandbox(argv, env, out) {
                 ? null
                 : await runtime.sandboxes.list({ state: ["stopped"], limit: 50 });
             const stopped = hidden?.data.length
-                ? `${hidden.data.length}${hidden.hasMore ? "+" : ""} stopped; runtime sandbox ls --all shows them.`
+                ? `${hidden.data.length}${hidden.hasMore ? "+" : ""} stopped; runtime sandboxes ls --all shows them.`
                 : "";
             const rows = all.map((s) => [
                 s.id,
                 s.info.name ?? "-",
                 s.state,
                 `${s.info.vcpu}/${s.info.memoryMiB}`,
-                s.info.funding,
-                // When it stops or pauses by itself (0381): its time limit's end, or
-                // "-" when it never will. An older server sends no endsAt.
-                (s.info.endsAt === undefined ? s.info.expiresAt : s.info.endsAt) ?? "-",
+                sandboxEnd(s.info),
             ]);
             print([
                 rows.length
-                    ? table([["ID", "NAME", "STATE", "CPU/MIB", "FUNDING", "ENDS"], ...rows])
+                    ? table([["ID", "NAME", "STATE", "CPU/MIB", "ENDS"], ...rows])
                     : stopped
                         ? "No live sandboxes."
-                        : "No sandboxes. Create one: runtime sandbox create",
+                        : "No sandboxes. Create one: runtime sandboxes create",
                 stopped,
             ]
                 .filter(Boolean)
@@ -1566,31 +1657,31 @@ async function sandbox(argv, env, out) {
         case "switch-image": {
             const args = parse(rest, ["keep-workspace"], []);
             const [id, image] = args.positional;
-            const sbx = await use(need(id, `a sandbox, e.g. ${me} sandbox switch-image <id> app:v2 --keep-workspace`));
+            const sbx = await use(need(id, `a sandbox, e.g. ${me} sandboxes switch-image <id> app:v2 --keep-workspace`));
             if (!args.flags.has("keep-workspace"))
-                throw usage(`A switch keeps only /workspace (your home), volumes, env and previews; processes restart and everything else on its disk is lost. Add --keep-workspace to say so, or snapshot it first (${me} sandbox snapshot ${sbx.id}) to keep everything.`);
+                throw usage(`A switch keeps only /workspace (your home), volumes, env and previews; processes restart and everything else on its disk is lost. Add --keep-workspace to say so, or snapshot it first (${me} sandboxes snapshot ${sbx.id}) to keep everything.`);
             await sbx.switchImage(need(image, "an image, e.g. app:v2"), { keep: "workspace" });
             print(describe(sbx.info), sbx.info);
             return 0;
         }
         case "resize": {
             const args = parse(rest, ["restart"], ["vcpu", "memory"]);
-            const sbx = await use(need(args.positional[0], `a sandbox, e.g. ${me} sandbox resize <id> --memory 4096 --restart`));
+            const sbx = await use(need(args.positional[0], `a sandbox, e.g. ${me} sandboxes resize <id> --memory 4096 --restart`));
             const size = {
                 ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
                 ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
             };
             if (size.vcpu === undefined && size.memoryMiB === undefined)
-                throw usage(`Name a new size, e.g. ${me} sandbox resize ${sbx.id} --memory 4096 --restart`);
+                throw usage(`Name a new size, e.g. ${me} sandboxes resize ${sbx.id} --memory 4096 --restart`);
             if (!args.flags.has("restart"))
-                throw usage(`A resize restarts it: its whole disk stays and its programs stop. Add --restart to say so, or snapshot it first (${me} sandbox snapshot ${sbx.id}) to keep its memory too.`);
+                throw usage(`A resize restarts it: its whole disk stays and its programs stop. Add --restart to say so, or snapshot it first (${me} sandboxes snapshot ${sbx.id}) to keep its memory too.`);
             await sbx.resize(size, { restart: true });
             print(describe(sbx.info), sbx.info);
             return 0;
         }
         case "rm":
         case "delete": {
-            const sbx = await use(need(rest[0], `a sandbox, e.g. ${me} sandbox rm <id>`));
+            const sbx = await use(need(rest[0], `a sandbox, e.g. ${me} sandboxes rm <id>`));
             const gone = await sbx.delete();
             print(`${gone.id} deleted`, gone);
             return 0;
@@ -1692,15 +1783,15 @@ async function sandbox(argv, env, out) {
                 print(gone.left ? "Left the tailnet." : "Not on a tailnet.", gone);
                 return 0;
             }
-            throw usage("runtime sandbox tailscale up|status|down <id>");
+            throw usage("runtime sandboxes tailscale up|status|down <id>");
         }
         case "snapshot": {
             const args = parse(rest, [], ["name", "retention"]);
             const sbx = await get(args.positional[0]);
             const snapshot = await sbx.snapshot({
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
-                ...(integer(args, "retention") !== undefined
-                    ? { retentionDays: integer(args, "retention") }
+                ...(daysOrCredit(args, "retention") !== undefined
+                    ? { retentionDays: daysOrCredit(args, "retention") }
                     : {}),
             });
             print(snapshot.id, snapshot);
@@ -1772,26 +1863,26 @@ async function sandbox(argv, env, out) {
         }
         case "extend": {
             const sbx = await get(rest[0]);
-            const seconds = Number(need(rest[1], "seconds, e.g. runtime sandbox extend <id> 600"));
+            const seconds = Number(need(rest[1], "seconds, e.g. runtime sandboxes extend <id> 600"));
             await sbx.extend(seconds);
-            print(sbx.info.endsAt === null
+            print(sandboxEnd(sbx.info) === "no limit"
                 ? `${sbx.id} has no time limit: it runs while it works, so nothing was extended`
-                : `${sbx.id} now ends at ${sbx.info.endsAt ?? sbx.info.expiresAt}`, sbx.info);
+                : `${sbx.id} now ends at ${sandboxEnd(sbx.info)}`, sbx.info);
             return 0;
         }
         case "exec": {
-            const args = parse(rest, [], ["cwd", "env", "timeout"], `${me} sandbox exec <id> -- ls -la`);
+            const args = parse(rest, [], ["cwd", "env", "timeout"], `${me} sandboxes exec <id> -- ls -la`);
             const command = args.rest ?? args.positional.slice(1);
             if (!command.length)
-                throw usage("Give the command after --: runtime sandbox exec <id> -- ls -la");
+                throw usage("Give the command after --: runtime sandboxes exec <id> -- ls -la");
             const sbx = await use(args.positional[0]);
             return execute(sbx, command, args, out, integer(args, "timeout"));
         }
         case "spawn": {
-            const args = parse(rest, ["pty"], ["cwd", "env"], `${me} sandbox spawn <id> -- npm run dev`);
+            const args = parse(rest, ["pty"], ["cwd", "env"], `${me} sandboxes spawn <id> -- npm run dev`);
             const command = args.rest ?? [];
             if (!command.length)
-                throw usage("Give the command after --: runtime sandbox spawn <id> -- npm run dev");
+                throw usage("Give the command after --: runtime sandboxes spawn <id> -- npm run dev");
             const sbx = await use(args.positional[0]);
             const proc = await sbx.spawn(command.length === 1 ? command[0] : command, {
                 ...(has(args, "pty") ? { pty: { cols: 120, rows: 40 } } : {}),
@@ -1807,36 +1898,54 @@ async function sandbox(argv, env, out) {
             print(list.length
                 ? table([
                     ["PROCESS", "STATE", "EXIT", "COMMAND"],
-                    ...list.map((p) => [p.id, p.state, String(p.exitCode ?? "-"), p.command]),
+                    // The command line is the guest's report: escaped, as a log is.
+                    ...list.map((p) => [
+                        terminalSafe(String(p.id)),
+                        terminalSafe(String(p.state)),
+                        `${typeof p.exitCode === "number" ? p.exitCode : "-"}${p.outOfMemory ? " (out of memory)" : ""}`,
+                        terminalSafe(String(p.command ?? "")),
+                    ]),
                 ])
                 : "No processes.", list);
+            const killed = list.find((p) => p.outOfMemory)?.outOfMemory;
+            if (killed && typeof killed.hint === "string" && !out.json)
+                out.error(`Hint: ${terminalSafe(killed.hint)}`);
             return 0;
         }
         case "logs": {
-            const args = parse(rest, ["f", "follow"], []);
+            const args = parse(rest, ["f", "follow", "raw"], []);
             const sbx = await use(args.positional[0]);
             const proc = await sbx.processes.get(need(args.positional[1], "a process id"));
+            const [stdout, stderr, shown] = [
+                logStream(process.stdout, has(args, "raw")),
+                logStream(process.stderr, has(args, "raw")),
+                logText(args),
+            ];
             if (has(args, "f") || has(args, "follow")) {
                 for await (const event of proc.output())
                     if (event.type === "stdout")
-                        process.stdout.write(event.data);
+                        stdout(event.data);
                     else if (event.type === "stderr")
-                        process.stderr.write(event.data);
+                        stderr(event.data);
                     else if (out.json)
-                        out.write(JSON.stringify(event));
+                        out.write(shown(JSON.stringify(event)));
+                    else if (event.type === "exit" && event.outOfMemory)
+                        out.error(outOfMemoryLines(event.outOfMemory));
                 return 0;
             }
             /* Without -f, what it has printed so far, then back to the prompt, as
                `docker logs` does: a server's log is read, not followed forever. */
             const so = await outputSoFar(runtime, sbx.id, proc.id);
             if (out.json) {
-                out.write(JSON.stringify(so));
+                out.write(shown(JSON.stringify(so)));
                 return 0;
             }
             for (const chunk of so.chunks)
-                (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text);
+                (chunk.stream === "stderr" ? stderr : stdout)(chunk.text);
+            if (so.outOfMemory)
+                out.error(outOfMemoryLines(so.outOfMemory));
             if (so.state === "running")
-                process.stderr.write(`[${proc.id} is still running; follow it: ${me} sandbox logs ${sbx.id} ${proc.id} -f]\n`);
+                process.stderr.write(`[${proc.id} is still running; follow it: ${me} sandboxes logs ${sbx.id} ${proc.id} -f]\n`);
             return 0;
         }
         case "kill": {
@@ -1906,7 +2015,7 @@ async function sandbox(argv, env, out) {
             return runCode(await use(rest[0]), rest.slice(1), out);
         case "preview": {
             if (rest[0] === "rotate") {
-                const port = portOf(rest[2], "runtime sandbox preview rotate <id> 3000");
+                const port = portOf(rest[2], "runtime sandboxes preview rotate <id> 3000");
                 const sbx = await use(rest[1]);
                 const preview = await sbx.previews.rotate(port);
                 print(preview.visibility === "public"
@@ -1915,7 +2024,7 @@ async function sandbox(argv, env, out) {
                 return 0;
             }
             const args = parse(rest, ["public"], ["ttl"]);
-            const port = portOf(args.positional[1], "runtime sandbox preview <id> 3000");
+            const port = portOf(args.positional[1], "runtime sandboxes preview <id> 3000");
             const sbx = await use(args.positional[0]);
             const preview = await sbx.previews.create(port, {
                 ...(has(args, "public") ? { visibility: "public" } : {}),
@@ -1935,7 +2044,7 @@ async function sandbox(argv, env, out) {
                     ["PORT", "VISIBILITY", "URL"],
                     ...list.map((p) => [String(p.port), p.visibility, p.url]),
                 ])
-                : "No shared ports. Share one: runtime sandbox preview <id> 3000", list);
+                : "No shared ports. Share one: runtime sandboxes preview <id> 3000", list);
             return 0;
         }
         case "session": {
@@ -1952,17 +2061,17 @@ async function sandbox(argv, env, out) {
                             one.origins.join(",") || "-",
                         ]),
                     ])
-                    : "No sessions. Make one: runtime sandbox session create <id> --origin https://app.example.com", list);
+                    : "No sessions. Make one: runtime sandboxes session create <id> --origin https://app.example.com", list);
                 return 0;
             }
             if (verb === "revoke") {
-                const sessionId = need(rest[2], "a session id: runtime sandbox session revoke <id> <session-id>");
+                const sessionId = need(rest[2], "a session id: runtime sandboxes session revoke <id> <session-id>");
                 const ended = await (await use(rest[1])).sessions.revoke(sessionId);
                 print(`Session ${ended.id} ended.`, ended);
                 return 0;
             }
             if (verb !== "create")
-                throw usage("runtime sandbox session create <id> [--origin <url>]..., session ls <id>, or session revoke <id> <session-id>");
+                throw usage("runtime sandboxes session create <id> [--origin <url>]..., session ls <id>, or session revoke <id> <session-id>");
             const args = parse(rest.slice(1), [], ["origin", "ttl", "name"]);
             const origins = args.flags.get("origin") ?? [];
             const ttl = integer(args, "ttl");
@@ -1976,7 +2085,7 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "unshare": {
-            const port = portOf(rest[1], "runtime sandbox unshare <id> 3000");
+            const port = portOf(rest[1], "runtime sandboxes unshare <id> 3000");
             const sbx = await use(rest[0]);
             print(`Port ${port} is no longer shared.`, await sbx.previews.delete(port));
             return 0;
@@ -2174,7 +2283,7 @@ read = readSecret) {
         }
         if (!hosts.length) {
             const saved = await runtime.secrets.set(name, { value, jobs: true });
-            print(`Stored ${name} for jobs, version ${saved.jobs.version}. Bind it: ${me} job create ... --secret ${name}`, saved);
+            print(`Stored ${name} for jobs, version ${saved.jobs.version}. Bind it: ${me} jobs create ... --secret ${name}`, saved);
             return 0;
         }
         const header = flag(args, "header");
@@ -2193,14 +2302,14 @@ read = readSecret) {
             `Stored ${saved.name}. Sandboxes see ${saved.name}=${saved.placeholder}.`,
             saved.header
                 ? `Requests to ${saved.hosts.join(", ")} get ${saved.header}: ${saved.format ?? "{value}"} over HTTPS.`
-                : `Over HTTPS to ${saved.hosts.join(", ")}, the placeholder becomes the value in the URL and headers.`,
+                : `Over HTTPS to ${saved.hosts.join(", ")}, the placeholder becomes the value in the Authorization header or another credential header (x-api-key, x-goog-api-key); in the URL it stays a placeholder.`,
             ...(saved.rules?.length ? [`Only these requests get it: ${ruleText(saved.rules)}.`] : []),
             ...(saved.enforced
                 ? []
                 : ["A host is catching up; running sandboxes have it within a minute."]),
             ...(saved.jobs
                 ? [
-                    `Also stored for jobs, version ${saved.jobs.version}: --secret ${saved.name} on ${me} job create.`,
+                    `Also stored for jobs, version ${saved.jobs.version}: --secret ${saved.name} on ${me} jobs create.`,
                 ]
                 : []),
         ].join("\n"), saved);
@@ -2339,7 +2448,7 @@ async function desktop(sbx, argv, out) {
             return 0;
         }
     }
-    throw usage(`${me} sandbox desktop <id> start|stop|screenshot|open|click|type|press|windows|record`);
+    throw usage(`${me} sandboxes desktop <id> start|stop|screenshot|open|click|type|press|windows|record`);
 }
 async function browser(sbx, argv, out) {
     const [action, ...rest] = argv;
@@ -2353,7 +2462,8 @@ async function browser(sbx, argv, out) {
                 ...(integer(args, "height") !== undefined ? { height: integer(args, "height") } : {}),
             });
             print(`${started.version}${started.headless ? "" : `, on the desktop: ${started.streamUrl}`}\n` +
-                `CDP: ${started.cdpUrl}\n(private; it expires ${started.expiresAt ?? "never"})`, started);
+                `CDP: ${started.cdpUrl}\n(private; it expires ${started.expiresAt ?? "never"})` +
+                (started.hint ? `\n${started.hint}` : ""), started);
             return 0;
         }
         case "get":
@@ -2368,7 +2478,7 @@ async function browser(sbx, argv, out) {
             return 0;
         }
     }
-    throw usage(`${me} sandbox browser <id> start [--headed]|get|stop`);
+    throw usage(`${me} sandboxes browser <id> start [--headed]|get|stop`);
 }
 const KEYS_HELP = `runtime keys <command>
 
@@ -2541,14 +2651,14 @@ async function keys(argv, env, out) {
     await confirm();
     return 0;
 }
-const SNAPSHOT_HELP = `runtime snapshot <command>
+const SNAPSHOT_HELP = `runtime snapshots <command>
 
   ls [--sandbox <id>] [--name n]              Your snapshots
   get <id>                                    One snapshot
-  extend <id> <days>                          Keep it longer
+  extend <id> <days|credit>                   Keep it longer; credit: while you have credit
   rm <id>                                     Delete it
-  Take one with \`runtime sandbox snapshot <sandboxId>\`; start a sandbox from it
-  with \`runtime sandbox create --snapshot <snapshotId>\`.
+  Take one with \`runtime sandboxes snapshot <sandboxId>\`; start a sandbox from it
+  with \`runtime sandboxes create --snapshot <snapshotId>\`.
 `;
 async function snapshot(argv, env, out) {
     const [verb, ...rest] = argv;
@@ -2571,9 +2681,15 @@ async function snapshot(argv, env, out) {
             print(all.length
                 ? table([
                     ["ID", "NAME", "STATUS", "FROM", "EXPIRES"],
-                    ...all.map((s) => [s.id, s.name ?? "-", s.status, s.sourceSandboxId, s.expiresAt]),
+                    ...all.map((s) => [
+                        s.id,
+                        s.name ?? "-",
+                        s.status,
+                        s.sourceSandboxId,
+                        s.expiresAt ?? "with credit",
+                    ]),
                 ])
-                : "No snapshots. Take one: runtime sandbox snapshot <sandboxId>", all);
+                : "No snapshots. Take one: runtime sandboxes snapshot <sandboxId>", all);
             return 0;
         }
         case "get": {
@@ -2582,9 +2698,11 @@ async function snapshot(argv, env, out) {
             return 0;
         }
         case "extend": {
-            const days = integer(parse(rest.slice(1), [], ["days"]), "days") ?? Number(need(rest[1], "days"));
+            const word = parse(rest.slice(1), [], ["days"]);
+            const days = daysOrCredit(word, "days") ??
+                (need(rest[1], "days") === "credit" ? null : Number(need(rest[1], "days")));
             const found = await api.extend(need(rest[0], "a snapshot id"), days);
-            print(`${found.id} kept until ${found.expiresAt}`, found);
+            print(`${found.id} kept ${found.expiresAt === null ? "while you have credit" : `until ${found.expiresAt}`}`, found);
             return 0;
         }
         case "rm":
@@ -2597,7 +2715,7 @@ async function snapshot(argv, env, out) {
     }
     throw unknown("snapshot command", verb, ["ls", "get", "extend", "rm"]);
 }
-const IMAGE_HELP = `runtime image <command>
+const IMAGE_HELP = `runtime images <command>
 
   build [<folder>] [--dockerfile|-f <Dockerfile>] | --from <image> | --pip <pkg>... --apt <pkg>... --npm <pkg>...
         [--name <name>] [--tag|-t name[:tag]]... [--target <stage>] [--build-arg K=V]... [--no-cache]
@@ -2612,8 +2730,9 @@ const IMAGE_HELP = `runtime image <command>
   ls                    Your images
   versions <name>       Every version of a name, newest first
   get <image>           One image: an id, name, name:tag or name@version
-  logs <image> [--follow]
-                        Its build log
+  logs <image> [--follow] [--raw]
+                        Its build log; on a terminal control characters
+                        show as \\uXXXX unless --raw
   tag <image> <tag>     Point a tag of the image's name at this version
   untag <image> <tag>   Take a tag off
   rm <image>            Delete that version and its tags
@@ -2624,7 +2743,7 @@ const IMAGE_HELP = `runtime image <command>
   registry set <ecr registry> --access-key-id <id>
                         Amazon ECR: the secret access key is read from standard input
   registry rm <registry>
-  Use one: runtime sandbox create --image app:latest
+  Use one: runtime sandboxes create --image app:latest
 `;
 /** Options `image build` takes with a value. */
 const IMAGE_BUILD_VALUES = [
@@ -2759,7 +2878,7 @@ read = readSecret) {
                 ])
                 : name
                     ? `No versions of ${name}.`
-                    : "No images. Build one: runtime image build --pip pandas", all);
+                    : "No images. Build one: runtime images build --pip pandas", all);
             return 0;
         }
         case "get": {
@@ -2768,13 +2887,14 @@ read = readSecret) {
             return 0;
         }
         case "logs": {
-            const args = parse(rest, ["follow", "f"], []);
+            const args = parse(rest, ["follow", "f", "raw"], []);
             const id = (await api.resolve(need(args.positional[0], "an image"))).id;
+            const shown = logText(args);
             if (has(args, "follow") || has(args, "f")) {
                 const lines = [];
-                const done = await api.followLogs(id, (line) => out.json ? lines.push(line.text) : out.write(line.text));
+                const done = await api.followLogs(id, (line) => out.json ? lines.push(line.text) : out.write(shown(line.text)));
                 if (out.json)
-                    print("", { lines, state: done.state });
+                    out.write(shown(JSON.stringify({ lines, state: done.state })));
                 return done.state === "failed" ? 1 : 0;
             }
             let after = 0;
@@ -2786,7 +2906,7 @@ read = readSecret) {
                     break;
                 after = page.nextAfter;
             }
-            print(lines.join("\n") || "(no log yet)", lines);
+            out.write(shown(out.json ? JSON.stringify(lines) : lines.join("\n") || "(no log yet)"));
             return 0;
         }
         case "tag":
@@ -2813,7 +2933,7 @@ read = readSecret) {
                         ["REGISTRY", "KIND", "USER", "SINCE"],
                         ...all.map((r) => [r.registry, r.kind, r.username, r.createdAt]),
                     ])
-                    : "No registry credentials. Store some: runtime image registry set ghcr.io --username you", all);
+                    : "No registry credentials. Store some: runtime images registry set ghcr.io --username you", all);
                 return 0;
             }
             if (action === "set") {
@@ -2853,7 +2973,7 @@ read = readSecret) {
         "registry",
     ]);
 }
-const JOB_HELP = `runtime job <command>
+const JOB_HELP = `runtime jobs <command>
 
   A job runs a command in a fresh sandbox, once or on a schedule. Each run spends
   the included usage first, then credit at the sandbox rates.
@@ -2871,14 +2991,21 @@ const JOB_HELP = `runtime job <command>
   ls                                          Your jobs: state, schedule and next run
   get <id>                                    One job, in full
   runs <id>                                   Its runs: state, exit code, when
-  logs <runId|jobId> [-f]                     A run's output (a job id: its latest run); -f follows it
+  logs <runId|jobId> [-f] [--raw]             A run's output (a job id: its latest run); -f follows it;
+                                              on a terminal control characters show as \\uXXXX
+                                              unless --raw
   pause <id> | resume <id>                    Stop or restart scheduling; a run already going finishes
+  trigger <id>                                Run it now, once; its schedule does not move, and a
+                                              paused job stays paused
+  reschedule <id> (--cron "<five fields>" [--timezone Europe/Berlin] | --at <time|now>)
+                                              A new schedule; the next run is its next time
   cancel <id>                                 End it for good and stop a run in progress
 
 Examples
-  runtime job create nightly --cron "0 3 * * *" --timezone Europe/Berlin -- python3 /workspace/report.py
-  runtime job create once --at now -- bash -lc 'echo hello from a job'
-  runtime job logs <jobId> -f
+  runtime jobs create nightly --cron "0 3 * * *" --timezone Europe/Berlin -- python3 /workspace/report.py
+  runtime jobs create once --at now -- bash -lc 'echo hello from a job'
+  runtime jobs trigger <jobId> && runtime jobs logs <jobId> -f
+  runtime jobs reschedule <jobId> --cron "30 4 * * 1-5" --timezone Europe/Berlin
 `;
 const when = (ms) => (ms == null ? "-" : new Date(ms).toISOString());
 function scheduleText(job) {
@@ -2926,13 +3053,13 @@ async function jobCommand(argv, env, out) {
                 "max-cost",
                 "max-total-cost",
                 "region",
-            ], `${me} job create <name> --cron "0 3 * * *" -- python3 -c '...'`);
+            ], `${me} jobs create <name> --cron "0 3 * * *" -- python3 -c '...'`);
             const name = need(args.positional[0], "the job's name, such as nightly-report");
             if (args.positional.length > 1)
-                throw usage(`Put the command after --: ${me} job create ${name} ... -- ${args.positional.slice(1).join(" ")}`);
+                throw usage(`Put the command after --: ${me} jobs create ${name} ... -- ${args.positional.slice(1).join(" ")}`);
             const argv = args.rest ?? [];
             if (!argv.length)
-                throw usage(`Give the command after --: ${me} job create ${name} --at now -- echo hello`);
+                throw usage(`Give the command after --: ${me} jobs create ${name} --at now -- echo hello`);
             const cron = flag(args, "cron");
             const at = flag(args, "at");
             if ((cron === undefined) === (at === undefined))
@@ -2989,7 +3116,7 @@ async function jobCommand(argv, env, out) {
                     : {}),
             });
             if (!out.json)
-                out.error(`Scheduled ${job.name}: ${scheduleText(job)}. Next run ${when(job.nextRunAt)}. Follow it: ${me} job logs ${job.id} -f`);
+                out.error(`Scheduled ${job.name}: ${scheduleText(job)}. Next run ${when(job.nextRunAt)}. Follow it: ${me} jobs logs ${job.id} -f`);
             print(job.id, job);
             return 0;
         }
@@ -3009,7 +3136,7 @@ async function jobCommand(argv, env, out) {
                         j.blockedReason ?? "-",
                     ]),
                 ])
-                : `No jobs. Schedule one: ${me} job create hello --at now -- echo hello`, all);
+                : `No jobs. Schedule one: ${me} jobs create hello --at now -- echo hello`, all);
             return 0;
         }
         case "get": {
@@ -3038,8 +3165,13 @@ async function jobCommand(argv, env, out) {
             return 0;
         }
         case "logs": {
-            const args = parse(rest, ["f", "follow"], []);
+            const args = parse(rest, ["f", "follow", "raw"], []);
             const id = need(args.positional[0], "a run id or a job id");
+            const [stdout, stderr, shown] = [
+                logStream(process.stdout, has(args, "raw")),
+                logStream(process.stderr, has(args, "raw")),
+                logText(args),
+            ];
             let runId = id;
             try {
                 await api.run(id);
@@ -3067,25 +3199,27 @@ async function jobCommand(argv, env, out) {
             for (;;) {
                 const page = await api.logs(runId, { cursor, limitBytes: 65536 });
                 if (out.json)
-                    out.write(JSON.stringify(page));
+                    out.write(shown(JSON.stringify(page)));
                 else
                     for (const chunk of page.chunks)
-                        (chunk.stream === "stderr" ? process.stderr : process.stdout).write(chunk.text);
+                        (chunk.stream === "stderr" ? stderr : stdout)(chunk.text);
                 cursor = page.nextCursor;
                 if (page.complete) {
+                    if (!follow && out.json)
+                        return 0;
+                    const run = await api.run(runId);
                     if (!out.json) {
-                        const run = await api.run(runId);
                         if (page.truncated)
                             process.stderr.write("[the run printed more than it keeps; this is its last part]\n");
                         process.stderr.write(`[${run.state}${run.exitCode === null ? "" : `, exit code ${run.exitCode}`}${run.reason ? `, ${run.reason}` : ""}]\n`);
                     }
-                    return 0;
+                    return follow ? (run.exitCode ?? (run.state === "succeeded" ? 0 : 1)) : 0;
                 }
                 if (page.chunks.length)
                     continue;
                 if (!follow) {
                     if (!out.json)
-                        process.stderr.write(`[${runId} is still going; follow it: ${me} job logs ${runId} -f]\n`);
+                        process.stderr.write(`[${runId} is still going; follow it: ${me} jobs logs ${runId} -f]\n`);
                     return 0;
                 }
                 await new Promise((resolve) => setTimeout(resolve, 1000));
@@ -3099,6 +3233,27 @@ async function jobCommand(argv, env, out) {
             print(`${job.name} ${job.state}.`, job);
             return 0;
         }
+        case "trigger": {
+            const id = need(rest[0], "a job id");
+            const job = await api.trigger(id);
+            print(`${job.name} runs now${job.state === "paused" ? ", once; it stays paused" : ""}. Follow it: ${me} jobs logs ${job.id} -f`, job);
+            return 0;
+        }
+        case "reschedule": {
+            const args = parse(rest, [], ["cron", "timezone", "at"], `${me} jobs reschedule <id> --cron "0 3 * * *" [--timezone Europe/Berlin]`);
+            const id = need(args.positional[0], "a job id");
+            const cron = flag(args, "cron");
+            const at = flag(args, "at");
+            if ((cron === undefined) === (at === undefined))
+                throw usage('Give --cron "<five fields>" for a schedule, or --at <time|now> for one run.');
+            if (at !== undefined && flag(args, "timezone") !== undefined)
+                throw usage("--timezone goes with --cron; --at takes a time with its own offset.");
+            const job = await api.reschedule(id, cron !== undefined
+                ? { cron, ...(flag(args, "timezone") ? { timezone: flag(args, "timezone") } : {}) }
+                : { at: atTime(at) });
+            print(`${job.name}: ${scheduleText(job)}. Next run ${when(job.nextRunAt)}.`, job);
+            return 0;
+        }
     }
     throw unknown("job command", verb, [
         "create",
@@ -3108,12 +3263,15 @@ async function jobCommand(argv, env, out) {
         "logs",
         "pause",
         "resume",
+        "trigger",
+        "reschedule",
         "cancel",
     ]);
 }
-const VOLUME_HELP = `runtime volume <command>
+const VOLUME_HELP = `runtime volumes <command>
 
-  create --size-mib <N> [--name n] [--shared]  A persistent disk; prints its id
+  create --size-mib <N> [--name n] [--label k=v]... [--shared]
+                                              A persistent disk; prints its id
   ls                                          Your volumes
   get <id>                                    One volume, its backups and where it is attached
   resize <id> --size-mib <N>                  Grow a detached volume on its current host
@@ -3128,7 +3286,7 @@ const VOLUME_HELP = `runtime volume <command>
   backup-rm <backupId>                        Delete a backup
   backup-policy <id> [--daily on|off] [--retention-days N]
                                               Daily backups on or off, and how long each is kept
-  Attach one: runtime sandbox create --volume <id>:/data
+  Attach one: runtime sandboxes create --volume <id>:/data
   Volumes are backed up off their host daily unless you turn it off.
   Shared commands work where shared disks are enabled.
 `;
@@ -3142,10 +3300,11 @@ async function volume(argv, env, out) {
     const api = (await client(env)).volumes;
     switch (verb) {
         case "create": {
-            const args = parse(rest, ["shared"], ["size-mib", "name"]);
+            const args = parse(rest, ["shared"], ["size-mib", "name", "label"]);
             const created = await api.create({
                 sizeMiB: integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>")),
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
                 ...(has(args, "shared") ? { shared: true } : {}),
             });
             print(created.id, created);
@@ -3166,7 +3325,7 @@ async function volume(argv, env, out) {
                         v.attachments.map((a) => `${a.sandboxId}:${a.path}`).join(", ") || "-",
                     ]),
                 ])
-                : "No volumes. Create one: runtime volume create --size-mib 10240", all);
+                : "No volumes. Create one: runtime volumes create --size-mib 10240", all);
             return 0;
         }
         case "get": {
@@ -3178,7 +3337,7 @@ async function volume(argv, env, out) {
             const args = parse(rest, [], ["size-mib"]);
             const id = need(args.positional[0], "a volume id");
             if (args.positional.length !== 1 || args.rest)
-                throw usage(`Use ${me} volume resize <id> --size-mib <N>.`);
+                throw usage(`Use ${me} volumes resize <id> --size-mib <N>.`);
             const sizeMiB = integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>"));
             const resized = await api.resize(id, { sizeMiB });
             print(describeRecord(resized, table), resized);
@@ -3190,7 +3349,7 @@ async function volume(argv, env, out) {
             const sandboxId = need(args.positional[1], "a sandbox id");
             const path = need(flag(args, "path"), "--path /data");
             if (args.positional.length !== 2 || args.rest)
-                throw usage(`Use ${me} volume attach <id> <sandboxId> --path /data.`);
+                throw usage(`Use ${me} volumes attach <id> <sandboxId> --path /data.`);
             const attachment = await api.attach(id, { sandboxId, path });
             print(describeRecord(attachment, table), attachment);
             return attachment.error ? 1 : 0;
@@ -3201,7 +3360,7 @@ async function volume(argv, env, out) {
             const id = need(args.positional[0], "a volume id");
             const attachmentId = need(args.positional[1], "an attachment id");
             if (args.positional.length !== 2 || args.rest)
-                throw usage(`Use ${me} volume ${verb} <id> <attachmentId>.`);
+                throw usage(`Use ${me} volumes ${verb} <id> <attachmentId>.`);
             const attachment = verb === "detach"
                 ? await api.detach(id, attachmentId)
                 : await api.getAttachment(id, attachmentId);
@@ -3210,7 +3369,8 @@ async function volume(argv, env, out) {
         }
         case "rm":
         case "delete": {
-            const found = await api.delete(need(rest[0], "a volume id"));
+            const id = need(rest[0], "a volume id");
+            const found = await withVolumeRelease((options) => api.delete(id, options), out);
             print(`${found.id} ${found.state}`, found);
             return 0;
         }
@@ -3220,7 +3380,7 @@ async function volume(argv, env, out) {
             const days = integer(args, "retention-days");
             const made = await api.backup(id, days === undefined ? {} : { retentionDays: days }, has(args, "no-wait") ? { wait: 0 } : {});
             if (!out.json && made.state === "pending")
-                out.error(`Copying it off the host; check with: ${me} volume backups ${id}`);
+                out.error(`Copying it off the host; check with: ${me} volumes backups ${id}`);
             print(made.id, made);
             return 0;
         }
@@ -3248,7 +3408,7 @@ async function volume(argv, env, out) {
             const args = parse(rest, [], ["name"]);
             const created = await api.restore(need(args.positional[0], "a backup id"), flag(args, "name") ? { name: flag(args, "name") } : {});
             if (!out.json && created.state === "creating")
-                out.error(`Restoring; check with: ${me} volume get ${created.id}`);
+                out.error(`Restoring; check with: ${me} volumes get ${created.id}`);
             print(created.id, created);
             return 0;
         }
@@ -3307,12 +3467,47 @@ const CREATE_FLAGS = [
 function waiting(out) {
     const said = new Set();
     return (refusal) => {
+        // The CLI's volume wait owns this refusal, including its deadline.
+        if (refusal.code === "volume_releasing")
+            throw refusal;
         if (said.has(refusal.code))
             return;
         said.add(refusal.code);
         out.error(`${refusal.message} Waiting for room, up to 2 minutes; Ctrl-C stops.`);
     };
 }
+/** A stopping sandbox can take a minute to let go of its volume. Retry only
+ * that refusal, with the same key so a create cannot make two sandboxes. */
+async function withVolumeRelease(operation, out) {
+    const idempotencyKey = crypto.randomUUID();
+    let until;
+    for (;;) {
+        try {
+            return await operation({
+                idempotencyKey,
+                ...(until === undefined
+                    ? {}
+                    : { signal: AbortSignal.timeout(Math.max(1, Math.ceil(until - performance.now()))) }),
+            });
+        }
+        catch (error) {
+            if (!(error instanceof RuntimeError) ||
+                error.code !== "volume_releasing" ||
+                error.status !== 409)
+                throw error;
+            if (until === undefined) {
+                until = performance.now() + 90_000;
+                out.error("Waiting for the volume to be let go, up to 90 seconds; Ctrl-C stops.");
+            }
+            const left = until - performance.now();
+            if (left <= 0)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(1000, left)));
+            if (performance.now() >= until)
+                throw error;
+        }
+    }
+}
 /** Options `sandbox create` and `run` take with a value. */
 const CREATE_VALUES = [
     "name",
@@ -3353,6 +3548,9 @@ function usdMicros(args, name) {
 }
 /** A create body from the command line's flags. */
 function createInput(args) {
+    for (const name of ["image", "snapshot", "volume", "name", "region", "connect"])
+        if (args.flags.get(name)?.some((value) => !value.trim()))
+            throw usage(`--${name} needs a non-empty value.`);
     const rules = ["allow", "deny", "connect"].filter((name) => args.flags.has(name));
     return {
         ...(flag(args, "image") ? { image: flag(args, "image") } : {}),
@@ -3387,7 +3585,7 @@ function createInput(args) {
             ? { timeoutSeconds: integer(args, "timeout") }
             : {}),
         ...(flag(args, "on-timeout")
-            ? { onLeaseEnd: oneOf(args, "on-timeout", ["pause", "stop"]) }
+            ? { onLeaseEnd: oneOf(args, "on-timeout", ["pause", "stop", "delete"]) }
             : {}),
         ...(integer(args, "idle-pause") !== undefined
             ? { idlePauseSeconds: integer(args, "idle-pause") }
@@ -3449,6 +3647,9 @@ ownInterrupt = true) {
     // (Sandbox.exec); `--json` answers the result and prints no such line.
     else if (result.timedOut)
         out.error(`runtime: timed out after ${timeout ? `${timeout} s` : "24 h"}; the command's process group was killed.`);
+    const memory = outOfMemoryLines(result.outOfMemory);
+    if (memory && !out.json)
+        out.error(memory);
     // Never drop output silently: say so, and do not exit 0.
     const lost = extras.lostOutput(result, sbx.id);
     if (lost && !out.json)