@shardflux/sdk 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,13 +1,59 @@
 # Changelog
 
-Every API the README shows is available from the version named here. Below 1.0, a minor release may break
-compatibility; breaking changes are marked **Breaking**.
+Every API the README shows is available from the version named here. Breaking changes ship in minor releases and are
+marked **Breaking**.
 
-## 0.11.0 (not yet published)
+## 0.12.0 (release candidate)
 
-### A resume that restarted processes says so (cold boot, contracts §12)
+Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
 
-Additive. When the platform's VM runtime changed after a suspend and no host can restore the memory snapshot, the
+Pooled HTTP/1.1 on Node 26 with pinned undici 8.10.2; custom fetch stays unchanged. Labels on open/list and setLabels, typed idle(), keepalive() and setIdlePolicy(). Protocol errors carry source; isWorkspaceGone recognizes only an explicit API workspace_deleted refusal. Exec sessions accept stdin_open and offset-addressed exec.input. Failed workspaces recover through resume/auto-wake with the same ID. Completed deletions free keys for new IDs.
+
+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 in the result
+
+Additive. A suspend returns as soon as the workspace is sealed on its host; the copy lands in durable storage right
+after. This release reads that from the result and can wait for it.
+
+- `suspend({ durable: true })` (`SuspendOptions.durable`, also `cloud.workspaces.suspend(id, { durable: true })`):
+  resolves once `result.durable` is `true`. It implies `wait` and uses the same `timeoutMs`/`signal` (one budget for
+  the suspend and the copy). Rejects with `DurabilityLostError` (new; `durability` with the reason) when the copy
+  cannot be made, and `OperationTimeoutError` with `durable: true` when the time runs out (the copy continues).
+  `suspend({ wait: true })` still resolves when the suspend succeeds, without waiting for the copy.
+- `cloud.workspaces.waitForDurable(operationOrId, waitOptions)`: the same wait for an operation you hold (a suspend, or
+  a fork of a running workspace).
+- `isDurable(op)`, `durabilityOf(op)` (`Durability`: `state` `pending` | `durable` | `lost`, `checkpointId`,
+  `generationId`, `localCommitAt`, `durableBy`, `durableAt`, `localCommitToDurableMs`, `overdueAt`, `reason`) and
+  `lostSuspendOf(op)` (`LostSuspend`, on a resume result). `ServerTiming` gains `durable`, `suspendPath`, `durability`
+  and `lostSuspend`; progress phase `durable` (reason `overdue` past `durableBy`); `formatTiming()` prints them.
+- `Operation.result` is typed with `durable`, `suspend_path`, `durability` and `lost_suspend` (OpenAPI).
+- `OperationFailedError.workspaceActive`: a suspend-when-idle canceled with `workspace_active` (the workspace was in
+  use; nothing changed and it keeps running). `workspace.waitUntilReady()` resolves for it instead of throwing, as
+  `wake()` already did.
+
+Requires the instant-suspend cell release for `durable: false` results; against other servers every succeeded suspend
+is already durable and `durable: true` resolves at once.
+
+## 0.11.1
+
+Wording: messages and JSDoc say what to do, without internals (no behaviour change).
+
+- `OperationTimeoutError` on a queued start: `... it stays queued server side until <deadline_at> and fails with
+  capacity_unavailable if it has not started by then.` (the same words as the Python SDK).
+- JSDoc (IDE hovers): `sendFeedback` goes to the Shardflux team; `capacity_unavailable` is retryable: the start passed
+  its deadline and nothing was started, send it again; `no_execution_host`: the execution cannot be placed right now;
+  `host_feature_unavailable`: the call is not available for this workspace, use the fallback in the hint;
+  `resumePath` `cold_boot`: the saved disk was booted after a platform runtime change, processes restarted; an
+  execution runs to completion; on Node 26 every request uses a fresh connection (`Connection: close`) unless
+  `SHARDFLUX_HTTP_KEEPALIVE=1`.
+- The `formatTiming()` example is a production resume (413 ms).
+
+## 0.11.0
+
+### A resume that restarted processes says so (cold boot)
+
+Additive. After a platform runtime change, the
 cell resumes the workspace by booting its checkpoint's disk (a cold boot), automatically, also when a tool call wakes
 the workspace. The workspace runs and its files are as of the suspend, but every process was restarted. The API passes
 the resume's result through; this release reads it.
@@ -80,7 +126,7 @@ from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overa
   `KnownErrorReason` adds them, the spend-policy refusals (422 `overage_unavailable`, `spend_cap_required`,
   `spend_cap_below_minimum`, `spend_cap_above_plan_price`, `spend_cap_below_charges`) and 409 `version_mismatch`.
 
-### Suspend when idle (contracts §20.6)
+### Suspend when idle
 
 - `workspace.suspendWhenIdle({ afterSeconds, idempotencyKey? })` and `cloud.workspaces.suspendWhenIdle(id, {
   afterSeconds })` (POST /v1/workspaces/{id}/suspend-when-idle): the workspace is suspended once it has been idle for
@@ -94,15 +140,14 @@ from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overa
   count as the next turn and cancel the request.
 - Types `SuspendRequest`, `SuspendWhenIdleOptions`, `SuspendWhenIdleResult`, `SuspendWhenIdleResponse`.
 
-## 0.9.0 (not yet published; npm `latest` is 0.8.0)
+## 0.9.0
 
 Elastic compute (decision 0007): file tools and wake hints for parked workspaces. Additive; older APIs and cell
 gateways keep working (the new calls answer 404 there).
 
 ### File search, patches with revisions, the wake hint
 
-Needs a cell gateway with the contracts §26 routes (`files/search`, `files/patch`, `wake-hint`, revisions); an older
-gateway does not serve them and returns no revisions.
+Uses the `files/search`, `files/patch` and `wake-hint` routes and file revisions.
 
 - `cell.files.search(path, pattern, opts)`: content search under a directory (literal or RE2 with `regex`,
   `caseInsensitive`, `include`/`exclude` globs, `maxMatches`, `maxFileBytes`, `contextLines`). Returns the gateway's
@@ -137,24 +182,22 @@ gateway does not serve them and returns no revisions.
   of a sleeping workspace `offline_unavailable` and `offline_budget` (409 `workspace_not_running`: woken and retried
   like any) and `offline_changed` (503, retried; served by the running workspace).
 - Reads of a suspended workspace without a held token: the API now issues tool tokens for a suspended workspace
-  (contracts §26.4), so `read`, `readText`, `readWithInfo`, `stat`, `list` and `search` of a suspended workspace are
+ , so `read`, `readText`, `readWithInfo`, `stat`, `list` and `search` of a suspended workspace are
   served from its disk without waking it also for a handle that fetches its first token after the suspend (before,
   the token was refused and the call woke the workspace). Any other call still wakes it: the cell refuses it with 409
   `workspace_not_running`. Needs that API; with an older one the token is refused and the call wakes it as before.
 - The agent-tool runner sends no wake hint for `read_file`, `list_files` and `search_files`: a sleeping workspace
   serves them from its disk, and the hint would wake a suspended one (or restore a hibernated one) for nothing.
-- Hosts without the features (contracts §26.7): `KnownErrorReason` adds `host_feature_unavailable` (409 `conflict`,
-  not retryable, `details.feature` `file_search` or `file_patch`): the workspace runs on a host agent that predates
-  the call, until it runs on an upgraded host. It is neither retried nor answered with a wake. Such a host also
-  returns no revisions (`FileInfo.revision`, `readWithInfo().revision` are absent).
+- Workspaces without the features: `KnownErrorReason` adds `host_feature_unavailable` (409 `conflict`,
+  not retryable, `details.feature` `file_search` or `file_patch`): the call is not available for the workspace. It is neither retried nor answered with a wake. Such a workspace also returns no revisions (`FileInfo.revision`, `readWithInfo().revision` are absent).
 - `JsonSchema.pattern`, checked by `validateArgs()`.
 - Types: `FileSearchOptions`, `FileSearchResponse`, `FileSearchRequest`, `FileSearchResult`, `FileSearchMatch`,
   `FilePatchParams`, `FilePatchEdit`, `FilePatchRequest`, `FilePatchResult`, `FileEdit`, `FileRevision`,
   `FileReadResult`, `ServedFrom`, `Residency`, `WakeHintResult`, `HintOptions`, `HintResult`.
 
-### File-first workspaces (contracts §29)
+### File-first workspaces
 
-Needs an API with `FILE_FIRST_WORKSPACES` on and a cell that serves file-first workspaces (contracts §29.8). A
+Needs an API with `FILE_FIRST_WORKSPACES` on and a cell that serves file-first workspaces. A
 file-first workspace has no VM between executions: its state is a versioned file tree under /home/user, and each
 command runs in a fresh VM whose changed files become the next tree revision. Processful workspaces are unchanged.
 
@@ -203,7 +246,7 @@ command runs in a fresh VM whose changed files become the next tree revision. Pr
 - Types: `WorkspaceMode`, `ExecutionResult`, `ExecutionResultBody`, `ExecutionChange`, `ExecutionState`,
   `ExecutionError`, `ExecutionRunOptions`, `ExecutionGetOptions`, `TreeRevisionOptions`.
 
-### Waking a suspended workspace is one request (contracts §22.6)
+### Waking a suspended workspace is one request
 
 Needs an API with the held resume for the single request; against an older API every call below works as in 0.7.0.
 
@@ -222,9 +265,9 @@ Needs an API with the held resume for the single request; against an older API e
   choose the token that comes back; `cell()`'s own wake passes its label and tools. `WorkspacesApi.requestResume()`
   is the bare request (`ResumeAnswer`, `ResumeRequestOptions`, `ResumeResponse`).
 - `CellClient`: after a wake that put a new token into the client's manager, the retry uses it instead of fetching one.
-### The account plane and the version check (contracts §30)
+### The account plane and the version check
 
-Needs an API with CLI sessions and client versions (contracts §30). Every API is additive; the one change in
+Needs an API with CLI sessions and client versions. Every API is additive; the one change in
 behavior is the automatic version check (below), which makes one background request per process.
 
 ### Account plane: `ShardfluxAccount`
@@ -279,9 +322,9 @@ behavior is the automatic version check (below), which makes one background requ
   Off with `SHARDFLUX_NO_UPDATE_CHECK=1` (also `true`, `yes`, `on`) or `NO_UPDATE_NOTIFIER=1`. `fetchBillingCatalog()`
   does not check.
 
-### Feedback straight to the founder (POST /v1/feedback)
+### Feedback straight to the Shardflux team (POST /v1/feedback)
 
-- `cloud.sendFeedback({ message, category?, context? })` sends feedback to the Shardflux founder by email and returns
+- `cloud.sendFeedback({ message, category?, context? })` sends feedback to the Shardflux team by email and returns
   `{ id, receivedAt, duplicate }`. `category`: `bug`, `confusing`, `missing`, `idea`, `praise` or `other` (default).
   `context`: `agent`, `client`, `workspace`, `requestId`, `errorCode`, `command`, `page` (sent in snake_case);
   `client` defaults to `shardflux-sdk-ts/<SDK_VERSION>`.
@@ -316,7 +359,7 @@ Types only; nothing changes at run time and the API is unchanged.
 
 ## 0.7.0 (2026-09-28)
 
-Needs an API with the template editor (contracts §24); every new field is additive and older fields are unchanged.
+Needs an API with the template editor; every new field is additive and older fields are unchanged.
 
 ### Template editor: build a template from template.yaml
 
@@ -337,7 +380,7 @@ Needs an API with the template editor (contracts §24); every new field is addit
   storage refused a PUT: `status`, `code` such as `BadDigest`; never the presigned URL). Exported: `packDirectory`,
   `readTemplateFile`, `parseTemplateText`, the tar writer (`tarHeader`, `tarPadding`, `tarEnd`).
 
-### Template editor: the API surface (contracts §24.6)
+### Template editor: the API surface
 
 - `templates.uploads.request({ sha256, size, kind })`, `templates.uploads.put(bytes | Blob | stream, { kind, sha256?,
   size? })` (PUT with exactly the presigned headers, skipped when the organization has the bytes, confirmed after) and
@@ -406,8 +449,7 @@ docs/decisions/0006-tool-call-capture.md (shared with the Python SDK 0.3.0).
 
 ### Starts that wait for capacity end
 
-The API no longer lets a start (open, resume, restore, fork) wait in `capacity_pending` forever. One that no host
-could admit 15 minutes after it was created fails with `capacity_unavailable` and `retryable: true`: nothing was
+The API no longer lets a start (open, resume, restore, fork) wait in `capacity_pending` forever. One still queued 15 minutes after it was created fails with `capacity_unavailable` and `retryable: true`: nothing was
 started, the concurrency slot is released, and a suspended workspace stays suspended with its state. Before, a VM could
 boot (and bill) long after every wait had given up.
 
@@ -460,8 +502,7 @@ boot (and bill) long after every wait had given up.
   receives the first tool token in the same response; it pre-connects to the workspace's cell meanwhile.
 - `waitForOperation()` and `templates.builds.waitForBuild()` use server-held polls (at most 20 s per request) and
   fall back to backoff (250 ms doubling to 5 s, ±20 % jitter) against a server without them.
-- On Node 26 the default `fetch` sends `Connection: close` (its bundled undici 8 can stall a request on a reused
-  keep-alive connection for tens of seconds). `SHARDFLUX_HTTP_KEEPALIVE=1` or your own `fetch` changes that.
+- On Node 26 the default `fetch` sends `Connection: close` . `SHARDFLUX_HTTP_KEEPALIVE=1` or your own `fetch` changes that.
 
 ### Suspended workspaces wake on use
 

package/README.md

@@ -7,14 +7,14 @@ it later with its disk and memory intact, and fork it. Hand your agent framework
 tools (exec, files, processes, PTY, git, browser) that plug into any model provider, and save your harness's own
 tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 
-> **Early access.** Shardflux is in early access. The API is versioned (`/v1`), but this SDK is
-> below 1.0: a minor release may contain breaking changes (see [Compatibility](#compatibility)).
+> **Compatibility.** The API is versioned (`/v1`). Breaking changes ship only in minor releases and are marked
+> **Breaking** in the changelog (see [Compatibility](#compatibility)).
 
 > **Versions.** This README describes 0.11.0. Anything marked **(0.11.0+)** is not in 0.10.x, **(0.10.0+)** not in 0.9.0, **(0.9.0+)** not in 0.8.x, **(0.8.0+)** not in 0.7.x,
 > **(0.7.0+)** not in 0.6.x and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
-- ESM only, no runtime dependencies, Node.js 24 or later. Reading a YAML template file uses the optional peer
+- ESM only, Node.js 24 or later. Reading a YAML template file uses the optional peer
   dependency `yaml` (`npm install yaml`); JSON template files need nothing.
 - Typed from the published OpenAPI documents.
 - Retries, idempotency keys, operation polling and tool-token refresh are handled for you.
@@ -64,8 +64,7 @@ console.log(formatTiming(again.lastTiming!));            // (0.6.0+) where the r
 ```
 
 `open()` waits until the workspace is running. Opening the same key again never resets it: files,
-installed packages and running processes are still there (a resume restarts processes only in the rare cold boot,
-see "A resume can restart processes" below). The same program is in
+installed packages and running processes are still there. The same program is in
 [`examples/quickstart.ts`](./examples/quickstart.ts).
 
 With 0.5.0, wait for the suspend by its operation instead:
@@ -159,17 +158,17 @@ const { data, revision: current, servedFrom } = await cell.files.readWithInfo('/
   replaces the whole file instead; `expectedRevision: 'absent'` requires that the file does not exist yet. A changed
   file is 409 `conflict` with `reason` `revision_mismatch` and `details.current_revision`; an edit that does not match
   exactly once is 422 `edit_not_found` or `edit_ambiguous` with `details.index`.
-- A suspended workspace whose disk is still on a host is read, listed and searched there without waking it; such
+- A suspended workspace is read, listed and searched from its saved disk without waking it; such
   results say `servedFrom: 'disk'` (`served_from` on search results). Everything else wakes it as usual. This also
   works for a handle without a tool token from before the suspend: the API issues tokens for suspended workspaces.
-- While the fleet is being upgraded, a workspace may run on a host that predates search and patches: they are 409
-  `conflict` with `reason` `host_feature_unavailable` and `details.feature` (`file_search`, `file_patch`), not
-  retryable (read and write the file, or run `grep` with `exec`, instead), and revisions are omitted.
+- If search or patches are not available for a workspace, the call fails with 409 `conflict`, `reason`
+  `host_feature_unavailable` and `details.feature` (`file_search`, `file_patch`), not retryable: run `grep` with
+  `exec`, or read then write the file, instead. Revisions are omitted there.
 
 ### Wake hint (0.9.0+)
 
-An idle running workspace may be parked by its host (frozen or hibernated) and is restored by the next tool call.
-`workspace.hint()` tells the host a tool call is coming so the restore starts earlier: call it when your model starts
+An idle running workspace is parked and restored by the next tool call. `workspace.hint()` says a tool call is
+coming so the restore starts earlier: call it when your model starts
 emitting a tool call, before its arguments are complete. It is cheap and returns at once; a suspended workspace is
 resumed in the background (`result.wake`). The agent tools below send it when each call starts.
 
@@ -188,7 +187,7 @@ await workspace.resume({ wait: true });       // or simply open() the key again
 
 const { workspace: copy } = await workspace.fork({ key: 'customer-42/experiment' }, { wait: true });
 
-await copy.delete();                          // tool access ends immediately; keys are never reused
+await copy.delete();                          // tool access ends immediately; the key can be reused after deletion finishes
 ```
 
 ### Requested or finished
@@ -200,25 +199,47 @@ means depends on `wait`:
 | --- | --- | --- |
 | `await workspace.suspend()` | the suspend is **requested** (usually `queued`; the workspace is still running) | the operation (`Operation`) |
 | `await workspace.suspend({ wait: true })` **(0.6.0+)** | the suspend has **finished** (`workspace.state` is then `suspended`) | the succeeded operation (`FinishedOperation`) |
+| `await workspace.suspend({ durable: true })` **(0.12.0+)** | the suspend has finished **and** its copy is in durable storage (`result.durable` is `true`) | the succeeded operation (`FinishedOperation`) |
 
 `wait` also takes `WaitOptions` (`timeoutMs`, default 5 minutes; `signal`; `onProgress`). A failed operation throws
 `OperationFailedError`. Running out of time throws `OperationTimeoutError`, and the operation continues server side:
 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 start waits for capacity for at most 15 minutes.** An open, resume, restore or fork that no host can admit yet
-waits in `capacity_pending`. Its `error.details.deadline_at` says when it gives up; the `phase` progress event carries
-it as `deadlineAt` **(0.6.2+)**, and so does `OperationTimeoutError` when your wait ends first. A start still pending
-at the deadline fails with `capacity_unavailable`: nothing was started, the concurrency slot is released, and a
-suspended workspace stays suspended with its state. `OperationFailedError.retryable` **(0.6.2+)** is `true` for it,
-so you can tell "retry later" from a definitive failure. The SDK does not retry it for you.
+**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
+progress. Most code needs nothing more: a suspended workspace resumes, is read and is forked the same way either way.
+When your code must know the copy is durable (before deleting a local artifact, or at the end of a job), ask for it:
+
+```ts
+import { durabilityOf } from '@shardflux/sdk';
+
+const op = await workspace.suspend({ durable: true }); // resolves once result.durable is true
+durabilityOf(op);   // { state: 'durable', checkpointId, localCommitAt, durableAt, localCommitToDurableMs, ... }
+```
+
+- `durable: true` implies `wait` and shares its `timeoutMs` and `signal` (e.g. `{ durable: true, wait: { timeoutMs: 60_000 } }`).
+  If the time runs out first, `OperationTimeoutError` has `durable: true` and the copy continues server side.
+- `cloud.workspaces.waitForDurable(operationOrId)` does the same for an operation you already hold, such as a
+  finished fork of a running workspace, whose result carries `durable` and `durability` the same way.
+- `isDurable(op)`, `durabilityOf(op)` and `lastTiming.server.durable` / `.durability` read the fields; `formatTiming()`
+  prints `sealed on host, durable 435 ms later`. Results from before 0.12.0 servers count as durable.
+- The errors reference on docs.shardflux.dev lists what `durable: true` can reject with.
+
+**Start deadlines.** A queued open, resume, restore or fork (`capacity_pending`) has a deadline 15 minutes after it
+was created. Its `error.details.deadline_at` carries the deadline; the `phase` progress event carries it as
+`deadlineAt` **(0.6.2+)**, and so does `OperationTimeoutError` when your wait ends first. A start still pending at the
+deadline fails with `capacity_unavailable`: nothing was started, the concurrency slot is released, and a suspended
+workspace stays suspended with its state. `OperationFailedError.retryable` **(0.6.2+)** is `true` for it, so you can
+tell a retryable failure from a definitive one.
 
 ```ts
 try {
   await workspace.resume({ wait: true });
 } catch (err) {
   if (err instanceof OperationFailedError && err.retryable) {
-    // err.errorCode === 'capacity_unavailable': no host had room; nothing changed. Try again later.
+    // err.errorCode === 'capacity_unavailable': nothing changed; retry.
   } else throw err;
 }
 ```
@@ -229,7 +250,7 @@ A running workspace is billed while it is awake, and its idle policy waits a whi
 agent's turn ends, ask for a suspend once the workspace has been idle for a short time instead:
 
 ```ts
-const { suspendRequest } = await workspace.suspendWhenIdle({ afterSeconds: 60 }); // 30..3600
+const { suspendRequest } = await workspace.suspendWhenIdle({ afterSeconds: 60 }); // 0..3600; 0 = as soon as it is idle
 workspace.suspendRequest;               // { requested_at, after_seconds, not_before } until it applies or is cancelled
 await workspace.cancelSuspendWhenIdle(); // idempotent
 ```
@@ -242,7 +263,7 @@ await workspace.cancelSuspendWhenIdle(); // idempotent
 - It applies under every idle policy, `never` included, and never delays a suspend the policy would do sooner.
 - When a suspend is already in progress, the result's `operation` is that suspend and nothing is recorded.
 - Errors: `ShardfluxApiError` 409 with `reason` `not_running`, `operation_in_progress`, `session_lifetime` or
-  `workspace_deleted`, and 422 `validation_failed` for `afterSeconds` outside 30..3600. A file-first workspace is never
+  `workspace_deleted`, and 422 `validation_failed` for `afterSeconds` outside 0..3600. A file-first workspace is never
   suspended: `NotSupportedForModeError` (409 `not_supported_for_mode`).
 - By id: `cloud.workspaces.suspendWhenIdle(id, { afterSeconds })` and `cloud.workspaces.cancelSuspendWhenIdle(id)`.
 
@@ -267,11 +288,11 @@ const cell = workspace.cell({ transitionTimeoutMs: 30_000 }); // give up waking
 await cell.exec.run(['make', 'test']);                         // resumes the workspace first if it is suspended
 ```
 
-**A resume can restart processes (0.11.0+).** A resume normally restores memory and running processes from the
-checkpoint. When the platform's VM runtime changed after the suspend and no host can restore that memory snapshot, the
-resume boots the checkpoint's disk instead (a cold boot), automatically, also when a tool call wakes the workspace. The
-workspace runs, its files are as of the suspend, but every process was restarted, as after a reboot: start dev
-servers, databases and background jobs again. You can tell from the resume's timing:
+**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:
 
 ```ts
 const t = workspace.lastTiming; // after resume({ wait: true }), wake(), or a tool call that woke the workspace
@@ -285,19 +306,18 @@ if (t?.server?.memoryRestored === false) {
 - `ServerTiming.coldBootReason`: why it booted (`runtime_changed`), 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`; its shape may change, so do not depend on it).
+  `cold_boot` with details such as `files_as_of`; it is informational and not part of the stable contract).
 
 `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
 one round trip of the commit. Against an API without bounded waits (or with `serverWait: false`) it polls with
 backoff (250 ms doubling to 5 s, ±20 % jitter). If the timeout passes, it throws `OperationTimeoutError` and the
-operation keeps running server side (a start waiting for capacity until its `deadlineAt`); wait for it again with the
+operation keeps running server side (a queued start until its `deadlineAt`); wait for it again with the
 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.
 
-On Node 26 the default fetch sends `Connection: close`: its bundled undici 8 can stall a request on a reused
-keep-alive connection for tens of seconds. Pass your own `fetch`, or set `SHARDFLUX_HTTP_KEEPALIVE=1`, to change that.
+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.
 
 List and look up workspaces:
 
@@ -321,28 +341,31 @@ says where the time went, and `formatTiming()` prints it:
 
 ```ts
 const ws = await cloud.workspaces.open({ key: 'customer-42/main', template: 'python-node-browser' });
+await ws.suspend({ wait: true });
+await ws.resume({ wait: true });
 console.log(formatTiming(ws.lastTiming!));
 ```
 
-A slow open (34 s instead of the usual second) then reads, for example:
+The resume then reads, for example:
 
 ```text
-open 34.18 s, succeeded (workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342, operation 01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33)
-  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 590 ms → view 42 ms ∥ token 61 ms
-  server: queued 33.40 s, ran 620 ms, total 34.02 s; start warm, boot to ready 79 ms
-  outside the server: 161 ms
+resume 413 ms, succeeded (workspace 01a0ead6-92e5-7d19-ab7a-f565bf4676cb, operation 01a0ead6-bd61-737a-ae88-66e2d01a6e25)
+  client: request 218 ms → queued 195 ms
+  server: queued 51 ms, ran 290 ms, total 341 ms; resume from local_cache, boot to ready 211 ms, host disk 0 ms, load 6 ms, ready 62 ms, total 211 ms, after_restore 36 ms
+  outside the server: 72 ms
 ```
 
-Here the time went to waiting for a host with capacity; the network and the VM start were fast.
+This resume brought the workspace back from its host's local cache, memory and running processes included, in 341 ms on the server and 413 ms end to end.
 
 - **client** phases are on your monotonic clock: the request (a held open waits on the server, `held`), then each
   operation state the SDK observed while waiting, with the server's reason (`capacity_pending` / `no_ready_host`:
-  waiting for a host; `running` / `template_downloading`: fetching the template), then reading the workspace and
+  queued to start; `running` / `template_downloading`: fetching the template), then reading the workspace and
   issuing the first tool token (together).
 - **server** timing comes from the operation itself (one database clock): `queued` is creation until it began
-  running, including any wait for capacity; `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+).
+  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+).
 - **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).
@@ -426,13 +449,13 @@ await cell.files.write('/home/user/app/main.py', 'print("bye")\n', { ifTreeRevis
 ```
 
 - **Executions are idempotent by id.** `executionId` defaults to a fresh `ex-<uuid>`; pass your own to make a call safe
-  to repeat across processes. Network failures and retryable 5xx answers (503 `no_execution_host`: no host has room;
-  the SDK waits `Retry-After`) are retried with the same id, at most `maxRetries` (5) times, and an answer that takes
-  longer than `attemptTimeoutMs` (300 s) is awaited again with the same id. The cell runs a command once per id: a
+  to repeat across processes. Network failures and retryable 5xx answers (503 `no_execution_host`: the execution
+  cannot be placed right now; the SDK waits `Retry-After`) are retried with the same id, at most `maxRetries` (5)
+  times, and an answer that takes longer than `attemptTimeoutMs` (300 s) is awaited again with the same id. The cell runs a command once per id: a
   repeated call gets the recorded result (`r.replayed`). The SDK never retries with a new id: a `failed` or `lost`
   result is returned, and running it again is your decision.
 - `ws.executions.get(id, { waitMs })` reads an execution: `pending` while it runs, its result when it ended (kept 7
-  days). Use it after a call that stopped waiting (an aborted `signal`): an execution cannot be canceled.
+  days). Use it after a call that stopped waiting (an aborted `signal`): an execution runs to completion.
 - While an execution runs, other executions and file writes are refused with 409 `workspace_busy`
   (`execution_in_progress`); the SDK waits them out within `transitionTimeoutMs` (120 s).
 - Only paths under /home/user exist (`outside_tree_root` otherwise). Reads, writes, `search()` and `patch()` work as on
@@ -440,7 +463,7 @@ await cell.files.write('/home/user/app/main.py', 'print("bye")\n', { ifTreeRevis
 - Calls a file-first workspace does not have fail with `NotSupportedForModeError` before any request: exec sessions
   (`cell.exec.*`), PTY, processes, git, browser, `changes()`, `suspend`, `resume`, `snapshot`, `fork`, `reset` and
   `saveAsTemplate`. On a processful workspace `executions` and `ifTreeRevision` are refused the same way.
-- Reopening a key with another `mode` is 409 `mode_mismatch`; a deployment without file-first workspaces answers 422
+- Reopening a key with another `mode` is 409 `mode_mismatch`; an account without file-first workspaces gets 422
   `mode_not_available`; a legacy template 409 `layout_unsupported`.
 
 ## Templates: file tree, diff and dev mode
@@ -689,10 +712,9 @@ pending: past that, while the workspace takes no writes, a call is not recorded
 `onError` gets `queue_full`). A write is retried for `retryWindowMs` (120 s) and then dropped (`write_failed`).
 Observing an async tool marks its promise handled: if your code never awaits a wrapped tool's promise and it rejects,
 Node reports no `unhandledRejection` for it (the error is still in the index; Node has no way to observe a rejection
-without handling it). About one write per call: more than roughly 100 calls per second per
-workspace reaches the pending limit. `Response`, `ReadableStream`, Node streams and `Blob` results are never read
-(`meta.note: "stream_not_captured"`). On template v1 the files API writes as root, so the agent can read the captured
-files but not change them. The format is specified in `docs/decisions/0006-tool-call-capture.md`.
+without handling it). About one write per call: the default limits handle about 100 calls per second per workspace;
+raise the pending limits for more. `Response`, `ReadableStream`, Node streams and `Blob` results are never read
+(`meta.note: "stream_not_captured"`). On template v1, captured files are read-only to the agent.
 
 ## Secrets
 
@@ -803,10 +825,9 @@ changes.
   (`details.reason`, e.g. `not_session`, `draft_not_found`, `legacy_disk_layout`; see `KnownErrorReason`).
 - `OperationFailedError`: an awaited operation ended `failed` or `canceled` (`errorCode`,
   `retryable` **(0.6.2+)**, `operation`, `timing`). `retryable` is the operation error's own flag: `true` for
-  `capacity_unavailable` (no host could admit the start before its deadline; retry later), `false` for a definitive
-  failure.
+  `capacity_unavailable` (the start passed its deadline; retry it), `false` for a definitive failure.
 - `OperationTimeoutError`: waiting gave up; the operation continues (`operationId`, `lastState`, `lastReason`,
-  `deadlineAt` **(0.6.2+)** while it waits for capacity, `timing`).
+  `deadlineAt` **(0.6.2+)** while a start is queued, `timing`).
 - `ShardfluxProtocolError`: a response was not the documented shape.
 - `NotSupportedForModeError` **(0.9.0+)**, a `ShardfluxApiError` (409 `conflict`, `reason` `not_supported_for_mode`):
   the call does not exist for the workspace's `mode`; `local` is true when the SDK refused it without a request.
@@ -829,14 +850,14 @@ carries `reason` **(0.9.0+)**:
 `details.spend_cap` is `{ cap_minor, effective_cap_minor, charges_minor, currency }` (minor units, `null` when the plan
 has no overage). An older API sends no `reason`. Do not retry these in a loop.
 
-Retryable 429/502/503/504 refusals (for example 503 `host_capacity`, when the workspace's host has no room to restore
-it right now, or `wake_failed`) are retried after `Retry-After` for reads, searches and calls that carry an
+Retryable 429/502/503/504 refusals (for example 503 `host_capacity` when the workspace cannot be woken right now, or
+`wake_failed`) are retried after `Retry-After` for reads, searches and calls that carry an
 Idempotency-Key (writes and patches); other calls surface them with `retryable: true` and `retryAfterSeconds`.
 A read of a sleeping workspace that its disk cannot answer (409 `workspace_not_running` with `reason`
 `offline_unavailable` or `offline_budget`) wakes the workspace and is retried like any `workspace_not_running`; 503
 `offline_changed` (the disk changed during the read) is retried and served by the running workspace. 409 `conflict`
-`host_feature_unavailable` (the workspace's host predates the call, `details.feature`) is neither retried nor
-woken: it lasts until the workspace runs on an upgraded host.
+`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.
 
 ## Usage and overage
 
@@ -870,10 +891,10 @@ is charged on the next invoice until the charges reach the spend cap.
 
 ## Feedback (0.9.0+)
 
-`cloud.sendFeedback()` sends a message straight to the Shardflux founder, who reads every one. If you or your coding
+`cloud.sendFeedback()` sends a message straight to the Shardflux team, who read every one. If you or your coding
 agent hit something while building with Shardflux, send it the moment it happens: a call that failed unexpectedly, an
-error or doc that was confusing, something missing or slow, a workaround you needed. Short and specific beats polished;
-the request id and error code let the founder find the logs.
+error or doc that was confusing, something missing, a workaround you needed. Short and specific beats polished;
+the request id and error code let the team find the logs.
 
 ```ts
 try {
@@ -881,7 +902,7 @@ try {
 } catch (err) {
   if (err instanceof ShardfluxApiError) {
     await cloud.sendFeedback({
-      message: 'open failed with capacity_unavailable twice in 10 minutes; expected a start within a minute',
+      message: 'open rejected template "python-node" with template_not_found; expected a suggestion of the closest slug',
       category: 'bug',
       context: { requestId: err.requestId, errorCode: err.code, workspace: 'acme/demo', agent: 'claude-code' },
     });
@@ -933,7 +954,7 @@ or no longer supported, it emits one warning:
 
 - The SDK follows the API's `/v1` contract. New fields, enum values and error codes can appear in
   any release; ignore unknown fields.
-- While below 1.0, a breaking change bumps the minor version (0.7 to 0.8).
+- Breaking changes ship only in minor releases (0.7 to 0.8) and are marked **Breaking** in the changelog.
 - `SDK_VERSION` is exported; requests send `User-Agent: shardflux-sdk-ts/<version>`.
 - Examples in this README, in `examples/` and on shardflux.dev name the version they need. The examples on the
   website and in the console are checked against the version published on npm before they ship.
@@ -941,3 +962,44 @@ or no longer supported, it emits one warning:
 ## License
 
 Apache-2.0
+
+
+## Workspace integrations (0.12.0+)
+
+```ts
+const ws = await cloud.workspaces.open({ key: 'qm/project-42', template: 'python-node-browser',
+  labels: { scope: 'project-42', owner: 'qm' }, idlePolicy: 'never' });
+const matches = await cloud.workspaces.list({ labels: { scope: 'project-42' } });
+await ws.setLabels({ scope: 'project-42', owner: 'qm' }); // replaces all labels; {} clears
+await ws.setIdlePolicy('adaptive'); // null restores the inherited policy
+const idle = await ws.idle(); // read-only, does not wake or record activity
+await ws.keepalive(60); // seconds; never shortens an existing keepalive
+await ws.suspendWhenIdle({ afterSeconds: 2 }); // one safe server-side request; no /idle + suspend race
+```
+
+Labels are exact string pairs (at most 50, keys 1–64 and values 0–256 characters); they are metadata, not secrets.
+A failed workspace is recoverable: `await ws.wake()` and ordinary auto-waking calls restart that ID using its existing disk. They do not create a replacement workspace. A failed attempt still raises its operation error; there is no unbounded restart loop.
+After `await ws.delete({ wait: true })`, opening its key creates a **new ID**. The old ID, tokens and history remain deleted. A key stays reserved while deletion is in progress.
+
+For a background command with a pipe (no PTY):
+
+```ts
+const cell = ws.cell();
+const session = await cell.exec.start({ session_id: 'qm-worker-1', argv: ['cat'], stdin_open: true });
+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`.
+
+```ts
+import { isWorkspaceGone, ShardfluxProtocolError } from '@shardflux/sdk';
+// isWorkspaceGone(error) is true only for an explicit API workspace_deleted refusal.
+// A protocol error, a cell 404, a scoped API 404 or a network failure is never deletion evidence.
+```
+
+`ShardfluxProtocolError.source` is `api` or `cell` for SDK responses (`unknown` only for an error constructed without a source by older caller code). It remains a protocol failure even when `status === 404`. Never delete local data based on an HTTP status alone.
+
+### Repositories with a minimum release age
+
+Keep your repository's age policy. Pin an exact version that has aged enough; do not exempt the entire `@shardflux/*` scope. The first SDK, 0.5.0, was published September 26, 2026 at 21:13:52 UTC and reaches seven days on October 3 at that time. New versions, including 0.12.0, need their own seven days after publication. Before then no registry setting on our side can make them eligible. `npm view @shardflux/sdk time --json` shows publication times. A targeted exception for an inspected exact release is a repository-owner decision, not an installation requirement we bypass. Older versions do not contain this release's fixes.

package/dist/account.d.ts

@@ -1,5 +1,5 @@
 /**
- * The account plane with a user session (0.9.0; contracts §30): what a person does in the web app, from code.
+ * The account plane with a user session (0.9.0): what a person does in the web app, from code.
  *
  *   // Before a session exists (no token needed)
  *   await ShardfluxAccount.register({ email, password, displayName });
@@ -102,7 +102,7 @@ export interface ShardfluxAccountOptions {
     sessionToken?: string;
     /** Default https://api.shardflux.dev. */
     baseUrl?: string;
-    /** Default: the runtime's fetch, with `Connection: close` on Node 26 (see defaultFetch in http.ts). */
+    /** Default: pooled HTTP/1.1 on Node 26+, native fetch on other runtimes (see defaultFetch in http.ts). */
     fetch?: typeof fetch;
     userAgent?: string;
     /** Per-request timeout (ms), default 30 s. */
@@ -451,7 +451,7 @@ export declare class ShardfluxAccount {
     /** The signed-in user and their memberships. */
     me(): Promise<Me>;
     /**
-     * Send feedback straight to the Shardflux founder as the signed-in user (0.9.0+; POST /v1/feedback), optionally about
+     * Send feedback straight to the Shardflux team as the signed-in user (0.9.0+; POST /v1/feedback), optionally about
      * one of your organizations (`organizationId`). Otherwise the same as `Shardflux.sendFeedback`: use it while you work,
      * returns `{ id, receivedAt, duplicate }`, never retried, 429 `rate_limited` per user.
      */

package/dist/account.js

@@ -571,7 +571,7 @@ export class ShardfluxAccount {
         const b = body;
         if (b && typeof b === 'object' && typeof b.session_token === 'string') {
             if (!isSessionToken(b.session_token))
-                throw new ShardfluxProtocolError('the API returned a session_token that is not a CLI session token (sfu_...)', 200);
+                throw new ShardfluxProtocolError('the API returned a session_token that is not a CLI session token (sfu_...)', 200, 'api');
             this.#token = b.session_token;
             const expiresAt = typeof b.session_expires_at === 'string' ? b.session_expires_at : '';
             await this.#onSessionToken?.({ token: b.session_token, expiresAt });
@@ -583,7 +583,7 @@ export class ShardfluxAccount {
         return this.#ctx.http.json('GET', '/v1/me', {}, this.#ctx.authorization);
     }
     /**
-     * Send feedback straight to the Shardflux founder as the signed-in user (0.9.0+; POST /v1/feedback), optionally about
+     * Send feedback straight to the Shardflux team as the signed-in user (0.9.0+; POST /v1/feedback), optionally about
      * one of your organizations (`organizationId`). Otherwise the same as `Shardflux.sendFeedback`: use it while you work,
      * returns `{ id, receivedAt, duplicate }`, never retried, 429 `rate_limited` per user.
      */