withruntime 0.9.0 → 0.11.0

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
+import { once } from "node:events";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { connectionOrigins, connectionStore, resolveCredential } from "./credentials.js";
+import { checkBrowserOrigins, connectionOrigins, connectionStore, resolveCredential, } from "./credentials.js";
 import { me, named } from "./cli-name.js";
 import { Runtime } from "./client.js";
 import { Sandbox as SandboxHandle } from "./sandbox.js";
@@ -36,6 +37,8 @@ Account
   sso                                          Single sign-on and SCIM directory sync (owner or
                                                admin keys); an owner changes it on the website
   usage [--csv]                                Balance, trial time and charges; --csv, each resource
+  usage export --since <UTC time> --until <UTC time>
+                                               Every settlement in the range as CSV; --json, each page
   limits                                       Whether this key is read-only, and its daily spending limit
   secrets set <NAME> --host <host>... [--header <name> [--format '<text {value}>']]
             [--allow '[GET,HEAD] /path/*']...  Store a secret sandboxes use without seeing it; the
@@ -85,7 +88,7 @@ Observability
                                                Events and metrics to an OpenTelemetry endpoint
 
 Products
-  sandbox   Linux microVMs: exec, shell, files, code, previews, network, desktop
+  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
@@ -94,7 +97,7 @@ Products
   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: send outbound traffic through your own proxy
+  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\`...
 
 Every command takes --json. Keys: RUNTIME_API_KEY, or the connection from \`runtime login\`.
@@ -128,11 +131,15 @@ const SANDBOX_HELP = `runtime sandbox <command>
   cat <id> <path>                             Print a file
   files <id> [path] [--depth 1] [--glob '**/*.py']
   stop <id> | pause <id> | wake <id> | restart <id>
+  stop --label k=v [--label k=v]...           Stop every live sandbox with all those labels
   rm <id>                                     Delete it for good: stops it, deletes its disk and
                                               paused memory, revokes its previews; snapshots stay
   switch-image <id> <image> --keep-workspace  Move it to another image, keeping /workspace (your home),
                                               volumes, env and previews; processes restart, the rest of
                                               its disk is lost (snapshot it first to keep everything)
+  resize <id> [--vcpu 2] [--memory 4096] --restart
+                                              Change its size by a restart: the whole disk stays,
+                                              programs stop (snapshot it first to keep memory)
   extend <id> <seconds>                       More time before the lease ends
   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]
@@ -177,11 +184,13 @@ const SANDBOX_HELP = `runtime sandbox <command>
                | type <text> | press <keys> | windows
   desktop <id> record start [--fps 10] [--max-seconds 1800] [--max-mib 512] | record stop <recId>
                | record ls | record fetch <recId> [file.mp4] | record rm <recId>
+  browser <id> start [--headed] [--width 1280] [--height 800] | get | stop
+                                              Chromium for CDP agents: prints its cdpUrl
 
 Examples
   id=$(runtime sandbox create)
-  runtime sandbox exec $id -- python3 -c 'print(6*7)'
-  runtime sandbox cp ./project $id:/workspace/project
+  runtime sandbox cp ./invoice.py $id:/workspace/invoice.py
+  runtime sandbox exec $id -- python3 /workspace/invoice.py
   runtime sandbox stop $id
 `;
 /** A command's options. Reading one its parse() did not declare is a bug in
@@ -229,9 +238,13 @@ commandAfter) {
                 throw commandAfter && !meantOption(name, known)
                     ? usage(`Unknown option ${arg.split("=")[0]}. If it belongs to the command, put the command after --: ${commandAfter}`)
                     : unknownOption(name, known);
-            const value = inline ?? (booleans.includes(name) ? "true" : argv[++i]);
-            if (value === undefined)
+            const boolean = booleans.includes(name);
+            const value = inline ?? (boolean ? "true" : argv[++i]);
+            if (value === undefined ||
+                (!boolean && inline === undefined && (value === "--" || /^--?[^\d]/.test(value))))
                 throw usage(`--${name} needs a value.`);
+            if (boolean && value !== "true" && value !== "false")
+                throw usage(`--${name} takes true or false.`);
             flags.set(name, [...(flags.get(name) ?? []), value]);
         }
         else
@@ -263,7 +276,10 @@ const integer = (args, name) => {
         return undefined;
     if (!/^\d+$/.test(value))
         throw usage(`--${name} must be a whole number.`);
-    return Number(value);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        throw usage(`--${name} is too large to represent exactly.`);
+    return parsed;
 };
 /** A flag that takes one of a few words, checked before anything is sent. */
 function oneOf(args, name, choices) {
@@ -400,6 +416,7 @@ const SANDBOX_VERBS = [
     "rm",
     "delete",
     "switch-image",
+    "resize",
     "pause",
     "wake",
     "restart",
@@ -427,6 +444,7 @@ const SANDBOX_VERBS = [
     "session",
     "network",
     "desktop",
+    "browser",
     "metrics",
     "watch",
     "mcp",
@@ -575,8 +593,8 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             ? JSON.stringify({ connected, usage: HELP })
             : `Runtime Cloud ${VERSION}. ${start}
 
-  ${me} sandbox run -- python3 -c 'print(6*7)'
-                                   A fresh sandbox runs one command, then stops
+  ${me} sandbox 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} help                             Everything else
@@ -588,10 +606,10 @@ 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 -c 'print(6*7)'`);
+        const args = parse(rest, [...CREATE_FLAGS, "keep"], [...CREATE_VALUES, "cwd", "env"], `${me} sandbox run -- python3 < invoice.py`);
         const commandLine = args.rest ?? args.positional;
         if (!commandLine.length)
-            throw usage(`Give the command after --: ${me} sandbox run -- python3 -c 'print(6*7)'`);
+            throw usage(`Give the command after --: ${me} sandbox run -- python3 < invoice.py`);
         const runtime = await client(env);
         const timeout = integer(args, "timeout");
         const { timeoutSeconds: _lease, ...input } = createInput(args);
@@ -688,6 +706,40 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "usage") {
+        if (rest[0] === "export") {
+            const args = parse(rest.slice(1), [], ["since", "until"]);
+            if (args.positional.length || args.rest)
+                throw usage(`Use ${me} usage export --since <UTC time> --until <UTC time>.`);
+            const since = need(flag(args, "since"), "--since <UTC time>, such as 2026-09-01T00:00:00Z");
+            const until = need(flag(args, "until"), "--until <UTC time>, such as 2026-10-01T00:00:00Z");
+            const rt = await client(env);
+            const cursors = new Set();
+            let cursor;
+            for (;;) {
+                const page = await rt.usageExport({
+                    since,
+                    until,
+                    ...(cursor ? { cursor } : {}),
+                    limit: 500,
+                });
+                if (page.nextCursor !== null && cursors.has(page.nextCursor))
+                    throw new RuntimeError({
+                        code: "usage_export_incomplete",
+                        status: 0,
+                        message: "The usage export repeated a page cursor and could not finish.",
+                        hint: "Run the export again; do not treat the partial output as complete.",
+                    });
+                if (out.json)
+                    out.write(JSON.stringify(page));
+                else if (page.csv)
+                    out.write(page.csv);
+                await out.drain?.();
+                if (page.nextCursor === null)
+                    return 0;
+                cursors.add(page.nextCursor);
+                cursor = page.nextCursor;
+            }
+        }
         const csv = rest.includes("--csv");
         const unknown = rest.find((arg) => arg !== "--csv");
         if (unknown)
@@ -738,7 +790,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         const page = await rt.events.list({
             ...(sandbox ? { resourceId: await sandboxIdOf(rt, sandbox) } : {}),
             ...(flag(args, "type") ? { type: flag(args, "type") } : {}),
-            ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+            ...(integer(args, "limit") !== undefined ? { limit: integer(args, "limit") } : {}),
         });
         print(page.data.length
             ? table(page.data.map((e) => {
@@ -783,7 +835,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
                 throw usage(`Unknown option --${name}.`);
         const page = await (await client(env)).audit.list({
             ...(flag(args, "action") ? { action: flag(args, "action") } : {}),
-            ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+            ...(integer(args, "limit") !== undefined ? { limit: integer(args, "limit") } : {}),
             ...(flag(args, "before") ? { before: flag(args, "before") } : {}),
         });
         print(page.events.length
@@ -809,17 +861,26 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         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, {
-            open: (input) => openWalletAccount(input, { authUrl: origins.auth }),
-            claim: (code) => claimWalletAccount(code, { authUrl: origins.auth }),
-            save: (key, orgId) => connectionStore(env).save({
-                version: 1,
-                apiOrigin: origins.api,
-                authOrigin: origins.auth,
-                key,
-                connectionId: "pasted",
-                orgId,
-                agentName: "Wallet agent",
-            }),
+            open: (input) => {
+                checkBrowserOrigins(origins);
+                return openWalletAccount(input, { authUrl: origins.auth });
+            },
+            claim: (code) => {
+                checkBrowserOrigins(origins);
+                return claimWalletAccount(code, { authUrl: origins.auth });
+            },
+            save: (key, orgId) => {
+                checkBrowserOrigins(origins);
+                return connectionStore(env).save({
+                    version: 1,
+                    apiOrigin: origins.api,
+                    authOrigin: origins.auth,
+                    key,
+                    connectionId: "pasted",
+                    orgId,
+                    agentName: "Wallet agent",
+                });
+            },
         });
     }
     if (command === "referrals") {
@@ -1442,6 +1503,21 @@ async function sandbox(argv, env, out) {
             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 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`);
+            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.`);
+            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>`));
@@ -1453,6 +1529,23 @@ async function sandbox(argv, env, out) {
         case "pause":
         case "wake":
         case "restart": {
+            if (verb === "stop" && rest.some((word) => /^--label(=|$)/.test(word))) {
+                const args = parse(rest, [], ["label"]);
+                if (args.positional.length)
+                    throw usage("Give a sandbox id or --label, not both.");
+                const { stopped, failed } = await runtime.sandboxes.stopAll({
+                    labels: pairs(args, "label"),
+                });
+                const said = (error) => (error instanceof Error ? error.message : String(error));
+                print([
+                    stopped.length || failed.length
+                        ? `${stopped.length} stopped${failed.length ? `, ${failed.length} failed` : ""}.`
+                        : "No live sandbox has those labels.",
+                    ...stopped.map((id) => `${id} stopped`),
+                    ...failed.map((f) => `${f.id} failed: ${said(f.error)}`),
+                ].join("\n"), { stopped, failed: failed.map((f) => ({ id: f.id, error: said(f.error) })) });
+                return failed.length ? 1 : 0;
+            }
             const sbx = await get(rest[0]);
             await sbx[verb]();
             print(`${sbx.id} ${sbx.state}`, sbx.info);
@@ -1536,7 +1629,9 @@ async function sandbox(argv, env, out) {
             const sbx = await get(args.positional[0]);
             const snapshot = await sbx.snapshot({
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
-                ...(integer(args, "retention") ? { retentionDays: integer(args, "retention") } : {}),
+                ...(integer(args, "retention") !== undefined
+                    ? { retentionDays: integer(args, "retention") }
+                    : {}),
             });
             print(snapshot.id, snapshot);
             return 0;
@@ -1596,7 +1691,7 @@ async function sandbox(argv, env, out) {
                 ...(cost === undefined
                     ? {}
                     : {
-                        maxTotalCostMicros: cost === "none" ? null : Math.round(Number(cost) * 1e6),
+                        maxTotalCostMicros: cost === "none" ? null : usdMicros(args, "max-total-cost"),
                     }),
             };
             if (!Object.keys(settings).length)
@@ -1709,7 +1804,7 @@ async function sandbox(argv, env, out) {
             const args = parse(rest, [], ["depth", "glob"]);
             const sbx = await use(args.positional[0]);
             const entries = await sbx.files.list(args.positional[1] ?? "/workspace", {
-                ...(integer(args, "depth") ? { depth: integer(args, "depth") } : {}),
+                ...(integer(args, "depth") !== undefined ? { depth: integer(args, "depth") } : {}),
                 ...(flag(args, "glob") ? { glob: flag(args, "glob") } : {}),
             });
             print(entries
@@ -1752,7 +1847,7 @@ async function sandbox(argv, env, out) {
             const sbx = await use(args.positional[0]);
             const preview = await sbx.previews.create(port, {
                 ...(has(args, "public") ? { visibility: "public" } : {}),
-                ...(integer(args, "ttl") ? { ttlSeconds: integer(args, "ttl") } : {}),
+                ...(integer(args, "ttl") !== undefined ? { ttlSeconds: integer(args, "ttl") } : {}),
             });
             // The link and how to use it, nothing more: the API's `hint` (which
             // carries a referral line) stays in --json, not in the command's words.
@@ -1838,6 +1933,8 @@ async function sandbox(argv, env, out) {
         }
         case "desktop":
             return desktop(await use(rest[0]), rest.slice(1), out);
+        case "browser":
+            return browser(await use(rest[0]), rest.slice(1), out);
         case "watch":
             return (await import("./cli-extras.js")).watchCommand(await use(rest[0]), rest.slice(1), out, kit);
         case "mcp":
@@ -2084,7 +2181,7 @@ async function runCode(sbx, argv, out) {
     const execution = await sbx.interpreter.run(code, {
         language,
         ...(flag(args, "context") ? { context: flag(args, "context") } : {}),
-        ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
+        ...(timeout !== undefined ? { timeoutMs: timeout * 1000 } : {}),
         ...(out.json
             ? {}
             : {
@@ -2133,8 +2230,8 @@ async function desktop(sbx, argv, out) {
         case "start": {
             const args = parse(rest, [], ["width", "height"]);
             const started = await d.start({
-                ...(integer(args, "width") ? { width: integer(args, "width") } : {}),
-                ...(integer(args, "height") ? { height: integer(args, "height") } : {}),
+                ...(integer(args, "width") !== undefined ? { width: integer(args, "width") } : {}),
+                ...(integer(args, "height") !== undefined ? { height: integer(args, "height") } : {}),
             });
             print(`Desktop ${started.size} on ${started.display}. Watch it: ${started.streamUrl}`, started);
             return 0;
@@ -2172,6 +2269,35 @@ async function desktop(sbx, argv, out) {
     }
     throw usage(`${me} sandbox desktop <id> start|stop|screenshot|open|click|type|press|windows|record`);
 }
+async function browser(sbx, argv, out) {
+    const [action, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    switch (action) {
+        case "start": {
+            const args = parse(rest, ["headed"], ["width", "height"]);
+            const started = await sbx.browser.start({
+                ...(args.flags.has("headed") ? { headless: false } : {}),
+                ...(integer(args, "width") !== undefined ? { width: integer(args, "width") } : {}),
+                ...(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);
+            return 0;
+        }
+        case "get":
+        case undefined: {
+            const state = await sbx.browser.get();
+            print(state.running ? `${state.version}\nCDP: ${state.cdpUrl}` : "No browser running.", state);
+            return 0;
+        }
+        case "stop": {
+            const stopped = await sbx.browser.stop();
+            print(stopped.stopped ? "Browser stopped." : "No browser was running.", stopped);
+            return 0;
+        }
+    }
+    throw usage(`${me} sandbox browser <id> start [--headed]|get|stop`);
+}
 const KEYS_HELP = `runtime keys <command>
 
   create [--name <name>] [--read-only] [--daily-limit <usd>] [--account-wide]
@@ -2473,9 +2599,13 @@ read = readSecret) {
             if (sources.filter((s) => s !== undefined).length !== 1)
                 throw usage("Give exactly one of a folder with a Dockerfile (or -f <Dockerfile>), --from <image>, or --pip/--apt/--npm.");
             const build = {
-                ...(integer(args, "max-image-mib") ? { maxImageMiB: integer(args, "max-image-mib") } : {}),
-                ...(integer(args, "disk-mib") ? { diskMiB: integer(args, "disk-mib") } : {}),
-                ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+                ...(integer(args, "max-image-mib") !== undefined
+                    ? { maxImageMiB: integer(args, "max-image-mib") }
+                    : {}),
+                ...(integer(args, "disk-mib") !== undefined ? { diskMiB: integer(args, "disk-mib") } : {}),
+                ...(integer(args, "timeout") !== undefined
+                    ? { timeoutSeconds: integer(args, "timeout") }
+                    : {}),
             };
             // -t app, -t app:v2 -t app:latest: one name, its tags.
             let name = flag(args, "name");
@@ -2492,9 +2622,11 @@ read = readSecret) {
             }
             const start = {
                 ...(flag(args, "start") ? { command: flag(args, "start") } : {}),
-                ...(integer(args, "ready-port") ? { readyPort: integer(args, "ready-port") } : {}),
+                ...(integer(args, "ready-port") !== undefined
+                    ? { readyPort: integer(args, "ready-port") }
+                    : {}),
                 ...(flag(args, "ready-command") ? { readyCommand: flag(args, "ready-command") } : {}),
-                ...(integer(args, "ready-timeout")
+                ...(integer(args, "ready-timeout") !== undefined
                     ? { readyTimeoutSeconds: integer(args, "ready-timeout") }
                     : {}),
             };
@@ -2758,23 +2890,29 @@ async function jobCommand(argv, env, out) {
                     ? { cron, ...(flag(args, "timezone") ? { timezone: flag(args, "timezone") } : {}) }
                     : { at: atTime(at) },
                 command: cwd ? { argv, cwd } : argv,
-                ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+                ...(integer(args, "timeout") !== undefined
+                    ? { timeoutSeconds: integer(args, "timeout") }
+                    : {}),
                 compute: {
-                    ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
-                    ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
-                    ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+                    ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
+                    ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
+                    ...(integer(args, "disk") !== undefined ? { diskMiB: integer(args, "disk") } : {}),
                     ...(flag(args, "cpu")
                         ? { cpuMode: oneOf(args, "cpu", ["shared", "reserved"]) }
                         : {}),
-                    ...(integer(args, "cpu-floor") ? { cpuFloorMillis: integer(args, "cpu-floor") } : {}),
+                    ...(integer(args, "cpu-floor") !== undefined
+                        ? { cpuFloorMillis: integer(args, "cpu-floor") }
+                        : {}),
                     ...(flag(args, "region") ? { region: flag(args, "region") } : {}),
-                    ...(usdMicros(args, "max-cost") ? { maxCostMicros: usdMicros(args, "max-cost") } : {}),
+                    ...(usdMicros(args, "max-cost") !== undefined
+                        ? { maxCostMicros: usdMicros(args, "max-cost") }
+                        : {}),
                 },
                 ...(attempts !== undefined
                     ? { retry: { maxAttempts: attempts, backoffSeconds: backoff ?? 30 } }
                     : {}),
                 ...(secrets ? { secrets } : {}),
-                ...(usdMicros(args, "max-total-cost")
+                ...(usdMicros(args, "max-total-cost") !== undefined
                     ? { maxTotalCostMicros: usdMicros(args, "max-total-cost") }
                     : {}),
             });
@@ -2903,9 +3041,13 @@ async function jobCommand(argv, env, out) {
 }
 const VOLUME_HELP = `runtime volume <command>
 
-  create --size-mib <N> [--name n]            A persistent ext4 disk; prints its id
+  create --size-mib <N> [--name n] [--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
+  attach <id> <sandboxId> --path /data        Mount a shared disk in a running sandbox
+  detach <id> <attachmentId>                 Flush and unmount its shared attachment
+  attachment <id> <attachmentId>             Read the attachment's state and error
   rm <id>                                     Delete it and everything on it (its backups stay)
   backup <id> [--retention-days N] [--no-wait]
                                               Back it up now, off its host; prints the backup id
@@ -2916,6 +3058,7 @@ const VOLUME_HELP = `runtime volume <command>
                                               Daily backups on or off, and how long each is kept
   Attach one: runtime sandbox 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.
 `;
 async function volume(argv, env, out) {
     const [verb, ...rest] = argv;
@@ -2927,10 +3070,11 @@ async function volume(argv, env, out) {
     const api = (await client(env)).volumes;
     switch (verb) {
         case "create": {
-            const args = parse(rest, [], ["size-mib", "name"]);
+            const args = parse(rest, ["shared"], ["size-mib", "name"]);
             const created = await api.create({
                 sizeMiB: integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>")),
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(has(args, "shared") ? { shared: true } : {}),
             });
             print(created.id, created);
             return 0;
@@ -2958,6 +3102,40 @@ async function volume(argv, env, out) {
             print(describeRecord(found, table), found);
             return 0;
         }
+        case "resize": {
+            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>.`);
+            const sizeMiB = integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>"));
+            const resized = await api.resize(id, { sizeMiB });
+            print(describeRecord(resized, table), resized);
+            return resized.resize?.state === "failed" ? 1 : 0;
+        }
+        case "attach": {
+            const args = parse(rest, [], ["path"]);
+            const id = need(args.positional[0], "a volume id");
+            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.`);
+            const attachment = await api.attach(id, { sandboxId, path });
+            print(describeRecord(attachment, table), attachment);
+            return attachment.error ? 1 : 0;
+        }
+        case "detach":
+        case "attachment": {
+            const args = parse(rest, [], []);
+            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>.`);
+            const attachment = verb === "detach"
+                ? await api.detach(id, attachmentId)
+                : await api.getAttachment(id, attachmentId);
+            print(describeRecord(attachment, table), attachment);
+            return verb === "detach" && attachment.error ? 1 : 0;
+        }
         case "rm":
         case "delete": {
             const found = await api.delete(need(rest[0], "a volume id"));
@@ -3029,6 +3207,10 @@ async function volume(argv, env, out) {
         "create",
         "ls",
         "get",
+        "resize",
+        "attach",
+        "detach",
+        "attachment",
         "rm",
         "backup",
         "backups",
@@ -3089,7 +3271,13 @@ function usdMicros(args, name) {
         return undefined;
     if (!/^\d+(\.\d{1,6})?$/.test(value))
         throw usage(`--${name} takes dollars, such as 25 or 2.50.`);
-    return Math.round(Number(value) * 1e6);
+    // ARCHITECTURE.md section 10: integer microdollars throughout, with no
+    // floating-point money path or rounding drift.
+    const [whole, fraction = ""] = value.split(".");
+    const micros = BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, "0"));
+    if (micros > BigInt(Number.MAX_SAFE_INTEGER))
+        throw usage(`--${name} is too large to represent exactly in microdollars.`);
+    return Number(micros);
 }
 /** A create body from the command line's flags. */
 function createInput(args) {
@@ -3109,17 +3297,23 @@ function createInput(args) {
         ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
         ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
         ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
-        ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
-        ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
-        ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+        ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
+        ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
+        ...(integer(args, "disk") !== undefined ? { diskMiB: integer(args, "disk") } : {}),
         ...(flag(args, "cpu") ? { cpu: oneOf(args, "cpu", ["shared", "reserved"]) } : {}),
-        ...(integer(args, "cpu-floor") ? { cpuFloorMillis: integer(args, "cpu-floor") } : {}),
+        ...(integer(args, "cpu-floor") !== undefined
+            ? { cpuFloorMillis: integer(args, "cpu-floor") }
+            : {}),
         ...(flag(args, "region") ? { region: flag(args, "region") } : {}),
-        ...(usdMicros(args, "max-cost") ? { maxCostMicros: usdMicros(args, "max-cost") } : {}),
-        ...(usdMicros(args, "max-total-cost")
+        ...(usdMicros(args, "max-cost") !== undefined
+            ? { maxCostMicros: usdMicros(args, "max-cost") }
+            : {}),
+        ...(usdMicros(args, "max-total-cost") !== undefined
             ? { maxTotalCostMicros: usdMicros(args, "max-total-cost") }
             : {}),
-        ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+        ...(integer(args, "timeout") !== undefined
+            ? { timeoutSeconds: integer(args, "timeout") }
+            : {}),
         ...(flag(args, "on-timeout")
             ? { onLeaseEnd: oneOf(args, "on-timeout", ["pause", "stop"]) }
             : {}),
@@ -3149,7 +3343,7 @@ ownInterrupt = true) {
         ...(stdin ? { stdin } : {}),
         ...(flag(args, "cwd") ? { cwd: flag(args, "cwd") } : {}),
         ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
-        ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
+        ...(timeout !== undefined ? { timeoutMs: timeout * 1000 } : {}),
     };
     // Ctrl-C stops the command in the sandbox too, and says so; without this
     // the CLI exited and the command ran on unseen.
@@ -3222,6 +3416,10 @@ function defaultOut(argv) {
     return {
         json,
         write: (text) => process.stdout.write(text.endsWith("\n") ? text : `${text}\n`),
+        drain: async () => {
+            if (process.stdout.writableNeedDrain)
+                await once(process.stdout, "drain");
+        },
         error: (text) => process.stderr.write(`${text}\n`),
     };
 }
@@ -3279,6 +3477,10 @@ function spark(values) {
 }
 const mib = (bytes) => `${Math.round(bytes / 1_048_576).toLocaleString("en-US")} MiB`;
 function metricsText(m) {
+    const waiting = (value) => value == null ? "not measured" : `${value}%`;
+    const waitingHistory = (field) => m.points.some((point) => point[field] != null)
+        ? spark(m.points.map((point) => point[field] ?? null))
+        : "not measured";
     const cpu = m.points.map((p) => p.cpuPercent);
     const memory = m.points.map((p) => p.memoryBytes);
     const peak = Math.max(0, ...m.points.map((p) => p.cpuPeakPercent ?? p.cpuPercent ?? 0));
@@ -3302,7 +3504,11 @@ function metricsText(m) {
                 "memory now",
                 still ?? (latest ? `${mib(latest.memoryBytes)} of ${mib(m.memoryLimitBytes)}` : "-"),
             ],
+            ["cpu wait now", still ?? waiting(latest?.cpuWaitPercent)],
+            ["memory stalls now", still ?? waiting(latest?.memoryStallPercent)],
             [`cpu, ${m.range}`, m.points.length ? `${spark(cpu)}  peak ${peak}%` : "no readings"],
+            [`cpu wait, ${m.range}`, waitingHistory("cpuWaitPercent")],
+            [`memory stalls, ${m.range}`, waitingHistory("memoryStallPercent")],
             [
                 `memory, ${m.range}`,
                 m.points.length
@@ -3397,7 +3603,7 @@ async function webhooksCommand(argv, env, out) {
         }
         case "deliveries": {
             const page = await hooks.deliveries(id(), {
-                ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+                ...(integer(args, "limit") !== undefined ? { limit: integer(args, "limit") } : {}),
             });
             print(page.data.length
                 ? table(page.data.map((d) => [