withruntime 0.8.4 → 0.10.0

package/dist/cli.js

@@ -1,15 +1,17 @@
 #!/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";
 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 { envFetch } from "./proxy.js";
 import { VERSION } from "./transport.js";
 const HELP = `Runtime Cloud CLI ${VERSION}
@@ -35,12 +37,16 @@ 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
                                                value is read from standard input, never an argument.
                                                --allow (paid): only these methods and paths get it
-  secrets ls | get <NAME>                      Names, hosts and placeholders, never values
+  secrets set <NAME> --jobs [--host ...]       A copy scheduled jobs put in their environment
+                                               (job create --secret NAME); with --host, both
+  secrets ls | get <NAME>                      Names, hosts, placeholders and jobs versions, never values
   secrets rotate <NAME>                        A new version of the jobs copy, from standard input
   secrets reveal <NAME> [--version N]          Print the jobs copy's value. The sandboxes' copy is
                                                never readable, by anyone
@@ -86,6 +92,7 @@ Products
   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
@@ -103,7 +110,7 @@ const SANDBOX_HELP = `runtime sandbox <command>
   run [--keep] [create options] -- <command>                  A fresh sandbox runs one command, then stops
   ssh <id|name> [-- <command...>] | ssh config [--install]    Log in over SSH, also from VS Code and JetBrains
   port-forward <id|name> <port|local:remote>...               Forward local ports to ports in it
-  create [--name n] [--label k=v]... [--vcpu 2] [--memory 4096] [--disk 4096]
+  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]
          [--no-internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
@@ -122,10 +129,15 @@ const SANDBOX_HELP = `runtime sandbox <command>
   cp <src> <dst>                              Copy files or directories; name a sandbox
                                               path as <id>:/path, e.g. cp ./app sbx:/workspace/app
   cat <id> <path>                             Print a file
-  files <id> [path] [--depth 2] [--glob '**/*.py']
+  files <id> [path] [--depth 1] [--glob '**/*.py']
   stop <id> | pause <id> | wake <id> | restart <id>
+  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)
   extend <id> <seconds>                       More time before the lease ends
-  update <id> [--name n] [--label k=v]... [--idle-pause <seconds>] [--auto-wake on|off]
+  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
   snapshot <id> [--name n] [--retention days] Keep its whole machine; prints the snapshot id
@@ -133,6 +145,9 @@ const SANDBOX_HELP = `runtime sandbox <command>
         [--endpoint https://...] [--account-id id] [--read-only]
                                               Your bucket as a directory; the proxy signs, the sandbox never sees the key
   mounts <id> | unmount <id> <path>           Its bucket mounts; unmount one
+  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]
                                               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 .]
@@ -168,8 +183,8 @@ const SANDBOX_HELP = `runtime sandbox <command>
 
 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
@@ -217,9 +232,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
@@ -251,7 +270,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) {
@@ -385,6 +407,9 @@ const SANDBOX_VERBS = [
     "ls",
     "get",
     "stop",
+    "rm",
+    "delete",
+    "switch-image",
     "pause",
     "wake",
     "restart",
@@ -392,6 +417,7 @@ const SANDBOX_VERBS = [
     "mount",
     "mounts",
     "unmount",
+    "tailscale",
     "fork",
     "extend",
     "update",
@@ -484,6 +510,12 @@ function describe(info) {
         ["funding", info.funding],
         ["region", info.region],
         ["expires", info.expiresAt ?? "-"],
+        ["at lease 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.
+        ...(info.pausedAt ? [["paused at", info.pausedAt]] : []),
+        ...(info.endedAt ? [["ended", info.endedAt]] : []),
+        ...(info.stopReason ? [["stop reason", info.stopReason]] : []),
         ["auto wake", info.autoWake === false ? "off" : "on"],
         [
             "idle pause",
@@ -523,6 +555,17 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     // `runtime sandbox 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") ||
+        (remaining.length === 1 && remaining[0] === "help");
+    // A command without a help of its own answers `help` with its lines of the
+    // top-level help, and never takes the word as its input.
+    if (first && first !== "help" && asked && !nested && !OWN_HELP.includes(first)) {
+        const lines = topicHelp(named(HELP), first);
+        if (lines) {
+            out.write(out.json ? JSON.stringify({ usage: lines }) : lines);
+            return 0;
+        }
+    }
     if (first &&
         (cut < 0 ? remaining : remaining.slice(0, cut)).some((arg) => arg === "--help" || arg === "-h"))
         return run(nested && command === "ssh"
@@ -542,8 +585,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
@@ -555,10 +598,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);
@@ -655,6 +698,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)
@@ -671,7 +748,8 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     if (command === "limits") {
         const l = await (await client(env)).limits.get();
-        const usd = (micros) => `$${(Number(BigInt(micros) / 10000n) / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+        // As `usage` shows money: $0.0014 of spend read $0.00 until 30 September 2026.
+        const usd = (micros) => dollars(micros);
         const access = l.access === "read"
             ? "read only: reads every product, cannot start, change or spend"
             : l.access === "full"
@@ -687,6 +765,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             ],
             ["used, last 24 hours", usd(l.daily.usedMicros)],
             ...(l.daily.remainingMicros === null ? [] : [["left", usd(l.daily.remainingMicros)]]),
+            ...(l.trial ? [["free trial", trialLeft(l.trial)]] : []),
         ]), l);
         return 0;
     }
@@ -703,7 +782,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) => {
@@ -748,7 +827,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
@@ -774,17 +853,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") {
@@ -975,11 +1063,15 @@ export function usageCsv(u) {
         .join(","));
     return [head.join(","), ...rows].join("\n");
 }
+/** The free trial's time left, as `runtime usage` and `runtime limits` say it. */
+function trialLeft(trial) {
+    const hours = (ms) => (ms / 3_600_000).toLocaleString("en-US", { maximumFractionDigits: 1 });
+    return `${hours(trial.availableMs)} of ${hours(trial.totalMs)} hours left${trial.reservedMs > 0 ? `, ${hours(trial.reservedMs)} held by running sandboxes` : ""}`;
+}
 function usageSummary(u) {
     const micros = (value) => typeof value === "string" || typeof value === "number" || typeof value === "bigint"
         ? BigInt(value)
         : 0n;
-    const hours = (ms) => (ms / 3_600_000).toLocaleString("en-US", { maximumFractionDigits: 1 });
     const takenBack = micros(u.takenBack);
     const rows = [
         ["available", dollars(micros(u.available))],
@@ -996,10 +1088,7 @@ function usageSummary(u) {
     if (micros(u.expired) > 0n)
         rows.push(["expired or taken back", dollars(micros(u.expired))]);
     if (u.trial)
-        rows.push([
-            "free trial",
-            `${hours(u.trial.availableMs)} of ${hours(u.trial.totalMs)} hours left${u.trial.reservedMs > 0 ? `, ${hours(u.trial.reservedMs)} held by running sandboxes` : ""}`,
-        ]);
+        rows.push(["free trial", trialLeft(u.trial)]);
     if (u.outbound) {
         const gib = (bytes) => `${(bytes / 1_073_741_824).toLocaleString("en-US", { maximumFractionDigits: 1 })} GiB`;
         const left = Math.max(0, u.outbound.allowanceBytes - u.outbound.freeBytes);
@@ -1357,8 +1446,12 @@ async function sandbox(argv, env, out) {
                 ...(args.flags.has("state")
                     ? { state: args.flags.get("state") }
                     : {}),
+                limit: 100,
             });
-            const all = await page.toArray(1000);
+            // Every page, oldest first, so the newest are last on the screen. Until
+            // 30 September 2026 this stopped at 1,000 and silently left out the
+            // newest sandboxes of a busy account.
+            const all = await page.toArray(Infinity);
             // Stopped sandboxes are hidden by default; say so, or an agent that
             // stopped everything reads "No sandboxes" as "never had any".
             const hidden = out.json || args.flags.size
@@ -1392,6 +1485,23 @@ async function sandbox(argv, env, out) {
             print(describe(sbx.info), sbx.info);
             return 0;
         }
+        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`));
+            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.`);
+            await sbx.switchImage(need(image, "an image, e.g. app:v2"), { keep: "workspace" });
+            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 gone = await sbx.delete();
+            print(`${gone.id} deleted`, gone);
+            return 0;
+        }
         case "stop":
         case "pause":
         case "wake":
@@ -1445,12 +1555,43 @@ async function sandbox(argv, env, out) {
             print(`${gone.path} unmounted`, gone);
             return 0;
         }
+        case "tailscale": {
+            const action = rest[0];
+            if (action === "up") {
+                const args = parse(rest.slice(1), [], ["auth-key-secret", "hostname", "tag"]);
+                const sbx = await use(args.positional[0]);
+                const joined = await sbx.tailscale.up({
+                    authKeySecret: need(flag(args, "auth-key-secret"), "--auth-key-secret, the name of a secret set with --jobs that holds your Tailscale auth key"),
+                    ...(flag(args, "hostname") ? { hostname: flag(args, "hostname") } : {}),
+                    ...(args.flags.has("tag") ? { tags: args.flags.get("tag") } : {}),
+                });
+                print(`${joined.hostname} ${joined.addresses.join(" ")}${joined.proxy ? ` (reach the tailnet through ${joined.proxy})` : ""}`, joined);
+                return 0;
+            }
+            if (action === "status") {
+                const sbx = await use(rest[1]);
+                const now = await sbx.tailscale.status();
+                print(now.tailnet
+                    ? `${now.tailnet.hostname} ${now.running ? now.addresses.join(" ") : (now.state ?? "not running")}`
+                    : "Not on a tailnet.", now);
+                return 0;
+            }
+            if (action === "down") {
+                const sbx = await use(rest[1]);
+                const gone = await sbx.tailscale.down();
+                print(gone.left ? "Left the tailnet." : "Not on a tailnet.", gone);
+                return 0;
+            }
+            throw usage("runtime sandbox 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") ? { retentionDays: integer(args, "retention") } : {}),
+                ...(integer(args, "retention") !== undefined
+                    ? { retentionDays: integer(args, "retention") }
+                    : {}),
             });
             print(snapshot.id, snapshot);
             return 0;
@@ -1472,7 +1613,16 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "update": {
-            const args = parse(rest, [], ["name", "label", "idle-pause", "auto-wake", "persistent", "max-total-cost"]);
+            const args = parse(rest, [], [
+                "name",
+                "label",
+                "env",
+                "unset-env",
+                "idle-pause",
+                "auto-wake",
+                "persistent",
+                "max-total-cost",
+            ]);
             const sbx = await get(args.positional[0]);
             const onOff = (name) => {
                 const value = flag(args, name);
@@ -1485,9 +1635,14 @@ async function sandbox(argv, env, out) {
             const cost = flag(args, "max-total-cost");
             if (cost !== undefined && cost !== "none" && !/^\d+(\.\d{1,6})?$/.test(cost))
                 throw usage("--max-total-cost takes dollars, such as 25 or 2.50, or none.");
+            const env = {
+                ...(args.flags.has("env") ? pairs(args, "env") : {}),
+                ...Object.fromEntries((args.flags.get("unset-env") ?? []).map((name) => [name, null])),
+            };
             const settings = {
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
                 ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+                ...(Object.keys(env).length ? { env } : {}),
                 ...(integer(args, "idle-pause") !== undefined
                     ? { idlePauseSeconds: integer(args, "idle-pause") }
                     : {}),
@@ -1496,11 +1651,11 @@ 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)
-                throw usage("Say what to change: --name, --label, --idle-pause, --auto-wake, --persistent or --max-total-cost.");
+                throw usage("Say what to change: --name, --label, --env, --unset-env, --idle-pause, --auto-wake, --persistent or --max-total-cost.");
             await sbx.update(settings);
             print(describe(sbx.info), sbx.info);
             return 0;
@@ -1576,8 +1731,21 @@ async function sandbox(argv, env, out) {
             const args = parse(rest, [], ["signal"]);
             const sbx = await use(args.positional[0]);
             const proc = await sbx.processes.get(need(args.positional[1], "a process id"));
+            // A process that has ended has nothing to signal; "Signalled" said it
+            // had been until 30 September 2026.
+            if (proc.info.state === "exited" ||
+                proc.info.state === "killed" ||
+                proc.info.state === "timed_out") {
+                print(`${proc.id} had already ${proc.info.state === "exited" ? "exited" : "ended"}${proc.info.exitCode == null ? "" : ` (exit code ${proc.info.exitCode})`}; nothing to signal.`, {
+                    processId: proc.id,
+                    state: proc.info.state,
+                    exitCode: proc.info.exitCode ?? null,
+                    signalled: false,
+                });
+                return 0;
+            }
             await proc.kill((flag(args, "signal") ?? "SIGTERM"));
-            print(`Signalled ${proc.id}.`, { processId: proc.id });
+            print(`Signalled ${proc.id}.`, { processId: proc.id, signalled: true });
             return 0;
         }
         case "shell": {
@@ -1596,7 +1764,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
@@ -1639,7 +1807,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.
@@ -1971,7 +2139,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
             ? {}
             : {
@@ -2020,8 +2188,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;
@@ -2256,7 +2424,7 @@ async function snapshot(argv, env, out) {
                     ? { sandboxId: await sandboxIdOf(await client(env), flag(args, "sandbox")) }
                     : {}),
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
-            })).toArray(1000);
+            })).toArray(Infinity);
             print(all.length
                 ? table([
                     ["ID", "NAME", "STATUS", "FROM", "EXPIRES"],
@@ -2360,9 +2528,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");
@@ -2379,9 +2551,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") }
                     : {}),
             };
@@ -2426,7 +2600,7 @@ read = readSecret) {
         case "list":
         case "versions": {
             const name = verb === "versions" ? need(rest[0], "a name") : undefined;
-            const all = await (await api.list(name ? { name } : {})).toArray(1000);
+            const all = await (await api.list(name ? { name } : {})).toArray(Infinity);
             print(all.length
                 ? table([
                     ["ID", "NAME", "VERSION", "TAGS", "STATE", "MIB", "CREATED"],
@@ -2447,7 +2621,7 @@ read = readSecret) {
         }
         case "get": {
             const found = await api.resolve(need(rest[0], "an image"));
-            print(JSON.stringify(found, null, 2), found);
+            print(describeRecord(found, table), found);
             return 0;
         }
         case "logs": {
@@ -2645,23 +2819,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") }
                     : {}),
             });
@@ -2672,7 +2852,7 @@ async function jobCommand(argv, env, out) {
         }
         case "ls":
         case "list": {
-            const all = await (await api.list({ limit: 100 })).toArray(1000);
+            const all = await (await api.list({ limit: 100 })).toArray(Infinity);
             print(all.length
                 ? table([
                     ["ID", "NAME", "STATE", "SCHEDULE", "NEXT RUN", "BLOCKED"],
@@ -2681,7 +2861,8 @@ async function jobCommand(argv, env, out) {
                         j.name,
                         j.state,
                         scheduleText(j),
-                        when(j.nextRunAt),
+                        // A canceled or finished job keeps its last nextRunAt, but runs no more.
+                        j.state === "active" || j.state === "paused" ? when(j.nextRunAt) : "-",
                         j.blockedReason ?? "-",
                     ]),
                 ])
@@ -2695,7 +2876,7 @@ async function jobCommand(argv, env, out) {
         }
         case "runs": {
             const jobId = need(rest[0], "a job id");
-            const all = await (await api.runs(jobId, { limit: 100 })).toArray(1000);
+            const all = await (await api.runs(jobId, { limit: 100 })).toArray(Infinity);
             print(all.length
                 ? table([
                     ["RUN", "ATTEMPT", "STATE", "EXIT", "SCHEDULED", "STARTED", "ENDED", "REASON"],
@@ -2724,7 +2905,7 @@ async function jobCommand(argv, env, out) {
                 if (!(error instanceof NotFoundError))
                     throw error;
                 // A job's id: its latest run.
-                const runs = await (await api.runs(id, { limit: 100 })).toArray(1000);
+                const runs = await (await api.runs(id, { limit: 100 })).toArray(Infinity);
                 const latest = runs.at(-1);
                 if (!latest) {
                     const job = await api.get(id);
@@ -2789,9 +2970,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
@@ -2802,6 +2987,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;
@@ -2813,17 +2999,18 @@ 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;
         }
         case "ls":
         case "list": {
-            const all = await (await api.list()).toArray(1000);
+            const all = await (await api.list()).toArray(Infinity);
             print(all.length
                 ? table([
                     ["ID", "NAME", "STATE", "MIB", "BACKED UP", "ATTACHED"],
@@ -2841,9 +3028,43 @@ async function volume(argv, env, out) {
         }
         case "get": {
             const found = await api.get(need(rest[0], "a volume id"));
-            print(JSON.stringify(found, null, 2), found);
+            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"));
@@ -2862,7 +3083,7 @@ async function volume(argv, env, out) {
         }
         case "backups": {
             const volumeId = rest[0];
-            const all = await (await api.backups(volumeId ? { volumeId } : {})).toArray(1000);
+            const all = await (await api.backups(volumeId ? { volumeId } : {})).toArray(Infinity);
             print(all.length
                 ? table([
                     ["ID", "VOLUME", "STATE", "TRIGGER", "MIB", "STORED", "TAKEN", "EXPIRES"],
@@ -2915,6 +3136,10 @@ async function volume(argv, env, out) {
         "create",
         "ls",
         "get",
+        "resize",
+        "attach",
+        "detach",
+        "attachment",
         "rm",
         "backup",
         "backups",
@@ -2966,6 +3191,7 @@ const CREATE_VALUES = [
     "image",
     "snapshot",
     "volume",
+    "env",
 ];
 /** Dollars from the command line as integer microdollars: 25, 2.50 or 0.000001. */
 function usdMicros(args, name) {
@@ -2974,7 +3200,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) {
@@ -2993,17 +3225,24 @@ function createInput(args) {
             : {}),
         ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
         ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
-        ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
-        ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
-        ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+        ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
+        ...(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"]) }
             : {}),
@@ -3033,7 +3272,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.
@@ -3071,7 +3310,11 @@ ownInterrupt = true) {
     const lost = extras.lostOutput(result, sbx.id);
     if (lost && !out.json)
         out.error(lost);
-    const code = result.timedOut ? 124 : Math.min(255, Math.max(0, result.exitCode ?? 1));
+    /* A command a signal ended comes back as minus the signal (-9 after the
+       out-of-memory killer's SIGKILL); a shell says 128 + the signal. Clamped
+       to 0 until 30 September 2026, a killed command exited 0. */
+    const exit = result.exitCode ?? 1;
+    const code = result.timedOut ? 124 : Math.min(255, exit < 0 ? 128 - exit : exit);
     return lost && code === 0 ? 1 : code;
 }
 async function shell(sbx, command) {
@@ -3102,6 +3345,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`),
     };
 }
@@ -3119,7 +3366,9 @@ export function describeError(error, json) {
                     details: error.details,
                 },
             });
-        return `Error [${error.code}]: ${error.message}${error.hint ? `\nHint: ${error.hint}` : ""}${error.requestId
+        // In the command line's words: the option, not the request's field.
+        const { message, hint } = cliRefusal(error);
+        return `Error [${error.code}]: ${message}${hint ? `\nHint: ${hint}` : ""}${error.requestId
             ? // A refusal of what was sent is the caller's to fix; only a failure
                 // of ours is worth a report.
                 error.status >= 400 && error.status < 500
@@ -3157,21 +3406,38 @@ 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));
-    const latest = m.latest;
+    // `latest` is the newest reading of the last 15 minutes whatever the state,
+    // so a sandbox paused a minute ago still has one from before it slept. Only a
+    // running sandbox has a now.
+    const latest = m.state === "running" ? m.latest : null;
+    const still = m.state === "running" ? null : `none: it is ${m.state}`;
+    const cpuNow = newestCpu(m);
     return [
         table([
             ["state", m.state],
             [
                 "cpu now",
-                latest?.cpuPercent == null
-                    ? "no reading in the last 15 minutes"
-                    : `${latest.cpuPercent}% of ${m.vcpu} vCPU (${latest.cpuCores} cores)`,
+                still ??
+                    (cpuNow
+                        ? `${cpuNow.percent}% of ${m.vcpu} vCPU${cpuNow.cores == null ? "" : ` (${cpuNow.cores} cores)`}${cpuNow.ago ? `, ${cpuNow.ago}` : ""}`
+                        : "no reading in this range"),
+            ],
+            [
+                "memory now",
+                still ?? (latest ? `${mib(latest.memoryBytes)} of ${mib(m.memoryLimitBytes)}` : "-"),
             ],
-            ["memory now", 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
@@ -3266,7 +3532,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) => [