@shardflux/sdk 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -3,6 +3,195 @@
 Every API the README shows is available from the version named here. Breaking changes ship in minor releases and are
 marked **Breaking**.
 
+## 0.14.0 (not yet published)
+
+### Workspaces working at once
+
+Additive. The plan's workspace number caps workspaces working at the same moment; stored workspaces are bounded by
+Retained state.
+
+- A tool call that finds every workspace the plan allows to work at once busy is refused with 429 `quota_exceeded`
+  (retryable, `Retry-After`; `details.limit` `concurrent_workspaces`, `limit_value`, `current`,
+  `retry_after_seconds`). The call did not run, so the SDK sends the same request again after `Retry-After` (at most
+  5 s) within `maxRetries`, for every call: exec starts, stdin, PTY create, keepalive and process signals included.
+  A refusal that outlasts the retries is a `ShardfluxApiError` with `retryAfterSeconds`. `executions.run()` keeps
+  these retries and does not add its own on top; the wake hint is not retried (it never waits).
+- `pty.read()` rejects with the refusal (`ShardfluxApiError`, e.g. 429 `quota_exceeded`, retryable) when an accepted
+  attach is closed with an error body and a 4xxx close code, instead of returning empty output.
+- The API's 403 `quota_exceeded` is not retried, as before. New `details.limit`: `retained_state` (`limit_value` and
+  `current` in GiB): opening a new key and forking are refused while the plan's Retained state is used up; existing
+  workspaces keep running, waking, suspending and resuming. Usage summaries report that allowance with `enforcement`
+  `storage_block` and `cap_state` `storage_blocked`.
+- Regenerated contract types: `ErrorCode` includes `quota_exceeded` for the workspace gateway; allowance
+  `enforcement` adds `storage_block`, `cap_state` adds `storage_blocked`.
+
+## 0.13.1 (not yet published)
+
+Patch, additive: the transport, a documented value, a fix for tool calls across a move and self-healing workspaces.
+`@shardflux/cli` 0.8.1, `@shardflux/mcp` 0.7.1 and the `shardflux` bundle 0.10.1 follow (`^0.13.1`).
+
+### Workspaces recover by themselves
+
+Additive. When the machine a workspace runs on fails, the workspace is suspended, and its next use (a tool call's wake,
+`resume()`, `open()`) restores it: from its own disk, files kept, or from its newest checkpoint. Nothing changes for
+code that already handles a cold resume.
+
+- `cold_boot_reason` / `ServerTiming.coldBootReason` can be `host_lost`: the resume booted the workspace's disk
+  (`resumePath` `cold_boot`, `memoryRestored` false, processes restarted). New type `ColdBootReason`
+  (`'runtime_changed' | 'host_lost'`, open to other strings; the field still accepts any string).
+- `hostLostOf(op)` and `ServerTiming.hostLost`: `result.host_lost` camelCased (`HostLost`: `detectedAt`,
+  `restoredFrom` `'disk' | 'checkpoint'`, `restoredCheckpointId`, `stateAsOf`). A resume from the checkpoint has its
+  state as of `stateAsOf`; a suspend that found the machine failed succeeds with `durable: true` and only
+  `detectedAt` (`restoredFrom` null).
+- `formatTiming()` prints `processes restarted (host_lost)` for the disk, `restored checkpoint <id> (host_lost; state as
+  of <time>)` for the checkpoint, and `host_lost (detected <time>)` for the suspend.
+- Documented operation error codes: `resume_required` (a fork or snapshot of such a workspace before its resume; resume
+  it first; not retryable) and `workspace_storage_unavailable` with `details.reason` `host_lost` (not retryable).
+  `KnownErrorReason` gains `host_lost`.
+
+### Connection reuse
+
+Additive. The call after an agent's pause between tool calls reuses its connection instead of opening a new one.
+
+- On Node 26 the pooled transport keeps an idle connection reusable for 5 minutes (was 4 s), so a request seconds or
+  minutes after the last one skips the TCP and TLS handshake. Pooled sockets send TCP keepalive probes after 60 s
+  idle, so NATs and firewalls along the way keep the connection open. Idle connections never keep a process alive. A
+  supplied `fetch`, other runtimes and `SHARDFLUX_HTTP_KEEPALIVE` work as before.
+- A request the SDK retries (GET, a request with an `Idempotency-Key`, a read-only POST such as files search) whose
+  connection closes before the response arrives is sent again at once on a new connection. That one resend has no
+  backoff and does not count against `maxRetries`; timing records and progress `retry` events list it with
+  `delayMs: 0`. A further failure follows `maxRetries` and backoff as before, and a POST without an
+  `Idempotency-Key` is never sent twice.
+
+### Faster suspend and resume
+
+Additive. `resumePath` / `resume_path` can be `thaw`: a resume that arrives while its suspend is still being
+written continues the same VM in place. Nothing else changes for your code.
+
+### Tool calls across a move
+
+Fix. A tool call made while its workspace finishes a resume or a move now runs once the workspace runs, instead of
+failing with `409 conflict` (`workspace_not_running`).
+
+- When the call's tool token was refused as not running and the wake then found the workspace already running (the
+  resume or move committed in between; `wake` resolves `false`), the call is retried with a current token: the held
+  resume's, or a new one. A refused call never ran, so the retry cannot run it twice. Before, the refusal surfaced.
+- A refusal that comes back while the API keeps reporting the workspace running is retried after 500 ms, within the
+  same 3 wakes and `transitionTimeoutMs`, then surfaces as before.
+- `onProgress` sees the retry as a `tool` event of type `retry`, cause `conflict workspace_not_running (the workspace
+  runs; new token)`.
+- The CLI, the MCP server and the `shardflux` bundle get it through their `^0.13.0` dependency.
+
+## 0.13.0
+
+### Elastic memory
+
+Additive. A workspace may be promised more memory than it holds while idle, and the host grows it when a command needs
+it (opt-in per workspace).
+
+- `Caps.allocation_mode` (`'fixed' | 'elastic'`, type `AllocationMode`) and `Caps.memory_mib_held` on `open()`,
+  `workspaces.fork()` and `workspace.fork()`. Given caps replace the stored ones (caps without `allocation_mode` make
+  the workspace fixed); omitted caps keep the stored layout.
+- `workspace.memory` (`WorkspaceMemory`: `{allocation_mode, promised_mib, held_mib, plugged_mib}`, null on an older
+  API) and `workspace.allocationMode` (`'fixed'` on an older API). `WorkspaceView` carries `caps.allocation_mode`,
+  `caps.memory_mib_held` and `memory` (regenerated contract types).
+- `RunResult.memoryGrow` (`MemoryGrow | null`): the grow the exec's start waited for (`outcome` delivered, partial,
+  missed or failed; `from_mib`, `want_mib`, `got_mib`, `deliver_ms`), from the start's session. `ExecSession`
+  carries `memory_grow`. The `exec` agent tool adds `memory_grow` to its result when a grow ran.
+- `KnownErrorReason` adds `allocation_mode_not_available`, `requires_elastic` and `exceeds_memory_mib` (422
+  `validation_failed`; elastic with file-first is the existing `not_supported_for_mode`).
+
+### Burst execution
+
+Additive. One heavy, run-to-completion command can run on a larger, short-lived burst VM on the workspace's host, and
+its file changes are applied back.
+
+- `RunOptions.burst` (`'never' | 'always'`), `burstVcpus` and `burstMemoryMib` on `exec.run()`; `ExecStartRequest`
+  carries `burst`, `burst_vcpus` and `burst_memory_mib` (regenerated contract types).
+- `RunResult.burst` (`BurstSummary | null`): host, size, method, whether the changes were applied, the change counts,
+  `leftover_killed`, `overhead_ms`, `excluded_paths`, `timings`, `replayed`. `ExecSession.burst` carries it; types
+  `BurstSummary` and `BurstError` are exported.
+- `exec.run()` rejects with `ShardfluxApiError` 409 `burst_unavailable` or `burst_apply_failed` also when the burst
+  fails after its start (the output stream's final error event, or `burst.error` on the ended session), without
+  reconnecting; it does not try to cancel a burst when its `signal` aborts (a burst cannot be canceled).
+- `ErrorCode` adds `burst_unavailable` and `burst_apply_failed`; `KnownErrorReason` adds `burst_mode_not_supported`,
+  `burst_not_supported`, `burst_size_exceeds_plan`, `not_available`, `shared_volumes`, `fence_not_drained`,
+  `apply_pending`, `park_failed`, `workspace_resumed`, `interrupted`, `burst_lost`, `disk_full`, `apply_failed`,
+  `reverted` and `revert_failed`.
+- `workspaceTools(ws, { burst: true })` (opt-in, default off) gives the processful `exec` tool the inputs `burst`,
+  `burst_vcpus` and `burst_memory_mib`, and its result adds `burst`. The default tool schemas are unchanged.
+
+### Background commands in the agent tools
+
+Additive. An agent can start a long command, keep working with the other tools, read its progress and stop it.
+
+- The processful `exec` tool takes `background: true`: it starts the command and returns `{session_id, state}` at
+  once (a failed start adds `error: {code, message, reason}`, as the foreground `exec` gives it). `timeout_ms` goes up
+  to 86400000 (a day); with `background` it is sent only when given. The file-first `exec` is unchanged.
+- New tool `exec_read` (permission `exec`): the session's `state`, `exit_code`, `term_signal`, `timed_out`,
+  `canceled` and output. Without offsets it returns the last `maxOutputBytes` of each stream; `stdout_offset` /
+  `stderr_offset` read from there, and the result's `next_stdout_offset` / `next_stderr_offset` continue where it
+  stopped (`truncated` when more output follows). Text is cut at character boundaries only. `wait_ms` (up to 60000)
+  waits for the command to exit and returns as soon as it does. `burst` and `error` when the session has them.
+- New tool `exec_cancel` (permission `exec`): SIGTERM, then SIGKILL after `grace_ms` (1-60000, default 5000);
+  returns `{session_id, state, exit_code, canceled}`.
+- With `workspaceTools(ws, { burst: true })`, `background: true` together with `burst: 'always'` is refused with
+  `ToolArgumentError` before any request (a burst holds the workspace until it applies its changes); `burst: 'never'`
+  with `background` is an ordinary background start.
+- `exec_read` and `exec_cancel` follow `exec` in `workspaceTools()` on processful workspaces; a file-first workspace
+  does not offer them. Both send the wake hint like the other tools.
+
+### Held fork
+
+Additive. A waited fork returns the running copy and its tool token in one request.
+
+- `workspaces.fork()` and `workspace.fork()` with `wait`: when the API holds the fork (`Prefer: wait`, answered 200
+  with `Preference-Applied`), the copy's handle adopts the returned running view and final-epoch tool token, with no
+  operation poll, view refresh or token request. The request's time counts against `wait.timeoutMs`.
+- `ForkOptions` and `WaitedForkOptions` (exported) add `agentLabel` and `tools`, which choose that token. They are sent
+  only on a server-held fork and need an API with held fork. `wait: { serverWait: false }` keeps polling.
+- An API that does not apply `Prefer` answers 202 as before; the call then polls the operation and refreshes the copy.
+- The fork's progress `request` phase has reason `held` when it asks the server to wait.
+
+### Exec start and output in one request
+
+- `exec.run()` starts the command and follows its output in one request: the start asks for NDJSON
+  (`Accept: application/x-ndjson`) and a cell that supports it answers with the output stream. A dropped stream
+  reconnects by session and byte offsets, never starting the command again. A cell that answers the start with the
+  session JSON gets the output request after it, as before; a start that failed still rejects with `ExecStartError`
+  (or the burst's error).
+- `RunResult.memoryGrow` and `burst` are unchanged: the combined stream's exit event carries the start's
+  `memory_grow`.
+
+### Immutable paths
+
+A template may declare directories as immutable: every workspace of the template mounts them read-only from the
+template's newest published version, picked up at its next cold boot or resume.
+
+- Recipe v2 `immutable` (`TemplateRecipeV2.immutable`, regenerated): the list in `template.yaml`, sent as written by
+  `buildFromFile()`, `buildFromRecipe()` and `builds.create()`. The stored recipe v2 of a build
+  (`TemplateBuildRecipeV2`) and an exported recipe (`versions.recipe()`) carry it.
+- `TemplateVersion.immutable` (`TemplateVersionImmutable`: `{paths, bytes}`, or null when the version declares none),
+  on every version of `templates.get()` and on `open_version`.
+- `TemplateBuild.immutable_paths`: the list the produced version declares (the recipe's, else the open version's).
+  `TemplateBuild.failure.details` carries code-specific fields: `immutable_path_missing` names `details.path`.
+- `workspace.immutableVersion` (`template.immutable_version` of the view): the template version whose immutable paths
+  the workspace has mounted, which can be newer than `template.version`; null when it mounts none.
+- `KnownErrorReason` adds `immutable_path_removed` (422; `details.removed`, `details.open_version`),
+  `immutable_paths_unsupported_base` (422; `details.base`, `details.required_feature`, `details.paths`) and
+  `read_only_path` (409 `conflict` from the files API for a write under an immutable path).
+- **Breaking:** the update policy left the API. Removed: the `UpdatePolicy` type, `TemplateSummary.update_policy`, the
+  regenerated `update_policy` of the workspace view, of `TemplateDefaults` and of the `defaults` inputs, and the reason
+  `update_policy_not_available`. It was always `pinned`; code that read it drops the read.
+
+### Exec cancel grace
+
+- `exec.cancel(id, graceMs?)` takes `graceMs` 0 to 60000 (0 or omitted: 5000), as the cell API now enforces (422
+  `validation_failed` outside it), and waits for the answer up to the grace plus 15 s when that is longer than the
+  client's `timeoutMs`: a command that ignores SIGTERM is answered after the grace and the SIGKILL, not a timeout.
+- The cancel that `exec.run` sends when its `signal` aborts passes `killGraceMs` capped at 60000, so a larger
+  `killGraceMs` still cancels the command.
+
 ## 0.12.0 (release candidate)
 
 Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
@@ -336,7 +525,6 @@ behavior is the automatic version check (below), which makes one background requ
 - New exports: `FeedbackCategory`, `FeedbackContext`, `FeedbackReceipt`, `SendFeedbackParams`, `AccountFeedbackParams`,
   `FEEDBACK_CATEGORIES`, `FEEDBACK_MESSAGE_MAX_LENGTH`.
 
-
 ## 0.8.0 (2026-09-28)
 
 Types only; nothing changes at run time and the API is unchanged.

package/README.md

@@ -108,8 +108,9 @@ const listing = await cell.files.list('/home/user');
 await cell.files.remove('/home/user/data.bin');
 ```
 
-`exec.run()` resumes from byte offsets if the output stream drops; it never starts the command
-twice. Aborting its `signal` also cancels the command in the workspace. File writes are atomic
+`exec.run()` starts the command and streams its output in one request **(0.13.0+)**, resumes from
+byte offsets if the output stream drops, and never starts the command twice. Aborting its `signal`
+also cancels the command in the workspace. File writes are atomic
 and durable (acknowledged after fsync).
 
 `cwd` is an absolute path (commands start in `/home/user` without one). The API refuses a relative
@@ -206,6 +207,12 @@ means depends on `wait`:
 wait again with `cloud.workspaces.waitForOperation(err.operationId)`. Without `wait`, the returned operation is the
 handle for the work in progress: pass its `id` to `waitForOperation()` when you need it finished.
 
+**A waited fork is one request (0.13.0+).** `fork(target, { wait: true })` asks the API to hold the fork until the
+copy runs, and the answer carries the running copy and a tool token for it: the copy's handle is ready with no
+operation poll, view refresh or token request. `agentLabel` and `tools` pick the token it brings back. Its timing is one
+`request` phase with reason `held`; `wait: { serverWait: false }` polls instead. An API without the held fork answers
+at once, and the SDK then waits for the operation and refreshes the copy, as before.
+
 **Durable storage (0.12.0+).** A suspend returns as soon as the workspace is sealed on its host, typically in a few
 hundred ms, and its RAM and CPU are released at that moment. `result.durable` turns `true` when the copy lands in
 durable storage, typically within a second; until then it is `false` and `result.durability` shows the copy's
@@ -289,10 +296,10 @@ await cell.exec.run(['make', 'test']);                         // resumes the wo
 ```
 
 **Detecting a cold resume (0.11.0+).** A resume restores memory and running processes from the checkpoint. After a
-platform runtime update, a resume can boot from the saved disk instead of restoring memory (a cold boot), also when a
-tool call wakes the workspace; check `memoryRestored`. The workspace runs with its files as of the suspend, and its
-processes start fresh, as after a reboot: start dev servers, databases and background jobs again. The resume's timing
-says which it was:
+platform runtime update, or after the machine the workspace ran on failed (0.13.1+), a resume can boot from the saved
+disk instead of restoring memory (a cold boot), also when a tool call wakes the workspace; check `memoryRestored`. The
+workspace runs with its files kept, and its processes start fresh, as after a reboot: start dev servers, databases and
+background jobs again. The resume's timing says which it was:
 
 ```ts
 const t = workspace.lastTiming; // after resume({ wait: true }), wake(), or a tool call that woke the workspace
@@ -303,11 +310,20 @@ if (t?.server?.memoryRestored === false) {
 
 - `ServerTiming.memoryRestored`: `true` when memory and processes came back, `false` when the workspace booted
   (`resumePath` `cold_boot`, or `reset_blank_layer` after a reset), `null` when the API did not say (older APIs).
-- `ServerTiming.coldBootReason`: why it booted (`runtime_changed`), else null. `formatTiming()` prints
-  `resume from cold_boot: processes restarted (runtime_changed)`.
+- `ServerTiming.coldBootReason` (type `ColdBootReason`): why it booted, `runtime_changed` or `host_lost`
+  **(0.13.1+)**, else null. `formatTiming()` prints `resume from cold_boot: processes restarted (runtime_changed)`.
 - The finished resume operation carries the same in `result` (`memory_restored`, `cold_boot_reason`, and
   `cold_boot` with details such as `files_as_of`; it is informational and not part of the stable contract).
 
+**Workspaces recover by themselves (0.13.1+).** When the machine a workspace runs on fails, the workspace is suspended,
+and its next use (a tool call, `resume()`, `open()`) restores it; there is nothing extra to call.
+`hostLostOf(op)` and `lastTiming.server.hostLost` (`HostLost`) say how:
+
+- `restoredFrom: 'disk'`: it booted from its own disk, files kept (`coldBootReason` `host_lost`, processes restarted).
+- `restoredFrom: 'checkpoint'`: it resumed its newest checkpoint (`restoredCheckpointId`); its state is as of
+  `stateAsOf`. `formatTiming()` adds `restored checkpoint <id> (host_lost; state as of <time>)`.
+- A `suspend()` that finds the machine failed succeeds (`result.durable` true, `hostLost.detectedAt`).
+
 `suspend`, `resume`, `fork`, `snapshot` and `delete` return the lifecycle operation.
 `cloud.workspaces.waitForOperation(id)` waits for it (default timeout 5 minutes): each poll asks the API to hold
 the response until the operation changes (`Prefer: wait`, at most 20 s per request), so completion arrives within
@@ -317,7 +333,15 @@ operation keeps running server side (a queued start until its `deadlineAt`); wai
 same call. `templates.builds.waitForBuild()` waits the same way. A waited `open()` issues the first tool token
 together with the final workspace read, so the first tool call starts at once.
 
-From 0.12.0, Node 26 reuses TLS connections through a private HTTP/1.1 pool. Other runtimes keep native fetch. A supplied `fetch` stays unchanged. `SHARDFLUX_HTTP_KEEPALIVE=0` forces connection closure for diagnosis; `=1` opts into native pooling. No global dispatcher is installed.
+From 0.12.0, Node 26 reuses TLS connections through a private HTTP/1.1 pool. From 0.13.0, an idle connection stays
+reusable for 5 minutes, so the call after an agent's pause between tool calls skips the TCP and TLS handshake, and
+pooled sockets send TCP keepalive probes after 60 s idle. Idle connections never keep a process alive. Other runtimes
+keep native fetch. A supplied `fetch` stays unchanged. `SHARDFLUX_HTTP_KEEPALIVE=0` forces connection closure for
+diagnosis; `=1` opts into native pooling. No global dispatcher is installed.
+
+A request the SDK retries (safe methods, requests with an `Idempotency-Key`, read-only POSTs) whose connection closes
+before the response arrives is sent again at once on a new connection **(0.13.0+)**, without backoff and outside
+`maxRetries`; timing records list it with `delayMs: 0`.
 
 List and look up workspaces:
 
@@ -334,6 +358,46 @@ sessions, template drafts and test instances. `findByKey()` searches every lifet
 workspace, and a tombstone only when no live workspace has the key. Use it rather than `listAll({ keyPrefix })` for
 lookups by key.
 
+### Elastic memory (0.13.0+)
+
+Promise a workspace a lot of memory while it holds only what it uses. An elastic workspace idles at its held floor
+(`memory_mib_held`, default 1024) and grows before each command starts, so compilers, test runners and V8 size
+themselves from the memory they will actually get. After 30 s without work it shrinks back. The layout takes effect at
+the workspace's next start.
+
+```ts
+const ws = await cloud.workspaces.open({
+  key: 'customer-42/repo-7',
+  template: 'node',
+  caps: { memory_mib: 8192, allocation_mode: 'elastic' },
+});
+ws.memory;           // { allocation_mode: 'elastic', promised_mib: 8192, held_mib: 1024, plugged_mib: 3072 }
+
+const r = await ws.cell().exec.run(['npm', 'test']);
+r.memoryGrow;        // { outcome: 'delivered', from_mib: 1024, want_mib: 4096, got_mib: 4096, deliver_ms: 175 }
+```
+
+Given `caps` replace the stored ones, so send `allocation_mode` with every `caps` you pass; an open without `caps`
+keeps the stored layout. The exec agent tool adds `memory_grow` to its result when the command's start grew the VM.
+
+### Burst execution (0.13.0+)
+
+Run one heavy command, such as a cold build or a full test suite, on a larger VM without resizing the workspace. With
+`burst: 'always'` the command runs on a short-lived burst VM over a copy of the workspace, output streams as usual,
+and its file changes are applied back byte for byte when it exits.
+
+```ts
+const r = await ws.cell().exec.run(['go', 'build', './...'], { burst: 'always', burstVcpus: 16 });
+r.exitCode;          // 0
+r.burst;             // { host: 'local', vcpus: 16, memory_mib: 8192, method: 'layer', applied: true,
+                     //   written_files: 3, written_dirs: 1, removed: 1, written_bytes: 40960, overhead_ms: 641, ... }
+```
+
+A burst carries back the command's file changes; processes it started and tmpfs content stay in the burst VM, and the
+workspace's own processes resume where they were. A burst is not signalled or canceled. If applying the changes
+fails (`burst_apply_failed`), retry `exec.run` with the same `sessionId` to finish the apply. The agent tools offer
+bursts when asked: `workspaceTools(ws, { burst: true })`.
+
 ### Timing and progress (0.6.0+)
 
 Every open, wake and waited lifecycle call is traced. `workspace.lastTiming` (and `err.timing` when the call fails)
@@ -365,7 +429,7 @@ This resume brought the workspace back from its host's local cache, memory and r
   running, including any time in `capacity_pending`; `ran` is the cell's work (placement, boot or restore, guest
   readiness). `start` / `resume from` and `boot to ready` / `host …` are what the cell reported. A resume that booted
   the saved disk instead of restoring memory reads `resume from cold_boot: processes restarted (runtime_changed)`
-  (0.11.0+).
+  (0.11.0+), or `(host_lost)` (0.13.1+) after the machine the workspace ran on failed.
 - **outside the server** is your total minus the operation's: network, TLS, polling latency, view and token. A large
   value with a small server total points at the connection between you and the API, not at the workspace.
 - **retries** lists transient failures the SDK retried (cause and backoff).
@@ -569,6 +633,27 @@ workspace keeps running so you can inspect it, and `workspace.startup` names the
 The next open runs the failed step again. Versions report their `settings`, platform templates their `category`
 (`os` or `stack`), builds the `denied_hosts` their build network refused (add them to `build.network.extra_hosts`).
 
+### Immutable paths (0.13.0+)
+
+Directories a template declares `immutable` follow the template: every workspace of it mounts them read-only from the
+template's newest published version, so the tools, models or data you ship there reach existing workspaces with your
+next version, at their next cold boot or resume. Everything else in a workspace stays its own.
+
+```yaml
+# template.yaml
+immutable: [/opt/acme]        # read-only in every workspace; follows the newest version
+```
+
+```ts
+const t = await cloud.templates.get('acme-dev');
+console.log(t.open_version?.immutable);              // { paths: ['/opt/acme'], bytes: 100663296 }
+const ws = await cloud.workspaces.open({ key: 'customer-42/main', template: 'acme-dev' });
+console.log(ws.template.version, ws.immutableVersion); // created from v1; /opt/acme shows v2
+```
+
+A build without `immutable` keeps the list of the template's open version, and each new version keeps every path of
+it: add paths, never remove them. A build reports the list its version declares in `immutable_paths`.
+
 ## Agent tools
 
 `workspaceTools(workspace)` returns tools with a name, a description, a JSON Schema for the
@@ -603,6 +688,20 @@ instead of being overwritten. Each call first sends `workspace.hint()` without w
 that off, e.g. when you send the hint yourself as the model starts a tool call), except `read_file`, `list_files` and
 `search_files`: a sleeping workspace answers them from its disk without waking.
 
+**Background commands (0.13.0+).** On a processful workspace `exec` takes `background: true` for anything that runs
+longer than a few minutes (a build, a test suite, a training run, a server): it returns `{ session_id, state }` at
+once and the model keeps using the other tools. `exec_read` reads the command's state, exit code and output (the end
+of each stream, or from the `next_stdout_offset` / `next_stderr_offset` of the previous read; `wait_ms` waits for the
+exit and returns as soon as it happens), and `exec_cancel` stops it. `timeout_ms` (up to a day) sets the longest the
+command may run; the workspace stays awake while it does. A burst (`burst: 'always'`) runs in the foreground.
+
+```ts
+const tools = workspaceTools(workspace);
+const { session_id } = (await executeToolCall(tools, { name: 'exec', input: { command: 'make -j8 test', background: true, timeout_ms: 7_200_000 } })) as { session_id: string };
+// ... other tool calls ...
+const progress = await executeToolCall(tools, { name: 'exec_read', input: { session_id, wait_ms: 30_000 } });
+```
+
 For a file-first workspace (0.9.0+) the tools are `exec` and the files tools only: `exec` runs each command as an
 execution and adds `execution_id`, `state`, `tree_revision` and `changed` to its result, and the process, terminal,
 git and browser tools are not offered. `workspaceTools(ws, { mode })` builds the definitions without touching the
@@ -859,6 +958,14 @@ A read of a sleeping workspace that its disk cannot answer (409 `workspace_not_r
 `host_feature_unavailable` (search or patches are not available for the workspace, `details.feature`) is neither
 retried nor woken: run `grep` with `exec`, or read then write the file, instead.
 
+Immutable paths **(0.13.0+)**: a files write under an immutable path is 409 `conflict` with `reason` `read_only_path`
+(not retried; write elsewhere, or change the template). A build is refused with 422 `validation_failed` and `reason`
+`immutable_path_removed` when its recipe drops a path of the template's open version (`details.removed`; keep them),
+`immutable_paths_unsupported_base` when its base cannot carry immutable paths (`details.base`; build on a newer version
+of that base), or `invalid_path` (`details.field` `recipe.immutable[<i>]`). A build that fails on them has
+`failure.code` `immutable_path_missing` (`failure.details.path` is not a directory in the built filesystem) or
+`immutable_image_too_large`.
+
 ## Usage and overage
 
 `cloud.usage` reads the organization's usage (API keys see organization totals and their own project's workspaces):
@@ -990,7 +1097,7 @@ let ack = await cell.exec.input(session.session_id, 'hello\n', { offset: 0 });
 ack = await cell.exec.input(session.session_id, '', { offset: ack.offset, close: true });
 ```
 
-Input frames are at most 64 KiB. The acknowledged offset counts bytes accepted into the pipe, not bytes consumed by the program. A blocked writer may receive a partial acknowledgement; continue from the returned offset. Retrying the identical last frame is safe. `close` sends EOF only once the entire frame is accepted. Do not combine `stdin_open` with the existing one-shot `stdin` option. The transport writes no separate input log or payload file; program output and full-state snapshots retain their normal persistence. Full-state suspend preserves the pipe. Older hosts/guests explicitly refuse this feature until upgraded (`exec_stdin` / `exec_stdin.v1`). Running sessions count as work within the documented idle-command window; long-running services should declare keepalives or choose `never`.
+Input frames are at most 64 KiB. The acknowledged offset counts bytes accepted into the pipe, not bytes consumed by the program. A blocked writer may receive a partial acknowledgement; continue from the returned offset. Retrying the identical last frame is safe. `close` sends EOF only once the entire frame is accepted. Do not combine `stdin_open` with the existing one-shot `stdin` option. The transport writes no separate input log or payload file; program output and full-state snapshots retain their normal persistence. Full-state suspend preserves the pipe. Where a workspace does not offer it, the start is refused with 409 `conflict`, `reason` `host_feature_unavailable` and `details.feature: 'exec_stdin'`, not retryable. Running sessions count as work within the documented idle-command window; long-running services should declare keepalives or choose `never`.
 
 ```ts
 import { isWorkspaceGone, ShardfluxProtocolError } from '@shardflux/sdk';

package/dist/cell.d.ts

@@ -22,6 +22,7 @@
  * have before sending them (NotSupportedForModeError).
  */
 import type { components, paths } from './generated/cell-api.js';
+import { ShardfluxApiError } from './errors.js';
 import type { WorkspaceMode } from './errors.js';
 import { ExecutionResult } from './executions.js';
 import type { ExecutionGetOptions, ExecutionRunOptions } from './executions.js';
@@ -31,6 +32,24 @@ import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
 export type ExecStartRequest = S['ExecStartRequest'];
 export type ExecSession = S['ExecSession'];
+/**
+ * Elastic memory (0.13.0): the host grew the workspace's memory before an exec started, and the exec
+ * waited for it. `outcome` delivered | partial | missed | failed; `from_mib`, `want_mib`, `got_mib` are guest memory
+ * before, aimed for and after; `deliver_ms` the time to deliver. On the session the start returned; absent when no
+ * grow ran (fixed workspaces, or already at the exec size).
+ */
+export type MemoryGrow = S['MemoryGrow'];
+/**
+ * Burst execution (0.13.0; needs an organization entitlement): the session of
+ * an exec started with `burst: 'always'` ran on a larger, short-lived burst VM on the workspace's host, and its file
+ * changes were applied back (`applied`). `host`, `vcpus`, `memory_mib`, `method`, the change counts
+ * (`written_files`, `written_dirs`, `removed`, `written_bytes`), `leftover_killed` (processes the command left behind:
+ * they do not survive a burst), `overhead_ms`, `excluded_paths`, `timings`, `replayed`; `error` when the burst failed
+ * after the start answered.
+ */
+export type BurstSummary = S['BurstSummary'];
+/** The failure recorded on a burst session (`burst.error`): code `burst_unavailable` or `burst_apply_failed`. */
+export type BurstError = S['BurstError'];
 export type ExecInputResult = S['ExecInputResult'];
 export type OutputEvent = S['OutputEvent'];
 export type PtyOpenRequest = S['PtyOpenRequest'];
@@ -155,8 +174,9 @@ export interface CellClientOptions {
     sleep?: (ms: number) => Promise<void>;
     /**
      * Wakes a suspended workspace (resume, or join the active resume/open) within `timeoutMs` and resolves once it runs;
-     * resolves `false` when there was nothing to wake (the API already reports it running), and the refusal then
-     * surfaces. It throws when the wake fails (OperationFailedError) or outlasts `timeoutMs` (OperationTimeoutError).
+     * resolves `false` when there was nothing to wake (the API already reports it running): the refused call is then
+     * retried with a current token, since the transition that refused it ended meanwhile (0.13.1+). It throws when the
+     * wake fails (OperationFailedError) or outlasts `timeoutMs` (OperationTimeoutError).
      * Workspace.cell() supplies `workspace.wake()`. A call refused with `workspace_not_running` wakes the workspace and is
      * retried; a refused call was never executed, so the retry cannot duplicate it. `null` surfaces
      * the refusal instead. A wake that put a new token into this client's manager (the held resume;
@@ -223,6 +243,10 @@ export interface RunResult {
     session: ExecSession;
     /** Output-stream reconnections performed (gateway restarts, network drops). */
     reconnects: number;
+    /** The memory grow the start of this exec waited for (0.13.0; elastic workspaces), null when none ran. */
+    memoryGrow: MemoryGrow | null;
+    /** The burst summary (0.13.0; `burst: 'always'`), null for an ordinary exec. */
+    burst: BurstSummary | null;
 }
 export interface RunOptions {
     sessionId?: string;
@@ -254,7 +278,24 @@ export interface RunOptions {
      * (details.reason `secret_not_available`, details.names) and nothing runs; a name also present in `env` is 422.
      */
     secretRefs?: string[];
+    /**
+     * Burst execution (0.13.0; needs the organization entitlement `policy.burst_exec`): `'always'` runs this
+     * run-to-completion command on a larger, short-lived burst VM on the workspace's
+     * host over a copy of the workspace disk, and applies its file changes back when it exits (`result.burst`).
+     * Processes it starts and tmpfs content (/tmp when tmpfs, /dev/shm) do not survive; the workspace's own processes
+     * pause meanwhile and writes to it are refused (409). Not with `stdin` (422 burst_not_supported). Refusals: 409
+     * `burst_unavailable` (details.reason not_available, layout_unsupported, host_capacity, ...), 409
+     * `burst_apply_failed` (details.applied_entries/pending_entries; retry with the same `sessionId` to finish the apply).
+     * A burst cannot be canceled: `signal` stops following it, not the command.
+     */
+    burst?: 'never' | 'always';
+    /** Burst VM vCPUs (1-32; default the host's, 8, or the plan's ceiling when lower). */
+    burstVcpus?: number;
+    /** Burst VM memory in MiB (512-65536; default the host's, 8192, or the plan's ceiling when lower). */
+    burstMemoryMib?: number;
 }
+/** The API error of a burst's recorded failure (`burst.error` of its session). Internal (the agent tools use it too). */
+export declare function burstFailure(e: BurstError): ShardfluxApiError;
 /** Parses an NDJSON byte stream into objects (tolerates CRLF and a final unterminated line). */
 export declare function ndjson<T>(body: ReadableStream<Uint8Array>): AsyncGenerator<T>;
 export declare class CellClient {
@@ -280,8 +321,10 @@ export declare class CellClient {
      * One authorized request. Refreshes the token once on stale_epoch / 401. Lifecycle transitions,
      * bounded in total by `transitionTimeoutMs`: a call refused with `workspace_busy` is retried after `Retry-After`; one
      * refused with `workspace_not_running` (or whose token cannot be minted because the workspace is not running) wakes
-     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call.
-     * Refused calls were never executed, so retrying is safe. When the budget is spent the refusal surfaces.
+     * the workspace through `wake`, given the time left, and is retried with a fresh token, at most 3 wakes per call. A
+     * wake that finds the workspace already running (`false`) is retried the same way: the transition that refused the
+     * call ended meanwhile (0.13.1+). Refused calls were never executed, so retrying is safe. When the budget is spent
+     * the refusal surfaces.
      */
     request(method: string, path: string, init?: RequestOptions & TransitionOptions): Promise<Response>;
     /**
@@ -308,6 +351,10 @@ export declare class CellClient {
             signal?: AbortSignal;
         }) => Promise<ExecInputResult>;
         signal: (sessionId: string, signal: Signal, onlyLeader?: boolean) => Promise<ExecSession>;
+        /**
+         * SIGTERM to the process group, SIGKILL after `graceMs` (0 to 60000; 0 or omitted is 5000). Resolves once the
+         * command has ended; the request waits for the grace.
+         */
         cancel: (sessionId: string, graceMs?: number) => Promise<ExecSession>;
         /**
          * Starts (or re-attaches to) a session and collects its output until it exits, reconnecting