@shardflux/cli 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,79 @@
 Every command and option the README shows is available from the version named here. Breaking changes ship in minor
 releases and are marked **Breaking**.
 
+## 0.8.0 (not yet published)
+
+Needs `@shardflux/sdk` 0.13.0 or later.
+
+### Elastic memory
+
+- `shard ws open` and `shard ws fork`: `--allocation-mode fixed|elastic` and `--memory-held <mib>` (elastic only; a
+  usage error otherwise), sent with the caps. Caps flags replace the stored caps; no caps flag keeps the stored layout.
+- `shard ws get` (and a ready `ws open`) prints a `memory` line: `fixed 4096 MiB`, or `elastic: promised 8192 MiB,
+  held 1024 MiB, plugged +2048 MiB` (`- (not running)` without a live allocation). `caps` shows `allocation_mode` and
+  `memory_mib_held`.
+- `shard ws exec -v` prints `memory grow  partial 1024 -> 3072 of 4096 MiB in 175 ms` on stderr when the command's
+  start waited for a grow; `--json` adds `memory_grow`. Without a grow nothing changes.
+
+### Burst execution
+
+- `shard ws exec --burst [--burst-vcpus N] [--burst-memory MIB]` runs the command on a larger, short-lived burst VM
+  and applies its file changes back.
+  `-v` prints a `burst` line (size, method, applied changes, leftover processes killed, overhead) on stderr; `--json`
+  adds `burst`. The sizes without `--burst`, out of range, or `--burst` with `--stdin`, are usage errors (exit 2);
+  `--burst` on a file-first workspace too.
+- Ctrl-C does not cancel a burst (it cannot be canceled). A `burst_apply_failed` error names the exec session on
+  stderr.
+
+### Background commands
+
+- `shard ws exec-start --timeout <duration>`: kill the command after this long (parsed like `shard ws exec --timeout`;
+  none unless set). Without `--json` it names the commands that read and stop the session on stderr.
+- `shard ws exec-read <id|key> <session-id> [--follow]`: the session's stdout and stderr from the start. An ended
+  session exits with the command's exit code (124 timed out, 128+N killed by signal N), one that still runs exits 5
+  with the command that follows it. `--follow` streams until the command exits, resuming from byte offsets after a
+  dropped connection; Ctrl-C stops following and the command keeps running. `--json` prints one object (`session_id`,
+  `state`, `exit_code`, `term_signal`, `timed_out`, `canceled`, `stdout`, `stderr`, `truncated`, `reconnects`).
+  A session that could not start exits 6 with the workspace's reason, as `shard ws exec` does.
+- `shard ws exec-cancel <id|key> <session-id> [--grace <duration>]`: SIGTERM, then SIGKILL after the grace (default
+  5s, at most 60s). Prints `exec session <id>: canceled (signal 15)` (`--json`: the session).
+
+### Suspend by id
+
+- `shard ws suspend <id>` sends the suspend straight to the workspace, without first fetching it: one request fewer.
+  The line it prints names the id you gave (`Suspending <id>: operation ...`); with a key it is unchanged
+  (`Suspending <key> (<id>): ...`). A UUID that is no workspace id is still tried as a key.
+
+### Held fork
+
+- `shard ws fork --wait` gets the running copy and its tool token in the fork request itself when the API holds the
+  fork (SDK 0.13.0), without the follow-up operation poll and copy refresh. Against an API that does not, it polls as
+  before. `shard ws fork` without `--wait` is unchanged.
+
+### Exec start and output in one request
+
+- `shard ws exec` starts the command and streams its output in one request on cells that support it (SDK 0.13.0);
+  output still resumes from byte offsets after a dropped connection, and the command never runs twice.
+
+### Immutable paths
+
+A template may declare directories as `immutable`: every workspace of it mounts them read-only from the template's
+newest published version.
+
+- `shard templates get`: an `IMMUTABLE PATHS` column with each version's paths and image size
+  (`/opt/acme, /srv/tools (128.0 MiB)`), shown when a version declares any.
+- `shard ws get` (and a ready `ws open`): `immutable paths  v2 (mounted read-only)`, the template version whose
+  immutable paths the workspace has mounted.
+- `shard templates build` sends template.yaml's `immutable` list; `shard templates builds get` (and a build's output)
+  prints `immutable paths`, and for a build that failed on them a `fix` line (`immutable_path_missing`: make the path a
+  directory in the build; `immutable_image_too_large`). `shard templates export` writes the list back.
+  `shard templates init` describes `immutable` in a comment.
+- Hints for the refusals: `immutable_path_removed` names the paths to add back, `immutable_paths_unsupported_base` the
+  base to build on, `invalid_path` the `immutable[<i>]` entry to fix (exit 2), and a write under an immutable path
+  (`read_only_path`, 409 from the workspace, exit 1) says where to change it.
+- **Breaking:** `--json` output no longer carries `update_policy`: the API removed the update policy (it was always
+  `pinned`).
+
 ## 0.6.2
 
 Needs `@shardflux/sdk` 0.11.1 or later.

package/README.md

@@ -374,11 +374,12 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `version [--check]` | Print the CLI and SDK versions and the update status (`--check` asks the API now). |
 | `usage [--org <id>] [--estimate \| --series \| --workspace <id\|key>] [--from T] [--to T] [--granularity hour\|day] [--meter M]` | Usage summary for the current period: plan, meters and allowances. `--estimate`: the bill so far and projected allowance use; `--series`: usage over time; `--workspace`: one workspace's usage over time (0.5.0+). The summary includes the [overage](#usage-and-overage) block (0.5.1+). |
 | `feedback [--category C] [--workspace W] [--request-id ID] [--error-code CODE] [--command TEXT] [--from-file F\|-] <message...>` | Send feedback straight to the Shardflux team (0.5.0+). See [Feedback](#feedback-agents-use-this-while-you-work). |
-| `workspaces open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--lifetime persistent\|session] [--mode processful\|file-first] [--cpu-millis N --memory-mib N --disk-gib N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. `--mode file-first` (0.5.0+) opens a [file-first workspace](#file-first-workspaces); the default is processful for a new key and the stored mode for an existing one. |
+| `workspaces open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--lifetime persistent\|session] [--mode processful\|file-first] [--cpu-millis N --memory-mib N --disk-gib N] [--allocation-mode fixed\|elastic] [--memory-held N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. `--mode file-first` (0.5.0+) opens a [file-first workspace](#file-first-workspaces); the default is processful for a new key and the stored mode for an existing one. `--allocation-mode elastic` (0.8.0+): [elastic memory](#elastic-memory-080). |
 | `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. A file-first workspace's state reads `running (file-first)` (0.5.0+). |
-| `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). |
+| `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). Its memory (0.8.0+): `fixed 4096 MiB`, or `elastic: promised …, held …, plugged +… MiB`. The template version whose [immutable paths](#immutable-paths-080) it has mounted (0.8.0+): `immutable paths  v3 (mounted read-only)`. |
 | `workspaces inputs <id\|key>` | The workspace's text inputs (0.4.0+). |
-| `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr. `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). |
+| `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] [--burst [--burst-vcpus N] [--burst-memory MIB]] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed (in the start request itself, 0.8.0+) and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr, and the memory grow the command waited for on an elastic workspace (0.8.0+; `--json`: `memory_grow`). `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). `--burst` (0.8.0+): [burst execution](#burst-execution-080). |
+| `workspaces exec-start <id\|key> [--session-id ID] [--cwd D] [--timeout T] [--stdin-open] -- <cmd> [args...]`, `workspaces exec-read <id\|key> <session-id> [--follow]`, `workspaces exec-cancel <id\|key> <session-id> [--grace D]` | Background commands (0.8.0+): start a command and return at once, read its output and state (`--follow` streams it to its exit and exits with its code; while it runs `exec-read` exits 5), stop it. See [Background commands](#background-commands-080). |
 | `executions get <id\|key> <execution-id> [--wait D]` | The result of a file-first workspace's execution (0.5.0+): its output, then what ran. Exits with the command's code, 6 if the execution failed or was lost, 5 while it still runs. |
 | `files read <id\|key> <path> [--out F]` | Raw bytes to stdout, or to a local file. |
 | `files write <id\|key> <path> [--from F\|-] [--append] [--no-parents] [--if-revision N]` | Atomic write. The default source is stdin. `--if-revision` (0.5.0+): file-first workspaces only, see [Tree revisions](#tree-revisions). |
@@ -389,7 +390,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `workspaces suspend\|resume <id\|key> [--wait] [--timeout T] [--timing]` | Lifecycle operation. Returns immediately unless you pass `--wait`. |
 | `workspaces suspend <id\|key> --durable [--timeout T]` | (0.7.0+) Suspend and wait until the copy is in durable storage. See "Durable storage". |
 | `workspaces suspend <id\|key> --when-idle D` / `--cancel-when-idle` | (0.5.1+) Suspend once the workspace has been idle for `D` (0 to 1h; `0` = as soon as it is idle, 0.6.1+), or cancel that. See "Suspend when idle". |
-| `workspaces fork <id\|key> <new-key> [caps] [--wait]` | Fork into a new key. |
+| `workspaces fork <id\|key> <new-key> [caps] [--allocation-mode fixed\|elastic] [--memory-held N] [--wait]` | Fork into a new key. Without caps the fork keeps the source's caps and memory allocation (0.8.0+). With `--wait` the API holds the fork until the copy runs and returns it ready in the same request (0.8.0+; `--timing` shows one `request` phase marked `(held)`). |
 | `workspaces delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once. After deletion finishes, the key can open a new workspace ID. |
 | `workspaces close <id\|key> [--wait]` | End a session workspace now: it is deleted, and the key then opens a new workspace. A persistent workspace is refused (`not_session`). |
 | `workspaces reset <id\|key> --yes [--wait]` | Layered workspaces: wipe every change and restart on the template. The previous state stays restorable for 7 days. |
@@ -404,7 +405,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `secrets versions <id\|NAME>`, `secrets delete <id\|NAME> --yes`, `secrets access-log <id\|NAME>` | Versions, deletion (also removes the name from every workspace binding), and the access log. |
 | `operations list <id\|key> [--state S] [--kind K]`, `operations get <op>`, `operations wait <op> [--timeout T] [--timing]` | Operations. |
 | `templates list [--owner platform\|organization] [--include-archived] [--all]` | Templates the project can open, with their open version, layouts, file list state and draft. |
-| `templates get <slug> [--owner O] [--include-archived]` | One template (0.4.0+): its versions, what open resolves to, and the open version's settings (env, inputs, start commands, services, defaults). |
+| `templates get <slug> [--owner O] [--include-archived]` | One template (0.4.0+): its versions, what open resolves to, and the open version's settings (env, inputs, start commands, services, defaults). Each version's [immutable paths](#immutable-paths-080) and their image size (0.8.0+). |
 | `templates init --base <slug[@version]> [--out F] [--force]` | Write a starter `template.yaml` on a base (0.4.0+). |
 | `templates build <file> [--slug S] [--display-name N] [--description T] [--publish] [--acknowledge PATH]... [--wait] [--timeout 30m] [--timing]` | Build a template from `template.yaml` (0.4.0+): local files and folders are uploaded, then the build is created. See [Build a template](#build-a-template-from-templateyaml). |
 | `templates export <slug>@<version> [--out F] [--force]` | The `template.yaml` a version was built from, ready to build again (0.4.0+). |
@@ -475,6 +476,30 @@ settings:
 - A file `shard` cannot read or pack (a symlink that leaves the folder, a device) is refused before any request (exit
   2). The API's refusals (`upload_missing`, `language_unavailable`, `invalid_settings`, ...) exit 2 with the reason.
 
+### Immutable paths (0.8.0+)
+
+Directories listed under `immutable` follow the template: every workspace of it mounts them read-only from the
+template's newest published version, picked up at its next cold boot or resume. Ship tools, models or data there and
+existing workspaces get each new version; everything else in a workspace stays its own.
+
+```yaml
+immutable: [/opt/acme]
+```
+
+```sh
+shard templates get acme-dev
+# VERSION  STATE      SOURCE  LAYOUTS  IMMUTABLE PATHS        CREATED               DESCRIPTION
+# v2 *     published  recipe  layered  /opt/acme (96.0 MiB)   2026-10-01 03:14:52Z  tools 2.4
+shard ws get acme/main
+# template         acme-dev v1 (<version id>)
+# immutable paths  v2 (mounted read-only)
+```
+
+A template.yaml without `immutable` keeps the list of the template's open version, and a new version keeps every path
+of it (`immutable_path_removed` names the ones to add back). `shard templates builds get` lists a build's immutable
+paths; `shard templates export` writes them back into template.yaml. A write under an immutable path
+(`shard files write`) exits 1 with `read_only_path` and a hint.
+
 ## File-first workspaces
 
 (0.5.0+) A file-first workspace has no VM between commands. Its state is a versioned file tree under `/home/user`.
@@ -617,6 +642,53 @@ shard ws suspend acme/demo --cancel-when-idle
   workspace that is not running is refused with `conflict` (`not_running`, exit 1), and a file-first workspace (never
   suspended) with `not_supported_for_mode` (exit 1).
 
+## Elastic memory (0.8.0+)
+
+Give a workspace a large memory promise while it holds only what it uses. It idles at `--memory-held` (default
+1024 MiB) and grows before each command starts, so builds and test runners see the memory they need from their first
+instruction.
+
+```sh
+shard ws open acme/demo --template python-node-browser --memory-mib 8192 --allocation-mode elastic
+shard ws get acme/demo                  # memory  elastic: promised 8192 MiB, held 1024 MiB, plugged +3072 MiB
+shard ws exec acme/demo -v -- npm test  # memory grow  delivered 1024 -> 4096 MiB in 175 ms
+```
+
+The layout takes effect at the workspace's next start. `--json` output carries `memory` on the workspace and
+`memory_grow` on a command that grew it.
+
+## Burst execution (0.8.0+)
+
+Run one heavy command, such as a cold build or a full test suite, on a larger VM without resizing the workspace:
+`--burst` runs it on a short-lived burst VM over a copy of the workspace and applies its file changes back when it
+exits. Output streams as usual and `shard` exits with the command's exit code.
+
+```sh
+shard ws exec acme/demo --burst --burst-vcpus 16 -v -- bash -lc "cd app && go build ./..."
+# burst  local 16 vCPU / 8192 MiB (layer); applied 3 files, 1 dirs, 1 removed, 40960 bytes; overhead 641 ms
+```
+
+`--burst-vcpus` and `--burst-memory` size the burst VM (default 8 vCPU and 8192 MiB within the plan's
+per-workspace limits); `--json` adds `burst` to the result.
+
+## Background commands (0.8.0+)
+
+A long command (a build, a test suite, a training run, a server) can run in the background of a processful workspace
+while you or your agent do other work:
+
+```sh
+shard ws exec-start acme/demo --session-id build-1 --timeout 2h -- bash -lc "make -C /home/user/app"
+shard ws exec-read acme/demo build-1            # the output so far; exit 5 while it runs
+shard ws exec-read acme/demo build-1 --follow   # stream to the end; exits with the command's exit code
+shard ws exec-cancel acme/demo build-1 --grace 10s
+```
+
+- `--timeout` is the longest the command may run; the workspace stays awake until it ends or that time passes.
+- `exec-read` prints stdout and stderr from the start. `--follow` resumes from byte offsets after a dropped
+  connection; Ctrl-C stops following and the command keeps running. `--json` prints one object with the state, exit
+  code and output.
+- `exec-cancel` sends SIGTERM, then SIGKILL after `--grace` (default 5s, at most 60s).
+
 ## Start deadlines
 
 A queued open, resume or fork (`capacity_pending`) has a deadline 15 minutes after it was created.
@@ -788,10 +860,10 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 | 2 | usage error: bad arguments, or input the API rejected as `validation_failed` |
 | 3 | not found: workspace, operation or route |
 | 4 | authentication or authorization: missing, malformed, revoked or insufficient key or session; `step_up_required` (run `shard auth step-up`), `mfa_required` (a sign-in waiting for its code), `email_unverified`, `invalid_credentials` |
-| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`), up to a queued start's 15-minute deadline. `executions get` (0.5.0+): the execution is still queued or running. `billing upgrade --wait` (0.5.0+): nobody paid in time (the checkout stays open) |
+| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`), up to a queued start's 15-minute deadline. `executions get` (0.5.0+): the execution is still queued or running. `ws exec-read` (0.8.0+): the background command still runs. `billing upgrade --wait` (0.5.0+): nobody paid in time (the checkout stays open) |
 | 6 | the awaited operation ended `failed` or `canceled` (also a resume or open that failed while waking a workspace). `retryable=true` in the error means a retry can succeed (`capacity_unavailable`). Also a file-first execution that ended `failed` or `lost` (0.5.0+): nothing was published. `exec` (0.5.1+): the command could not start (`exec_failed_to_start`). `billing upgrade --wait` (0.5.0+): the checkout expired or was canceled (`checkout_ended`) |
 | 130 | interrupted (Ctrl-C). Waits stop at once, and exec sends a cancel to the session. A file-first execution runs to completion, and the error names the `shard executions get` command for its result. |
-| exec, executions get | the command's own code: 124 if it timed out, 128+N if killed by signal N. Failures before the command ran use the codes above; use `--json` to tell them apart. |
+| exec, executions get, ws exec-read | the command's own code: 124 if it timed out, 128+N if killed by signal N. Failures before the command ran use the codes above; use `--json` to tell them apart. |
 
 ## Durable storage (0.7.0+)
 

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.7.0";
+export declare const CLI_VERSION = "0.8.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.7.0';
+export const CLI_VERSION = '0.8.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -27,6 +27,15 @@ const CAPS = {
     'memory-mib': { type: 'string', value: '<n>', description: 'Memory cap in MiB.' },
     'disk-gib': { type: 'string', value: '<n>', description: 'Disk cap in GiB.' },
 };
+/** Elastic memory (0.8.0+): the memory allocation of a workspace's caps (open and fork only). */
+const MEMORY_ALLOCATION = {
+    'allocation-mode': {
+        type: 'string',
+        value: '<fixed|elastic>',
+        description: 'elastic: --memory-mib is a promise; the workspace holds --memory-held while idle and the host grows it when a command needs it (needs the elastic memory entitlement). Takes effect at the next VM start. Caps given without it make the workspace fixed; a command without caps keeps the stored layout.',
+    },
+    'memory-held': { type: 'string', value: '<mib>', description: 'With --allocation-mode elastic: memory held while idle, in MiB (at least 512, default 1024, at most --memory-mib).' },
+};
 /** `--timing` (0.3.0+): the SDK's lifecycle timing of the command's open, wait or wake (README "Timing"). */
 const TIMING = {
     timing: {
@@ -209,6 +218,7 @@ const KEY_COMMANDS = [
             },
             ...INPUTS,
             ...CAPS,
+            ...MEMORY_ALLOCATION,
             wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once). Ready includes the template’s start commands and services.' },
             timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side; one waiting for capacity gives up 15 minutes after it began (capacity_unavailable, retryable).' },
             ...TIMING,
@@ -221,6 +231,7 @@ const KEY_COMMANDS = [
             'shard ws open acme/demo --template python-node-browser --no-wait --json',
             'shard ws open acme/demo --template python-node-browser --timing',
             'shard ws open acme/agent-7 --template python-node-browser --mode file-first',
+            'shard ws open acme/demo --template python-node-browser --memory-mib 8192 --allocation-mode elastic --memory-held 1024',
         ],
     },
     {
@@ -245,11 +256,38 @@ const KEY_COMMANDS = [
             policy: { type: 'string', value: '<policy>', description: 'adaptive, never, fixed:<seconds>, or default to clear the override.' },
             keepalive: { type: 'string', value: '<seconds>', description: 'Declare ongoing work for this many seconds.' },
         } },
-    { path: ['workspaces', 'exec-start'], summary: 'Start a background exec session with optional pipe stdin', positionals: [REF, { name: 'command', required: true, variadic: true }], options: {
+    {
+        path: ['workspaces', 'exec-start'],
+        summary: 'Start a background exec session with optional pipe stdin',
+        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax) and returns the session at once (JSON on stdout). Read it with "shard ws exec-read", stop it with "shard ws exec-cancel".',
+        positionals: [REF, { name: 'command', required: true, variadic: true }],
+        options: {
             'stdin-open': { type: 'boolean', description: 'Keep pipe stdin open for exec-input.' },
             'session-id': { type: 'string', value: '<id>', description: 'Caller-chosen id to deduplicate starts.' },
             cwd: { type: 'string', value: '<dir>', description: 'Absolute working directory.' },
-        } },
+            timeout: { type: 'string', value: '<duration>', description: 'Kill the command after this long (e.g. 30m, 2h; none unless set). The workspace stays awake until the command ends or this passes (1 hour when unset).' },
+        },
+        examples: ['shard ws exec-start acme/demo --session-id build-1 --timeout 2h -- bash -lc "make -C /home/user/app"', 'shard ws exec-read acme/demo build-1 --follow'],
+    },
+    {
+        path: ['workspaces', 'exec-read'],
+        summary: 'Print a background exec session’s output and state; --follow streams it until the command exits',
+        description: 'Prints the session’s stdout and stderr from the start. When the command has ended, shard exits with its exit code (124 if it timed out, 128+N if killed by signal N); while it still runs, exit 5. --follow keeps streaming until it ends and resumes from byte offsets after dropped connections; Ctrl-C stops following, the command keeps running. --json prints one object at the end.',
+        positionals: [REF, { name: 'session-id', required: true }],
+        options: {
+            follow: { type: 'boolean', short: 'f', description: 'Stream the output until the command exits, then exit with its exit code.' },
+        },
+        examples: ['shard ws exec-read acme/demo build-1', 'shard ws exec-read acme/demo build-1 --follow', 'shard ws exec-read acme/demo build-1 --json'],
+    },
+    {
+        path: ['workspaces', 'exec-cancel'],
+        summary: 'Stop a background exec session: SIGTERM, then SIGKILL after the grace',
+        positionals: [REF, { name: 'session-id', required: true }],
+        options: {
+            grace: { type: 'string', value: '<duration>', description: 'Time between SIGTERM and SIGKILL (e.g. 10s; at most 60s; default 5s).' },
+        },
+        examples: ['shard ws exec-cancel acme/demo build-1', 'shard ws exec-cancel acme/demo build-1 --grace 30s'],
+    },
     { path: ['workspaces', 'exec-input'], summary: 'Write pipe stdin at its acknowledged byte offset', positionals: [REF, { name: 'session-id', required: true }, { name: 'data' }], options: {
             offset: { type: 'string', value: '<bytes>', description: 'Required acknowledged offset (0 initially).' },
             close: { type: 'boolean', description: 'Send EOF after these bytes are accepted.' },
@@ -272,10 +310,16 @@ const KEY_COMMANDS = [
                 description: 'File-first: the execution’s id (8-128 of A-Z a-z 0-9 . _ : -, starting with a letter or digit; default a fresh ex-<uuid>). Running the same command again with the same id returns its recorded result instead of running it twice, so scripts can repeat the call safely.',
             },
             'output-limit': { type: 'string', value: '<bytes>', description: 'File-first: keep at most this many bytes of stdout and of stderr each (1-16777216; default 1 MiB).' },
+            burst: {
+                type: 'boolean',
+                description: 'Processful: run this command on a larger, short-lived burst VM on the workspace’s host and apply its file changes back when it exits (needs the burst execution entitlement). Its processes and tmpfs content do not come back; the workspace’s own processes pause meanwhile. Not with --stdin; cannot be canceled.',
+            },
+            'burst-vcpus': { type: 'string', value: '<n>', description: 'With --burst: the burst VM’s vCPUs (1-32; default the host’s, 8, or the plan’s ceiling when lower).' },
+            'burst-memory': { type: 'string', value: '<mib>', description: 'With --burst: the burst VM’s memory in MiB (512-65536; default the host’s, 8192, or the plan’s ceiling when lower).' },
             verbose: {
                 type: 'boolean',
                 short: 'v',
-                description: 'After the output, print on stderr what ran: file-first: execution id, state, base -> tree revision, replayed, timings and the changed paths (A|M|D path); processful: the session id and exit status.',
+                description: 'After the output, print on stderr what ran: file-first: execution id, state, base -> tree revision, replayed, timings and the changed paths (A|M|D path); processful: the session id and exit status (and with --burst the burst: size, method, applied changes, overhead).',
             },
             ...WAKE_TIMING,
         },
@@ -284,6 +328,7 @@ const KEY_COMMANDS = [
             'shard ws exec acme/demo --cwd /home/user/app --env CI=1 -- bash -lc "npm test"',
             'shard ws exec acme/agent-7 -v --execution-id build-42 --timeout 10m -- bash -lc "make -C /home/user/app"',
             'shard ws exec acme/agent-7 --json -- python3 /home/user/report.py > result.json',
+            'shard ws exec acme/demo --burst --burst-vcpus 16 -v -- bash -lc "cd /home/user/app && go build ./..."',
         ],
     },
     {
@@ -304,7 +349,7 @@ const KEY_COMMANDS = [
         path: ['workspaces', 'fork'],
         summary: 'Fork a workspace into a new key',
         positionals: [REF, { name: 'new-key', required: true }],
-        options: { ...CAPS, ...WAIT },
+        options: { ...CAPS, ...MEMORY_ALLOCATION, ...WAIT },
     },
     {
         path: ['workspaces', 'delete'],

package/dist/commands.js

@@ -8,15 +8,15 @@
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
-import { EXECUTION_ID, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, newExecutionId } from '@shardflux/sdk';
+import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId } from '@shardflux/sdk';
 import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
-import { ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
+import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
 import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -66,6 +66,47 @@ function caps(values) {
         c.disk_gib = parsePositiveInt(disk, 'disk-gib', 1_000_000);
     return Object.keys(c).length ? c : undefined;
 }
+const ALLOCATION_MODES = ['fixed', 'elastic'];
+/**
+ * The caps of `workspaces open` and `workspaces fork` (0.8.0): the resource caps plus the memory allocation. Given caps
+ * replace the stored ones, so they are sent only when a flag was given.
+ */
+function workspaceCaps(values) {
+    const c = caps(values) ?? {};
+    const mode = oneOf(values, 'allocation-mode', ALLOCATION_MODES);
+    const held = str(values['memory-held']);
+    if (held !== undefined && mode !== 'elastic')
+        throw new UsageError('--memory-held needs --allocation-mode elastic (a fixed workspace holds all of --memory-mib)');
+    if (mode !== undefined)
+        c.allocation_mode = mode;
+    if (held !== undefined)
+        c.memory_mib_held = parsePositiveInt(held, 'memory-held', 16_777_216);
+    return Object.keys(c).length ? c : undefined;
+}
+/**
+ * `--burst [--burst-vcpus N] [--burst-memory MIB]` of `workspaces exec` (0.8.0): the exec.run options,
+ * or undefined without --burst.
+ */
+function burstOptions(values, withStdin) {
+    const vcpus = str(values['burst-vcpus']);
+    const mem = str(values['burst-memory']);
+    if (values.burst !== true) {
+        if (vcpus !== undefined || mem !== undefined)
+            throw new UsageError('--burst-vcpus and --burst-memory need --burst');
+        return undefined;
+    }
+    if (withStdin)
+        throw new UsageError('--burst runs the command to completion without stdin; drop --stdin');
+    const o = { burst: 'always' };
+    if (vcpus !== undefined)
+        o.burstVcpus = parsePositiveInt(vcpus, 'burst-vcpus', 32);
+    if (mem !== undefined) {
+        o.burstMemoryMib = parsePositiveInt(mem, 'burst-memory', 65_536);
+        if (o.burstMemoryMib < 512)
+            throw new UsageError('--burst-memory must be between 512 and 65536');
+    }
+    return o;
+}
 /** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds). */
 export function whenIdleSeconds(text) {
     if (/^0+(?:\.0+)?(?:ms|s|m|h)?$/.test(text.trim()))
@@ -414,6 +455,75 @@ export function execExitCode(r) {
         return 128 + r.termSignal;
     return 1;
 }
+/** The longest cancel grace the workspace applies (it waits 5 s without one). */
+const MAX_CANCEL_GRACE_MS = 60_000;
+/** Error codes of a burst's own failure (an output stream's final error event; the session carries it too). */
+const BURST_FAILURES = new Set(['burst_unavailable', 'burst_apply_failed']);
+/**
+ * `shard ws exec-read` (0.8.0): an exec session's output from offset 0, and the session. Without `follow`, the output
+ * that exists now; with it, until the session ends, resuming from the byte offsets read after a dropped stream.
+ * `maxBytes` of each stream are kept for the result (the rest is counted); `onOutput` gets every new chunk.
+ */
+async function readSession(cell, sessionId, opts) {
+    let session = await cell.exec.get(sessionId);
+    const kept = { stdout: [], stderr: [] };
+    const size = { stdout: 0, stderr: 0 };
+    let total = { stdout: 0, stderr: 0 };
+    let reconnects = 0;
+    const live = (s) => s.state === 'starting' || s.state === 'running';
+    for (;;) {
+        let ended;
+        try {
+            const events = await cell.exec.output(sessionId, { stdoutOffset: total.stdout, stderrOffset: total.stderr, follow: opts.follow && live(session), signal: opts.signal });
+            for await (const ev of events) {
+                if (ev.type === 'output' && ev.data !== undefined) {
+                    const stream = ev.stream === 'stderr' ? 'stderr' : 'stdout';
+                    const bytes = Buffer.from(ev.data, 'base64');
+                    const start = ev.offset ?? total[stream];
+                    // A reconnect may resend bytes already printed.
+                    const fresh = start < total[stream] ? bytes.subarray(Math.min(total[stream] - start, bytes.length)) : bytes;
+                    if (fresh.length === 0)
+                        continue;
+                    total = { ...total, [stream]: Math.max(total[stream], start + bytes.length) };
+                    const room = opts.maxBytes - size[stream];
+                    if (room > 0) {
+                        kept[stream].push(fresh.subarray(0, room));
+                        size[stream] += Math.min(room, fresh.length);
+                    }
+                    opts.onOutput?.(stream, fresh);
+                }
+                else if (ev.type === 'exit') {
+                    ended = ev.session ?? (await cell.exec.get(sessionId));
+                    break;
+                }
+                else if (ev.type === 'error' && ev.error && !BURST_FAILURES.has(ev.error.error.code)) {
+                    throw new ShardfluxApiError(502, ev.error, 'cell');
+                }
+            }
+        }
+        catch (err) {
+            if (opts.signal.aborted)
+                throw err;
+            const transient = !(err instanceof ShardfluxApiError) || err.retryable;
+            if (!opts.follow || !transient || reconnects >= 10)
+                throw err;
+        }
+        if (ended)
+            session = ended;
+        else if (opts.follow) {
+            // The stream ended without the exit (a dropped connection, a restarted gateway): continue from the offsets.
+            reconnects += 1;
+            if (reconnects > 10)
+                throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0, 'cell');
+            await new Promise((r) => setTimeout(r, Math.min(2_000, 100 * 2 ** reconnects)).unref());
+            session = await cell.exec.get(sessionId);
+            if (live(session) || total.stdout < session.stdout_size || total.stderr < session.stderr_size)
+                continue;
+        }
+        const text = (b) => new TextDecoder().decode(Buffer.concat(b));
+        return { session, stdout: text(kept.stdout), stderr: text(kept.stderr), truncated: total.stdout > size.stdout || total.stderr > size.stderr, reconnects };
+    }
+}
 async function bestEffortCancel(cell, sessionId) {
     await Promise.race([cell.exec.cancel(sessionId).catch(() => undefined), new Promise((r) => setTimeout(r, 3_000).unref())]);
 }
@@ -496,7 +606,7 @@ function reportExecution(ctx, ref, r, opts) {
 }
 function lifecycleText(verb, w, op) {
     const finished = op.state === 'succeeded' || op.state === 'failed' || op.state === 'canceled';
-    return `${verb} ${w.key} (${w.id}): operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
+    return `${verb} ${w.key !== undefined ? `${w.key} (${w.id})` : w.id}: operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
 }
 /** The project-key commands; handlers.ts adds the account plane's. */
 export const KEY_HANDLERS = {
@@ -590,10 +700,78 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'workspaces exec-start'(ctx, values, [ref, ...argv]) {
+        const timeout = str(values.timeout);
+        const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
         const ws = await resolveWorkspace(ctx, ref);
         const session = await cellOf(ctx, ws).exec.start({ argv, stdin_open: values['stdin-open'] === true,
-            ...(str(values['session-id']) ? { session_id: str(values['session-id']) } : {}), ...(str(values.cwd) ? { cwd: str(values.cwd) } : {}) }, ctx.signal);
+            ...(str(values['session-id']) ? { session_id: str(values['session-id']) } : {}), ...(str(values.cwd) ? { cwd: str(values.cwd) } : {}),
+            ...(timeoutMs !== undefined ? { timeout_ms: timeoutMs } : {}) }, ctx.signal);
         out(ctx, JSON.stringify(session, null, 2) + '\n', session);
+        // 0.8.0: what to do next (stderr, so stdout stays the session's JSON).
+        if (!ctx.json && session.state !== 'failed_to_start')
+            ctx.io.stderr.write(`read it with: shard ws exec-read ${ref} ${session.session_id} --follow; stop it with: shard ws exec-cancel ${ref} ${session.session_id}\n`);
+        return 0;
+    },
+    async 'workspaces exec-read'(ctx, values, [ref, sessionId]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const cell = cellOf(ctx, ws);
+        const follow = values.follow === true;
+        let r;
+        try {
+            r = await readSession(cell, sessionId, {
+                follow,
+                signal: ctx.signal,
+                maxBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
+                ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
+            });
+        }
+        catch (err) {
+            if (ctx.signal.aborted && follow) {
+                throw new InterruptedError(`Stopped following exec session ${sessionId}; the command keeps running.`, undefined, { hint: `stop it with: shard ws exec-cancel ${ref} ${sessionId}` });
+            }
+            throw err;
+        }
+        const s = r.session;
+        // Nothing ran (a cwd that is not a directory, a program not on PATH): exit 6 with the workspace's reason, as ws exec.
+        if (s.burst?.error)
+            throw new ShardfluxApiError(409, { error: { code: s.burst.error.code, message: s.burst.error.message, request_id: '', retryable: s.burst.error.retryable, ...(s.burst.error.details ? { details: s.burst.error.details } : {}) } }, 'cell');
+        if (s.state === 'failed_to_start')
+            throw new ExecStartError(s);
+        if (ctx.json) {
+            ctx.io.stdout.write(json(withTiming(ctx, {
+                session_id: s.session_id,
+                state: s.state,
+                exit_code: s.exit_code ?? null,
+                term_signal: s.term_signal ?? null,
+                timed_out: s.timed_out ?? false,
+                canceled: s.canceled ?? false,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                truncated: r.truncated,
+                reconnects: r.reconnects,
+                ...(s.error ? { error: s.error } : {}),
+                ...(s.burst ? { burst: s.burst } : {}),
+            })));
+        }
+        if (s.state === 'starting' || s.state === 'running') {
+            throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
+        }
+        const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false };
+        if (!ctx.json && result.exitCode === null && !result.timedOut && !(result.termSignal !== null && result.termSignal > 0)) {
+            ctx.io.stderr.write(`exec session ${s.session_id} ended ${s.state} without an exit code${s.error ? `: ${s.error}` : ''}\n`);
+        }
+        return execExitCode(result);
+    },
+    async 'workspaces exec-cancel'(ctx, values, [ref, sessionId]) {
+        const grace = str(values.grace);
+        const graceMs = grace === undefined ? undefined : parseDuration(grace, 'grace');
+        if (graceMs !== undefined && graceMs > MAX_CANCEL_GRACE_MS)
+            throw new UsageError(`--grace must be at most 60s (got "${grace}")`);
+        const ws = await resolveWorkspace(ctx, ref);
+        const s = await cellOf(ctx, ws).exec.cancel(sessionId, graceMs);
+        const ended = s.state !== 'starting' && s.state !== 'running';
+        const status = !ended ? `${s.state} (cancel sent)` : s.canceled ? `canceled${s.term_signal ? ` (signal ${s.term_signal})` : ''}` : `already ${s.state}${typeof s.exit_code === 'number' ? ` (exit code ${s.exit_code})` : ''}`;
+        out(ctx, `exec session ${s.session_id}: ${status}\n`, s);
         return 0;
     },
     async 'workspaces exec-input'(ctx, values, [ref, sessionId, data]) {
@@ -609,7 +787,7 @@ export const KEY_HANDLERS = {
         const template = str(values.template);
         if (!template)
             throw new UsageError('--template <slug> is required for "shard workspaces open"');
-        const c = caps(values);
+        const c = workspaceCaps(values);
         const bind = secretNames(strs(values.secret), '--secret');
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
         const mode = modeFlag(values);
@@ -699,11 +877,14 @@ export const KEY_HANDLERS = {
         const limitText = str(values['output-limit']);
         const outputLimit = limitText === undefined ? undefined : parsePositiveInt(limitText, 'output-limit', MAX_OUTPUT_LIMIT);
         const stdinSource = str(values.stdin);
+        const burst = burstOptions(values, stdinSource !== undefined);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
         const ws = await resolveWorkspace(ctx, ref);
         const cell = cellOf(ctx, ws);
         const cwd = str(values.cwd);
         if (ws.mode === 'file_first') {
+            if (burst)
+                throw new UsageError(`--burst applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)}`);
             // An execution: answered when the command ended. The id is ours, so Ctrl-C can name it.
             const id = executionId ?? newExecutionId();
             let r;
@@ -739,6 +920,7 @@ export const KEY_HANDLERS = {
                 ...(Object.keys(env).length ? { env } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(stdin !== undefined ? { stdin } : {}),
+                ...(burst ?? {}),
                 maxOutputBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
                 ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
                 signal: ctx.signal,
@@ -746,9 +928,14 @@ export const KEY_HANDLERS = {
         }
         catch (err) {
             if (ctx.signal.aborted) {
+                if (burst)
+                    throw new InterruptedError(`Interrupted; burst exec session ${sessionId} keeps running server side (a burst cannot be canceled).`);
                 await bestEffortCancel(cell, sessionId);
                 throw new InterruptedError(`Interrupted; sent cancel to exec session ${sessionId}.`);
             }
+            // A burst's apply that did not complete is finished by a retry of the same session (SDK exec.run / the API).
+            if (burst && err instanceof ShardfluxApiError && err.code === 'burst_apply_failed')
+                ctx.io.stderr.write(`burst exec session ${sessionId}\n`);
             throw err;
         }
         const code = execExitCode(r);
@@ -757,7 +944,14 @@ export const KEY_HANDLERS = {
         const unexplained = r.exitCode === null && !r.timedOut && !(r.termSignal !== null && r.termSignal > 0);
         if (values.verbose === true && !ctx.json) {
             const status = r.timedOut ? 'timed out' : r.canceled ? 'canceled' : r.termSignal ? `killed by signal ${r.termSignal}` : unexplained ? r.session.state : `exit code ${r.exitCode ?? '-'}`;
-            ctx.io.stderr.write(kv([['session', r.sessionId], ['status', status], ['output', `${r.stdoutBytes} bytes stdout, ${r.stderrBytes} bytes stderr`], ['reconnects', String(r.reconnects)]]));
+            ctx.io.stderr.write(kv([
+                ['session', r.sessionId],
+                ['status', status],
+                ['output', `${r.stdoutBytes} bytes stdout, ${r.stderrBytes} bytes stderr`],
+                ['reconnects', String(r.reconnects)],
+                ...(r.memoryGrow ? [['memory grow', memoryGrowText(r.memoryGrow)]] : []),
+                ...(r.burst ? [['burst', burstText(r.burst)]] : []),
+            ]));
         }
         if (ctx.json) {
             ctx.io.stdout.write(json(withTiming(ctx, {
@@ -772,6 +966,8 @@ export const KEY_HANDLERS = {
                 truncated: r.truncated,
                 reconnects: r.reconnects,
                 ...(r.session.error ? { error: r.session.error } : {}),
+                ...(r.memoryGrow ? { memory_grow: r.memoryGrow } : {}),
+                ...(r.burst ? { burst: r.burst } : {}),
             })));
         }
         else if (unexplained) {
@@ -899,7 +1095,21 @@ export const KEY_HANDLERS = {
         const cancel = values['cancel-when-idle'] === true;
         const durable = values.durable === true;
         if (whenIdle === undefined && !cancel) {
-            return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, durable ? { ...o, durable: true, wait: o.wait ?? { timeoutMs: waitTimeout(values), signal: ctx.signal } } : o), ['suspend', 'Suspend']);
+            const suspend = (id, o) => ctx.cloud().workspaces.suspend(id, durable ? { ...o, durable: true, wait: o.wait ?? { timeoutMs: waitTimeout(values), signal: ctx.signal } } : o);
+            if (UUID.test(ref)) {
+                // An id needs no resolve request: the suspend goes straight to it (the API refuses a file-first workspace
+                // itself). Only a UUID that is no workspace id here (404, nothing started) is looked up as a key.
+                try {
+                    const op = await waited(ctx, 'the operation continues server side.', () => suspend(ref, lifecycleOptions(ctx, values, waitTimeout(values))));
+                    out(ctx, lifecycleText('Suspending', { id: ref }, op), op);
+                    return 0;
+                }
+                catch (err) {
+                    if (!(err instanceof ShardfluxApiError && err.status === 404 && err.operationId === undefined))
+                        throw err;
+                }
+            }
+            return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => suspend(ws.id, o), ['suspend', 'Suspend']);
         }
         if (durable)
             throw new UsageError(`${whenIdle !== undefined ? '--when-idle' : '--cancel-when-idle'} cannot be combined with --durable (nothing is suspended now)`);
@@ -1423,7 +1633,7 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'workspaces fork'(ctx, values, [ref, newKey]) {
-        const c = caps(values);
+        const c = workspaceCaps(values);
         const timeoutMs = waitTimeout(values);
         const source = await resolveWorkspace(ctx, ref);
         requireProcessful(source, 'fork', 'A fork');

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { CheckoutStatus, ExecutionResult } from '@shardflux/sdk';
+import type { CheckoutStatus, ExecSession, ExecutionResult } from '@shardflux/sdk';
 export declare const EXIT: {
     readonly ok: 0;
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -76,6 +76,15 @@ export declare class ExecutionPendingError extends Error {
     readonly hint: string;
     constructor(message: string, result: ExecutionResult, hint: string);
 }
+/**
+ * `shard ws exec-read` without --follow (0.8.0): the background command still runs (exit 5, as a file-first execution
+ * that still runs); `hint` names the command that follows it to its end.
+ */
+export declare class ExecSessionRunningError extends HintedError {
+    name: string;
+    readonly session: ExecSession;
+    constructor(message: string, session: ExecSession, hint: string);
+}
 export interface ErrorInfo {
     code: string;
     message: string;

package/dist/errors.js

@@ -97,6 +97,18 @@ export class ExecutionPendingError extends Error {
         this.hint = hint;
     }
 }
+/**
+ * `shard ws exec-read` without --follow (0.8.0): the background command still runs (exit 5, as a file-first execution
+ * that still runs); `hint` names the command that follows it to its end.
+ */
+export class ExecSessionRunningError extends HintedError {
+    name = 'ExecSessionRunningError';
+    session;
+    constructor(message, session, hint) {
+        super(message, hint);
+        this.session = session;
+    }
+}
 const AUTH_CODES = new Set(['unauthenticated', 'invalid_credentials', 'token_invalid', 'forbidden', 'mfa_required', 'email_unverified', 'step_up_required', 'csrf_failed']);
 const KEY_PATTERN = /sfk_[A-Za-z0-9]{8,}_[A-Za-z0-9]+/g;
 /** User session tokens (`sfu_` + 43 base64url characters), also cut short. */
@@ -163,6 +175,8 @@ export function describeError(err) {
     }
     if (err instanceof ExecutionPendingError)
         return { code: 'timeout', message: err.message, execution_id: err.result.executionId, last_state: err.result.state };
+    if (err instanceof ExecSessionRunningError)
+        return { code: 'timeout', message: err.message, last_state: err.session.state, details: { session_id: err.session.session_id } };
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
     if (err instanceof CheckoutTimeoutError) {
@@ -214,7 +228,7 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.timeout;
     if (err instanceof OperationFailedError || err instanceof DurabilityLostError || err instanceof ExecutionFailedError || err instanceof CheckoutEndedError)
         return EXIT.operationFailed;
-    if (err instanceof ExecutionPendingError)
+    if (err instanceof ExecutionPendingError || err instanceof ExecSessionRunningError)
         return EXIT.timeout;
     // A command that could not start exits 6 in both modes, as a failed execution does (0.5.1).
     if (err instanceof ExecStartError)

package/dist/format.d.ts

@@ -1,5 +1,7 @@
-import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } from '@shardflux/sdk';
+import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
+/** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
+export declare function byteSize(n: number): string;
 export declare function json(value: unknown): string;
 export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;
 export declare function kv(pairs: readonly (readonly [string, string])[]): string;
@@ -33,6 +35,12 @@ export declare function suspendWhenIdleText(w: {
     suspend_request: SuspendRequest | null;
     operation: Operation | null;
 }): string;
+/** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
+export declare function memoryText(m: WorkspaceMemory): string;
+/** The grow an exec's start waited for: `delivered 1024 -> 4096 MiB in 175 ms`, `partial 1024 -> 3072 of 4096 MiB in 175 ms`. */
+/** The burst line of `ws exec -v` (0.8.0). */
+export declare function burstText(b: BurstSummary): string;
+export declare function memoryGrowText(g: MemoryGrow): string;
 export declare function workspaceDetail(w: WorkspaceView): string;
 export declare const OPERATION_HEADERS: readonly ["ID", "KIND", "STATE", "REASON", "CREATED", "COMPLETED"];
 export declare function operationTable(ops: readonly Operation[]): string;
@@ -90,6 +98,8 @@ export declare function languageTable(l: TemplateLanguages): string;
 export declare function packageTable(page: TemplatePackagePage): string;
 /** A template: identity, what open resolves to, its versions, and the open version's settings. */
 export declare function templateDetailText(t: TemplateDetail): string;
+/** A version's immutable paths and the size of their image: `/opt/acme, /srv/tools (128.0 MiB)`, or `-`. */
+export declare function immutablePathsText(i: TemplateVersion['immutable'] | undefined): string;
 /** A version's settings, one line per part. */
 export declare function settingsText(s: TemplateSettings): string;
 /** How many changed paths the human output lists before "... N more" (--json lists every one the result has). */

package/dist/format.js

@@ -4,6 +4,10 @@
  * these functions only shape what people read.
  */
 import { durabilityOf, isDurable } from '@shardflux/sdk';
+/** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
+export function byteSize(n) {
+    return n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(2)} GiB`;
+}
 export function json(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -128,6 +132,32 @@ export function suspendWhenIdleText(w, r) {
     const op = r.operation;
     return `A suspend of ${w.key} (${w.id}) is already in progress (operation ${op.id} ${op.kind} ${op.state}); nothing was scheduled.\nwait with: shard operations wait ${op.id}\n`;
 }
+const mib = (n) => (n === null ? '-' : `${n} MiB`);
+/** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
+export function memoryText(m) {
+    if (m.allocation_mode !== 'elastic')
+        return `fixed ${mib(m.promised_mib)}`;
+    return `elastic: promised ${mib(m.promised_mib)}, held ${mib(m.held_mib)}, plugged ${m.plugged_mib === null ? '- (not running)' : `+${m.plugged_mib} MiB`}`;
+}
+/** The grow an exec's start waited for: `delivered 1024 -> 4096 MiB in 175 ms`, `partial 1024 -> 3072 of 4096 MiB in 175 ms`. */
+/** The burst line of `ws exec -v` (0.8.0). */
+export function burstText(b) {
+    const size = [b.vcpus !== undefined ? `${b.vcpus} vCPU` : null, b.memory_mib !== undefined ? `${b.memory_mib} MiB` : null].filter(Boolean).join(' / ');
+    const head = `${b.host}${size ? ` ${size}` : ''}${b.method ? ` (${b.method})` : ''}`;
+    const changes = b.applied
+        ? `applied ${b.written_files ?? 0} files, ${b.written_dirs ?? 0} dirs, ${b.removed ?? 0} removed, ${b.written_bytes ?? 0} bytes`
+        : 'changes not applied';
+    const extra = [
+        b.leftover_killed ? `${b.leftover_killed} leftover processes killed` : null,
+        b.overhead_ms !== undefined ? `overhead ${b.overhead_ms} ms` : null,
+        b.replayed ? 'replayed' : null,
+    ].filter(Boolean);
+    return [head, changes, ...extra].join('; ');
+}
+export function memoryGrowText(g) {
+    const to = g.got_mib === g.want_mib ? `${g.got_mib} MiB` : `${g.got_mib} of ${g.want_mib} MiB`;
+    return `${g.outcome} ${g.from_mib} -> ${to} in ${g.deliver_ms} ms`;
+}
 export function workspaceDetail(w) {
     const c = w.ceilings;
     const startup = startupText(w.startup);
@@ -138,6 +168,8 @@ export function workspaceDetail(w) {
         ['state', `${w.observed_state} (desired ${w.desired_state})`],
         ['ready', isReady(w) ? 'yes' : 'no'],
         ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
+        // Immutable paths (0.8.0): the template version whose immutable paths the workspace has mounted, when it has one.
+        ...(typeof w.template.immutable_version === 'number' ? [['immutable paths', `v${w.template.immutable_version} (mounted read-only)`]] : []),
         // The mode (0.5.0) when the API reports it; a file-first workspace's state is its tree revision.
         ...(w.mode !== undefined ? [['mode', modeText(w.mode)]] : []),
         ...(w.mode === 'file_first' ? [['tree revision', String(w.tree_revision)]] : []),
@@ -145,6 +177,8 @@ export function workspaceDetail(w) {
         ['ceilings', c ? `cpu ${c.cpu_millis}m (${c.sources.cpu_millis}), memory ${c.memory_mib} MiB (${c.sources.memory_mib}), disk ${c.disk_gib} GiB (${c.sources.disk_gib})` : '-'],
         ['grants', pairs(w.grants)],
         ['caps', pairs(w.caps)],
+        // Elastic memory (0.8.0) when the API reports it.
+        ...(w.memory ? [['memory', memoryText(w.memory)]] : []),
         ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
         ['pending', w.pending_reason ?? '-'],
         ...(suspendRequest ? [['suspend when idle', suspendRequestText(suspendRequest)]] : []),
@@ -509,15 +543,30 @@ function buildSource(b) {
     const v2 = b.provenance.recipe_schema === 'shardflux.template-recipe.v2';
     return `recipe${v2 ? ' v2' : ''}${b.provenance.recipe_sha256 ? ` (sha256 ${b.provenance.recipe_sha256.slice(0, 12)})` : ''}`;
 }
+/** What to do about a build that failed on its immutable paths (0.8.0; contracts §34.2), from failure.code and details. */
+function immutableFailureFix(f) {
+    if (f.code === 'immutable_path_missing') {
+        const path = typeof f.details?.path === 'string' ? f.details.path : 'the path';
+        return `make ${path} a directory in the build (a step: mkdir -p ${path}), then build again`;
+    }
+    if (f.code === 'immutable_image_too_large')
+        return 'keep large data outside the immutable paths, then build again';
+    return null;
+}
 export function buildText(b) {
     const settled = b.state === 'published' || b.state === 'failed' || b.state === 'canceled' || b.state === 'succeeded';
     const denied = b.denied_hosts ?? [];
+    const immutable = b.immutable_paths ?? [];
+    const fix = b.failure ? immutableFailureFix(b.failure) : null;
     return (kv([
         ['build', b.id],
         ['template', `${b.template.slug} v${b.target_version ?? '?'}`],
         ['state', `${b.state}${b.failure ? ` (${b.failure.code}: ${b.failure.message})` : ''}`],
+        ...(fix ? [['fix', fix]] : []),
         ['registration', `${b.registration.state}${b.registration.error ? ` (${b.registration.error.code}: ${b.registration.error.message})` : ''}`],
         ['source', buildSource(b)],
+        // Immutable paths (0.8.0): the list the produced version declares.
+        ...(immutable.length ? [['immutable paths', immutable.join(', ')]] : []),
         ['network', b.network.mode === 'none' ? 'none' : `allowlist ${b.network.allow_hosts.join(', ') || '(empty)'}`],
         ...(denied.length ? [['denied hosts', `${denied.join(', ')} (allow one: add it to build.network.extra_hosts and build again)`]] : []),
         ['version', b.template_version ? `${b.template_version.id}${b.template_version.published ? ' (published)' : ' (unpublished)'}` : '-'],
@@ -543,11 +592,25 @@ export function templateDetailText(t) {
         ['draft', t.draft ? `${t.draft.workspace_key} (${t.draft.observed_state})` : '-'],
         ['archived', time(t.archived_at)],
     ]);
+    // Immutable paths (0.8.0): the column appears when a version declares any.
+    const immutable = t.versions.some((v) => v.immutable);
     const versions = t.versions.length
-        ? table(['VERSION', 'STATE', 'SOURCE', 'LAYOUTS', 'CREATED', 'DESCRIPTION'], t.versions.map((v) => [`v${v.version}${v.is_open_version ? ' *' : ''}`, v.state, v.source?.kind ?? '-', v.disk_layouts.join(',') || '-', time(v.created_at), v.description ?? '-']))
+        ? table(['VERSION', 'STATE', 'SOURCE', 'LAYOUTS', ...(immutable ? ['IMMUTABLE PATHS'] : []), 'CREATED', 'DESCRIPTION'], t.versions.map((v) => [
+            `v${v.version}${v.is_open_version ? ' *' : ''}`,
+            v.state,
+            v.source?.kind ?? '-',
+            v.disk_layouts.join(',') || '-',
+            ...(immutable ? [immutablePathsText(v.immutable)] : []),
+            time(v.created_at),
+            v.description ?? '-',
+        ]))
         : 'No versions.\n';
     return `${head}\n${versions}${open?.settings ? `\nsettings of v${open.version}:\n${settingsText(open.settings)}` : ''}`;
 }
+/** A version's immutable paths and the size of their image: `/opt/acme, /srv/tools (128.0 MiB)`, or `-`. */
+export function immutablePathsText(i) {
+    return i ? `${i.paths.join(', ')} (${byteSize(i.bytes)})` : '-';
+}
 /** A version's settings, one line per part. */
 export function settingsText(s) {
     const inputs = Object.entries(s.inputs).map(([n, i]) => `${n} (${i.kind}${i.required ? ', required' : ''}${i.default !== null ? `, default ${JSON.stringify(i.default)}` : ''})`);

package/dist/main.js

@@ -79,6 +79,9 @@ function hintFor(info, cred, file) {
     const policyHint = spendPolicyHint(info);
     if (policyHint)
         return policyHint;
+    const immutable = immutableHint(info);
+    if (immutable)
+        return immutable;
     // File patches: what to do about each refusal. details.index is the 0-based edit (--old) index.
     const reason = info.details?.reason;
     const index = typeof info.details?.index === 'number' ? ` #${info.details.index + 1}` : '';
@@ -166,6 +169,35 @@ function spendPolicyHint(info) {
             return undefined;
     }
 }
+/**
+ * Immutable paths (0.8.0; contracts §34): the build refusals (422 validation_failed per details.reason, with the paths
+ * and base the API names) and a files write under an immutable path (409 conflict read_only_path from the cell).
+ */
+function immutableHint(info) {
+    const d = info.details ?? {};
+    const reason = reasonOf(info);
+    const list = (v) => (Array.isArray(v) ? v.filter((p) => typeof p === 'string').join(', ') : '');
+    if (info.code === 'conflict' && reason === 'read_only_path') {
+        return 'this path is an immutable path of the workspace’s template: read-only, it follows the template’s newest version. Write elsewhere, or change it in the template and build a new version (shard templates get <slug> lists the immutable paths)';
+    }
+    if (info.code !== 'validation_failed')
+        return undefined;
+    if (reason === 'immutable_path_removed') {
+        const removed = list(d.removed);
+        const open = typeof d.open_version === 'number' ? `v${d.open_version}` : 'the open version';
+        return `a new version keeps every immutable path of ${open}: add ${removed || 'them'} back to immutable in template.yaml (adding paths is fine)`;
+    }
+    if (reason === 'immutable_paths_unsupported_base') {
+        if (d.field === 'recipe')
+            return 'this template has immutable paths: build it from a template.yaml (shard templates export <slug>@<version> writes the current one, shard templates build builds it)';
+        const base = typeof d.base === 'object' && d.base !== null ? d.base.name : undefined;
+        return typeof base === 'string' ? `build on a newer version of ${base} (shard templates get ${base} lists its versions)` : 'build on a newer version of the base';
+    }
+    if (reason === 'invalid_path' && typeof d.field === 'string' && d.field.startsWith('recipe.immutable[')) {
+        return `fix ${d.field.slice('recipe.'.length)} in template.yaml (the list counts from 0)`;
+    }
+    return undefined;
+}
 /**
  * 409 conflict host_feature_unavailable (0.5.0): the call is not available for this workspace. Not retryable, so the
  * hint names the fallback that works now.
@@ -258,6 +290,8 @@ const NO_NUDGE_REASONS = new Set([
     'subscription_exists',
     // A stale spend policy (If-Match): the hint names the version to retry with (0.5.1).
     'version_mismatch',
+    // A write under an immutable path (0.8.0): the hint says where to change it.
+    'read_only_path',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback

package/dist/template-yaml.js

@@ -20,6 +20,9 @@ export function initTemplateYaml(base) {
 # build: what goes into the template (languages, packages, files, steps). settings: what a workspace gets when it opens.
 schema: shardflux.template-recipe.v2
 base: ${base}
+# Immutable paths: directories every workspace of this template mounts read-only from its newest published version
+# (workspaces pick up a new version at their next cold boot or resume), e.g. tools or data you ship with each version.
+# immutable: [/opt/acme]
 build:
   # Languages from the platform's table: python, node, go, rust, java (version omitted: the base's default).
   languages: []

package/dist/timing.js

@@ -6,6 +6,7 @@
  * carry no `timing` (network errors, Ctrl-C).
  */
 import { formatTiming } from '@shardflux/sdk';
+import { byteSize } from "./format.js";
 export class TimingRecorder {
     /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
     last = null;
@@ -196,7 +197,7 @@ export class BuildTimer {
 }
 const fmtMs = (ms) => (ms === null ? '-' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
 const short = (sha) => sha.slice(0, 12);
-const bytes = (n) => (n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(2)} GiB`);
+const bytes = byteSize;
 /** One stderr line per build-from-file progress event. */
 export function progressLine(e) {
     if (e.type === 'pack')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.12.0"
+    "@shardflux/sdk": "^0.13.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",