@shardflux/cli 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -3,6 +3,115 @@
 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.9.0 (not yet published)
+
+Needs `@shardflux/sdk` 0.14.0 or later.
+
+### Workspaces working at once
+
+- A command whose workspace call finds every workspace the plan allows to work at once busy is sent again after
+  `Retry-After` (the SDK's retries; the call did not run). A refusal that lasts exits 1 with 429 `quota_exceeded`
+  (`details.limit` `concurrent_workspaces`) and the hint `every workspace your plan allows to work at once is busy
+  and the call did not run (it was already retried); retry in 2 s, or upgrade: shard billing plans`.
+- The API's 403 `quota_exceeded` with `details.limit` `retained_state` (opening a new key or forking while the
+  plan's Retained state is used up) hints `delete workspaces you no longer need (shard ws delete <key> --yes), or
+  upgrade: shard billing plans`. Neither suggests `shard feedback`.
+- `--json` errors carry `retry_after_seconds` when the refusal has `Retry-After` (e.g. 429 `quota_exceeded`, 429
+  `rate_limited`).
+- `shard usage` says `retained state  used up: new workspaces and forks are refused (...)` when the Retained state
+  allowance's `cap_state` is `storage_blocked` (`enforcement` `storage_block`).
+
+## 0.8.1 (not yet published)
+
+Needs `@shardflux/sdk` 0.13.1 or later.
+
+### Workspaces recover by themselves
+
+When the machine a workspace runs on fails, the workspace is suspended, and the next command on it resumes it.
+
+- A resume that booted the workspace's own disk (`cold_boot_reason` `host_lost`) prints the cold-boot note with the
+  reason in words: `note: workspace <id> resumed from its saved disk; running processes were restarted (the machine it
+  ran on failed)`.
+- A resume that restored its newest checkpoint prints `note: workspace <id> resumed from checkpoint <id> (state as of
+  <time>) after the machine it ran on failed; changes after that time are not in it` on stderr (also with `--json`,
+  `ws resume --wait`, `operations wait` and a command's wake).
+- `--timing --json`: `server.host_lost` (`detected_at`, `restored_from`, `restored_checkpoint_id`, `state_as_of`).
+  `--timing` prints the SDK's `restored checkpoint <id> (host_lost; state as of <time>)`.
+- `hostLostNotice()` is exported next to `coldBootNotice()`.
+
+## 0.8.0
+
+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`.
@@ -582,11 +607,11 @@ without waking it (the state at suspension); `files search` then notes it on std
   refused at once (exit 1, `workspace_not_running`).
 
 **Detecting a cold resume (0.6.0+).** A resume restores memory and running processes. After a platform runtime
-update, a resume can boot from the saved disk instead of restoring memory (a cold boot), also when a command wakes the
-workspace; check `memory_restored`. The command still runs with the files as of the suspend, and processes start
-fresh, as after a reboot: start dev servers and background jobs again. `shard` then prints one line on stderr after
-the output (also with `--json`, except on a failure, whose stderr is only the error document), whether or not you
-pass `--timing`:
+update, or after the machine the workspace ran on failed (0.8.1+), a resume can boot from the saved disk instead of
+restoring memory (a cold boot), also when a command wakes the workspace; check `memory_restored`. The command still runs
+with the files kept, and processes start fresh, as after a reboot: start dev servers and background jobs again. `shard`
+then prints one line on stderr after the output (also with `--json`, except on a failure, whose stderr is only the
+error document), whether or not you pass `--timing`:
 
 ```text
 note: workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342 resumed from its saved disk; running processes were restarted (runtime_changed)
@@ -596,6 +621,12 @@ note: workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342 resumed from its saved disk
 `cold_boot`, `memory_restored` false, `cold_boot_reason`), and `--timing` shows `resume from cold_boot: processes
 restarted (runtime_changed)`. The same applies to `operations wait` of such a resume.
 
+**Workspaces recover by themselves (0.8.1+).** When the machine a workspace runs on fails, the workspace is suspended,
+and the next command on it resumes it; there is nothing extra to run. From its own disk, the note above ends in
+`(the machine it ran on failed)`; from its newest checkpoint, the note names the checkpoint and the time its state is
+from (`state as of <time>`). `--json` carries `result.host_lost` (`detected_at`, `restored_from` `disk` or
+`checkpoint`, `restored_checkpoint_id`, `state_as_of`), and `--timing` adds `host_lost` to `server`.
+
 ## Suspend when idle (0.5.1+)
 
 A running workspace is billed while it is awake. When an agent's turn ends, ask for a suspend once the workspace has
@@ -617,6 +648,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.
@@ -706,7 +784,7 @@ With `--json`, stdout carries the timing as a `timing` field of the command's JS
 `workspace_id`, `operation_id`, `total_ms`, `phases` (`phase`, `reason`, `operation_id`, `start_ms`, `duration_ms`),
 `retries`, `server` (`queued_ms`, `run_ms`, `total_ms`, `start_path`, `resume_path`, `memory_restored` and
 `cold_boot_reason` (0.6.0+; `memory_restored` is `false` when a resume booted the saved disk, `null` when the API did
-not say), `boot_to_ready_ms`, ...) and `outside_server_ms`. It is `null` when the command made no lifecycle call. On a failure the error document on stderr
+not say), `host_lost` (0.8.1+), `boot_to_ready_ms`, ...) and `outside_server_ms`. It is `null` when the command made no lifecycle call. On a failure the error document on stderr
 carries it: `{"error": {...}, "timing": {...}}`.
 
 For live progress events, use the SDK's `onProgress`.
@@ -788,10 +866,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.1";
 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.1';
 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'],