@shardflux/cli 0.6.2 → 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.
@@ -38,6 +111,29 @@ New organizations can start on a trial: 60 days at Developer limits, no card. Th
 - An interrupted file-first `ws exec` says `(an execution runs to completion)`; `mode_not_available` drops "yet";
   `--open` no longer says "best effort"; `templates init --help` no longer names an internal document.
 
+## 0.7.0 (release candidate)
+
+Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
+
+Uses SDK 0.12.0 and its pooled transport. Adds --labels/--idle-policy to open, --labels to list, ws labels, ws idle, ws exec-start --stdin-open and ws exec-input --offset. Protocol-error JSON includes source. Resume recovers failed workspaces; completed deletion permits key reuse.
+
+Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
+
+### Instant suspend: durable storage
+
+- `shard ws suspend --wait` still returns when the suspend succeeds (sealed on its host); a finished suspend or fork
+  now prints `durable: yes (<n> ms after the suspend)` or `durable: in progress ...` when the result says so.
+- `shard ws suspend --durable`: waits until `result.durable` is true (implies `--wait`, shares `--timeout`). A copy
+  that cannot be made exits 6 with code `durability_lost` (operation id, `details.state` `lost`, `details.reason`); a
+  timeout exits 5 with `details.durable` false and `details.state` `pending`. `--durable` with `--when-idle` or
+  `--cancel-when-idle` is a usage error.
+- `shard operations wait <id> --durable`, and a `durable` line in `operations get|wait` for suspends and forks.
+- `--timing --json`: `server` gains `durable`, `suspend_path`, `durability` and `lost_suspend`.
+- A resume (or a command's wake) whose result carries `lost_suspend` prints a note on stderr naming the restored
+  checkpoint and its time.
+- A suspend-when-idle canceled `workspace_active` says the workspace was in use and keeps running.
+- The `ws suspend` summary no longer says "durable checkpoint".
+
 ## 0.6.1
 
 Needs `@shardflux/sdk` 0.11.0 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). |
@@ -387,9 +388,10 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `files search <id\|key> <path> <pattern> [--regex] [-i\|--ignore-case] [--include G]... [--exclude G]... [--max N]` | Search file contents under a directory (or in one file; gitignore-style globs): `path:line:column: text` per match (0.5.0+). |
 | `files patch <id\|key> <path> (--old T --new T)... [--replace-all] \| --content-file F\|- [--expected-revision R] [--if-revision N]` | Replace exact text (each `--old` must occur once unless `--replace-all`), or the whole content, atomically; `R` is a revision from `files stat --revision` or `absent` (0.5.0+). `--if-revision` (0.5.0+): file-first workspaces only. |
 | `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 delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once. The key of a persistent workspace is never reused. |
+| `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. |
 | `workspaces save-as-template <id\|key> --template <slug> [--display-name N] [--description T] [--checkpoint ID] [--default-lifetime L] [--default-idle-timeout D] [--acknowledge PATH]... [--no-auto-publish] [--wait]` | Save a layered workspace as the next version of an organization template. `--wait` follows the build. |
@@ -403,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+). |
@@ -474,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`.
@@ -616,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.
@@ -787,16 +860,54 @@ 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+)
+
+`shard ws suspend --wait` returns as soon as the workspace is sealed on its host, typically in a few hundred ms, and
+its RAM and CPU are released then. The copy lands in durable storage right after, typically within a second:
+
+```sh
+shard ws suspend acme/demo --wait
+# Suspending acme/demo (<id>): operation <op> suspend succeeded
+# durable: in progress, typically within a second (wait with: shard operations wait <op> --durable)
+shard ws suspend acme/demo --durable      # returns once it is durable: "durable: yes (435 ms after the suspend)"
+shard operations wait <op> --durable      # the same for a suspend or fork you already started
+```
+
+- `--durable` implies `--wait` and shares its `--timeout`.
+- `--json` prints the operation as the API returns it: `result.durable` and `result.durability` (`state`
+  `pending` or `durable`, `local_commit_at`, `durable_at`, ...). `--timing` adds `durable`, `suspend_path` and
+  `durability` to `server`.
+- `operations get|wait` show a `durable` line for suspends and forks. A fork of a running workspace reports its copy the
+  same way.
+- The exit codes and errors of `--durable` are in the CLI reference on docs.shardflux.dev.
 
 ## HTTP connections
 
-By default every request uses a fresh connection (`Connection: close`); `SHARDFLUX_HTTP_KEEPALIVE=1` reuses
-connections.
+`shard` 0.7.0 uses the SDK’s pooled HTTP/1.1 transport on Node 26. Custom fetch is preserved. `SHARDFLUX_HTTP_KEEPALIVE=0` forces connection closure for diagnosis; `=1` opts into native pooling.
 
 ## License
 
 Apache-2.0
+
+
+## Integration controls (0.7.0+)
+
+```sh
+shard ws open qm/project-42 --template python-node-browser --labels '{"scope":"project-42"}' --idle-policy never
+shard ws list --labels '{"scope":"project-42"}' --json
+shard ws labels qm/project-42 --set '{"scope":"project-42","owner":"qm"}'
+shard ws idle qm/project-42 --json
+shard ws idle qm/project-42 --keepalive 60
+shard ws idle qm/project-42 --policy adaptive
+shard ws suspend qm/project-42 --when-idle 2s
+shard ws exec-start qm/project-42 --stdin-open --session-id qm-worker-1 -- cat
+shard ws exec-input qm/project-42 qm-worker-1 hello --offset 0
+shard ws exec-input qm/project-42 qm-worker-1 --offset 5 --close
+```
+
+Use the byte offset in each acknowledgement, including partial writes. `ws resume` can recover a failed workspace with its existing ID and disk. A completed delete frees the key; old IDs remain deleted. Protocol-error JSON includes `source`; HTTP 404 alone does not mean a workspace was deleted.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.6.2";
+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.6.2';
+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: {
@@ -189,6 +198,8 @@ const KEY_COMMANDS = [
         positionals: [{ name: 'key', required: true }],
         options: {
             template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
+            labels: { type: 'string', value: '<json>', description: 'Replace workspace labels with a JSON object of strings.' },
+            'idle-policy': { type: 'string', value: '<policy>', description: 'adaptive, never or fixed:<seconds>.' },
             secret: {
                 type: 'string',
                 multiple: true,
@@ -207,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,
@@ -219,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',
         ],
     },
     {
@@ -228,6 +241,7 @@ const KEY_COMMANDS = [
         options: {
             state: { type: 'string', value: '<state>', description: 'Observed state filter (running, suspended, creating, ...).' },
             prefix: { type: 'string', value: '<key-prefix>', description: 'Only keys starting with this prefix.' },
+            labels: { type: 'string', value: '<json>', description: 'Exact label matches (JSON object; all pairs must match).' },
             ...LIFETIME_FILTER,
             'include-deleted': { type: 'boolean', description: 'Include deleted workspaces and ended sessions (tombstones).' },
             all: { type: 'boolean', description: 'Fetch every page.' },
@@ -235,6 +249,49 @@ const KEY_COMMANDS = [
             cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
         },
     },
+    { path: ['workspaces', 'labels'], summary: 'Read or replace workspace labels', positionals: [REF], options: {
+            set: { type: 'string', value: '<json>', description: 'Replace all labels; {} clears them.' },
+        } },
+    { path: ['workspaces', 'idle'], summary: 'Inspect idle status, set policy or declare a keepalive', positionals: [REF], options: {
+            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',
+        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.' },
+        } },
     { path: ['workspaces', 'get'], summary: 'Show one workspace (state, template, startup)', positionals: [REF], options: {} },
     { path: ['workspaces', 'inputs'], summary: 'Show the text inputs of a workspace (secret inputs are bound secrets: shard ws secrets)', positionals: [REF], options: {} },
     {
@@ -253,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,
         },
@@ -265,26 +328,28 @@ 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 ./..."',
         ],
     },
     {
         path: ['workspaces', 'suspend'],
-        summary: 'Suspend a running workspace (durable checkpoint), now or once it has been idle',
-        description: 'Without options the suspend is requested now. --when-idle (0.5.1+) defers it instead: the workspace is suspended once it has been idle for that long, counted from the later of its last work and the request, so call it when an agent turn ends. A command still running, an attached exec or terminal stream, or a keepalive postpones it; the next tool call (the next turn) or a resume cancels it. Repeating replaces the pending request. --cancel-when-idle cancels it.',
+        summary: 'Suspend a running workspace (memory and processes checkpointed), now or once it has been idle',
+        description: 'Without options the suspend is requested now. With --wait it returns as soon as the workspace is sealed on its host, typically in a few hundred ms; the result\'s durable turns true when the copy lands in durable storage, typically within a second. --durable (0.7.0+) waits for that too. --when-idle (0.5.1+) defers it instead: the workspace is suspended once it has been idle for that long, counted from the later of its last work and the request, so call it when an agent turn ends. A command still running, an attached exec or terminal stream, or a keepalive postpones it; the next tool call (the next turn) or a resume cancels it. Repeating replaces the pending request. --cancel-when-idle cancels it.',
         positionals: [REF],
         options: {
             'when-idle': { type: 'string', value: '<duration>', description: 'Suspend once the workspace has been idle this long (0.5.1+; 0 to 1h, e.g. 0, 30s, 2m; 0 = as soon as it is idle, 0.6.1+). Cannot be combined with --wait.' },
             'cancel-when-idle': { type: 'boolean', description: 'Cancel a pending --when-idle request (0.5.1+; idempotent).' },
+            durable: { type: 'boolean', description: 'Wait until the suspend is in durable storage (result durable: true; 0.7.0+). Implies --wait and shares its --timeout.' },
             ...WAIT,
         },
-        examples: ['shard ws suspend acme/demo --wait', 'shard ws suspend acme/demo --when-idle 2m', 'shard ws suspend acme/demo --cancel-when-idle'],
+        examples: ['shard ws suspend acme/demo --wait', 'shard ws suspend acme/demo --durable', 'shard ws suspend acme/demo --when-idle 2m', 'shard ws suspend acme/demo --cancel-when-idle'],
     },
     { path: ['workspaces', 'resume'], summary: 'Resume a suspended workspace', positionals: [REF], options: { ...WAIT } },
     {
         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'],
@@ -695,7 +760,11 @@ const KEY_COMMANDS = [
         path: ['operations', 'wait'],
         summary: 'Wait for an operation to finish (exit 0 succeeded, 6 failed/canceled, 5 timeout)',
         positionals: [{ name: 'operation-id', required: true }],
-        options: { timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' }, ...TIMING },
+        options: {
+            timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' },
+            durable: { type: 'boolean', description: 'A suspend or fork: also wait until its copy is in durable storage (result durable: true; 0.7.0+).' },
+            ...TIMING,
+        },
     },
 ];
 /** Every command: the account plane first (sign in, set up), then the project-key commands. */