@shardflux/mcp 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,7 +1,48 @@
 # Changelog
 
-Every tool, field and variable the README shows is available from the version named here. Below 1.0, a minor release
-may break compatibility; breaking changes are marked **Breaking**. Versions before 0.3.0 were not published.
+Every tool, field and variable the README shows is available from the version named here. Breaking changes ship in
+minor releases and are marked **Breaking**. Versions before 0.3.0 were not published.
+
+## 0.5.2
+
+Needs `@shardflux/sdk` 0.11.1 (the workspace version).
+
+Wording: the server instructions, tool descriptions and error hints say what to do, without internals (no behaviour
+change).
+
+- `send_feedback` goes to the Shardflux team (`note`: `Delivered to the Shardflux team. Keep sending feedback as you
+  work.`); the instructions and description ask agents to also pass on what their user asks for (a capability, an
+  option or a smoother workflow) and their ideas. `error_code` shows `e.g. template_not_found`.
+- The instructions: a queued start (open, resume, fork) has a deadline 15 minutes after it was created; past it, it
+  fails with code `operation_failed`, `details.error_code` `capacity_unavailable` and `retryable` true. Nothing was
+  started, so send it again. The `capacity_unavailable` message ends `The start passed its deadline and nothing was
+  started; send it again.`
+- `exec` on a file-first workspace and the instructions say `an execution runs to completion` (before: "cannot be
+  canceled"); the timeout message says `(a file-first execution runs to completion)`.
+- Hints: `no_execution_host`: `The execution cannot be placed right now and nothing ran; retry in a few seconds.`
+  `host_feature_unavailable`: `search_files is not available for this workspace. Search with exec instead, ...
+  Retrying does not help.` (the same for `edit_file` and other tools). `mode_not_available` drops "yet".
+
+## 0.6.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 label creation/filtering, workspace_idle, workspace_keepalive, workspace_set_idle_policy, workspace_set_labels, workspace_exec_start and workspace_exec_input. Exec tools follow key permissions and are hidden for file-first workspaces. Protocol errors include source.
+
+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
+
+- Operations in tool results carry `durable`, `suspend_path`, `durability` (suspend, fork) and `lost_suspend` (resume)
+  when the result has them; `timing.server` adds `durable` and `durability_state`.
+- `workspace_suspend` takes `durable: true`: returns once the copy is in durable storage (implies `wait`; not with
+  `after_seconds`). A copy that cannot be made is the tool error `durability_lost` (`operation_id`, `details.state`
+  `lost`, `details.reason`); a durable wait that runs out is `timeout` with `details` `{durable: false, state:
+  "pending"}` and says to call `operation_wait` with `durable: true`.
+- `operation_wait` takes `durable: true` (a suspend or fork).
+- A resume whose result carries `lost_suspend` adds a `notice` naming the checkpoint it resumed from.
+- A suspend-when-idle canceled `workspace_active`: the `operation_failed` message says the workspace keeps running.
+- `workspace_suspend` no longer describes the suspend as a "durable" checkpoint.
 
 ## 0.5.1
 
@@ -16,8 +57,7 @@ it. The result's `message` then says `the workspace is suspended as soon as it i
 
 Needs `@shardflux/sdk` 0.11.0 (the workspace version).
 
-A resume that restarted processes says so (cold boot, contracts §12). When the platform's VM runtime changed after a
-suspend and no host can restore the memory snapshot, the cell resumes the workspace by booting its saved disk,
+A resume that restarted processes says so (cold boot). After a platform runtime change, the cell resumes the workspace by booting its saved disk,
 automatically, also when a workspace tool wakes it. Files are as of the suspend; every process was restarted.
 
 - `timing.server` of results and error results adds `memory_restored` (when the API reports it: `false` for a cold
@@ -59,7 +99,7 @@ Opt-in overage with a spend cap (through `@shardflux/sdk` 0.10.0):
 - A start refused with 402 `allowance_exhausted` comes back with `reason` `allowance_used`, `overage_paused` or
   `spend_cap_reached` and `details.spend_cap` (errors already carried `details`).
 
-Suspend when idle (contracts §20.6):
+Suspend when idle:
 
 - `workspace_suspend` takes an optional `after_seconds` (30-3600): suspend when idle instead of now. The workspace is
   suspended once it has been idle that long; the agent's next tool call on it cancels that, and a running command or a
@@ -69,11 +109,11 @@ Suspend when idle (contracts §20.6):
 - Workspace summaries (`workspace_status`, `workspace_list`, `workspace_open`) carry `suspend_request`: the pending
   request, or null.
 
-## 0.4.0 (not yet published; npm `latest` is 0.3.1)
+## 0.4.0
 
 Needs `@shardflux/sdk` 0.9.0 (the workspace version).
 
-File-first workspaces (contracts §29):
+File-first workspaces:
 
 - `workspace_open` takes `mode` (`processful` | `file_first`); `SHARDFLUX_WORKSPACE_MODE` sets the default. Workspace
   results (`workspace_open`, `workspace_status`, `workspace_list`) carry `mode` and, for file-first workspaces,
@@ -92,7 +132,7 @@ File-first workspaces (contracts §29):
   `current_tree_revision`), `outside_tree_root`, `execution_in_progress`, `execution_id_reused`, `no_execution_host`.
 - The server instructions describe file-first workspaces.
 
-Waking a suspended workspace is one request (contracts §22.6, through `@shardflux/sdk` 0.9.0):
+Waking a suspended workspace is one request (through `@shardflux/sdk` 0.9.0):
 
 - A workspace tool on a suspended workspace wakes it with one held resume that returns the running workspace and this
   server's tool token (its agent label), then runs the tool; the wake's `timing` is one `request(held)` phase. An API
@@ -100,7 +140,7 @@ Waking a suspended workspace is one request (contracts §22.6, through `@shardfl
 - `workspace_resume` with `wait` goes through the server's workspace handle: one held request, after which the handle
   holds the view and the token, so the next workspace tool starts without a token request.
 
-File tools and the wake hint (contracts §26):
+File tools and the wake hint:
 
 - `search_files` (read-only) and `edit_file` come from the SDK's `workspaceTools()` with its schemas, plus
   `workspace_key` and `timeout_ms`, filtered by the `files` permission. The server instructions describe them.
@@ -108,19 +148,19 @@ File tools and the wake hint (contracts §26):
   fire-and-forget; a suspended workspace starts resuming in the background, bounded like any wake by
   `SHARDFLUX_WAKE_TIMEOUT_MS` and the call's deadline), except `read_file`, `list_files` and `search_files`.
 - `read_file`, `list_files` and `search_files` of a suspended workspace whose disk a host still holds are answered
-  from that disk without resuming it (contracts §26.4), also as the first call after the suspend: the API now issues
+  from that disk without resuming it, also as the first call after the suspend: the API now issues
   tool tokens for suspended workspaces. Every other tool still resumes it. With an older API they resume it as before.
-- A workspace on a host that predates search and patches (contracts §26.7, while the fleet is upgraded):
+- A workspace without search and patches:
   `search_files` and `edit_file` return `conflict`, `reason: host_feature_unavailable` (`details.feature`
   `file_search` or `file_patch`), `retryable: false`, with a `hint` naming another way (`exec` with `grep`;
-  `read_file` then `write_file`). They work once the workspace runs on an upgraded host. `hostFeatureHint()` is
+  `read_file` then `write_file`). `hostFeatureHint()` is
   exported next to `modeHint()`.
 - New refusals come back as error results with their `details.reason`: `revision_mismatch` (with
   `current_revision`), `edit_not_found` / `edit_ambiguous` (with `index`), `host_capacity` (retryable). A read of a
   sleeping workspace its disk cannot answer (`offline_unavailable`, `offline_budget`) wakes it like any
   `workspace_not_running`; `offline_changed` (503) is retried.
 
-Version check (contracts §30.4; needs an API that serves `GET /v1/client-versions`):
+Version check (needs an API that serves `GET /v1/client-versions`):
 
 - Version check at startup: after the configuration is validated, the server asks `GET /v1/client-versions` (through
   its own fetch, the SDK's `checkClientVersion`: one request, 3 s timeout, never awaited by the protocol) whether
@@ -141,7 +181,7 @@ Version check (contracts §30.4; needs an API that serves `GET /v1/client-versio
   authenticates with a project API key, which the API refuses for account actions (403 `forbidden` on the account
   routes, 401 on the `/v1/auth` session routes); they need a person's session (`sfu_...`), which the CLI signs in.
 
-### send_feedback: feedback straight to the founder (needs an API with POST /v1/feedback)
+### send_feedback: feedback straight to the Shardflux team (needs an API with POST /v1/feedback)
 
 - New management tool `send_feedback` (`message`, `category`: bug, confusing, missing, idea, praise or other; optional
   `workspace`, `request_id`, `error_code`, `command`). It calls the SDK's `sendFeedback()` with `client:
@@ -149,8 +189,8 @@ Version check (contracts §30.4; needs an API that serves `GET /v1/client-versio
   `SHARDFLUX_AGENT_LABEL`); a pinned server fills `workspace` with its key. Result: `{id, received_at, duplicate,
   note}`. Always listed (any API key may send feedback).
 - The server instructions and the tool description ask the agent to call it actively while it works: the moment a
-  call fails unexpectedly, an error or doc is confusing, something is missing or slow, or it needed a workaround, and
-  when its user is frustrated about Shardflux or asked for something it could not do (paraphrased, without private
+  call fails unexpectedly, an error or doc is confusing, something is missing, or it needed a workaround, and
+  when its user asks for something new (paraphrased, without private
   data; the agent tells its user it sent feedback).
 - Failed calls carry a `feedback` field next to `error`, except the expected flow: `invalid_arguments`,
   `workspace_pinned`, `unauthenticated`, `validation_failed`, `timeout`, and refusals whose error names the next step
@@ -198,8 +238,7 @@ Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
 
 Needs `@shardflux/sdk` 0.6.2 (the workspace version).
 
-The API no longer lets a start (open, resume, fork) wait in `capacity_pending` forever: one that no host could admit
-15 minutes after it began fails with `capacity_unavailable` (retryable; nothing was started, a suspended workspace
+The API no longer lets a start (open, resume, fork) wait in `capacity_pending` forever: one still queued 15 minutes after it began fails with `capacity_unavailable` (retryable; nothing was started, a suspended workspace
 stays suspended).
 
 - Failed-operation errors (`code: operation_failed`) carry `retryable`, the operation error's own flag, and

package/README.md

@@ -14,8 +14,8 @@ with the scoped project API key you give it. Each tool call becomes one SDK requ
 
 Documentation: <https://docs.shardflux.dev/reference/mcp>.
 
-> **Early access.** Shardflux is in early access, and this server is below 1.0: tools and results
-> may still change in a minor release.
+> **Compatibility.** The API is versioned (`/v1`). Breaking changes ship only in minor releases and are marked
+> **Breaking** in the changelog.
 
 Requires Node.js 24 or later and a Shardflux project API key (`sfk_...`, from the Shardflux console).
 
@@ -174,7 +174,7 @@ environment `SHARDFLUX_API_KEY`.
 | `SHARDFLUX_WAKE_TIMEOUT_MS` | Longest wait per tool call for a workspace to wake or finish a transition, 1000-3600000 ms. Default 120000. It is clamped to `SHARDFLUX_MCP_TOOL_TIMEOUT_MS`, and each wake also ends 250 ms before the call's own deadline. |
 | `SHARDFLUX_AGENT_LABEL` | Attribution label of every tool token this server obtains. Default `mcp`. It appears as an agent session in `GET /v1/workspaces/{id}/agent-sessions`, the console and `shard ws sessions`. |
 | `SHARDFLUX_MCP_LOG_LEVEL` | `debug`, `info` (default), `warn` or `error`. Logs are JSON lines on **stderr**; stdout is the protocol. The key is never logged, and anything key-shaped is redacted. |
-| `SHARDFLUX_HTTP_KEEPALIVE=1` | Reuse HTTP connections. By default every request uses a fresh connection (`Connection: close`), because on some Node.js releases a request sent on a reused keep-alive connection can stall until the request timeout. |
+| `SHARDFLUX_HTTP_KEEPALIVE` | 0.6.0+: default private HTTP/1.1 pooling on Node 26; `0` forces close for diagnosis, `1` uses native pooling. |
 | `SHARDFLUX_NO_UPDATE_CHECK` | (0.4.0) `1`, `true`, `yes` or `on` turns off the startup version check (see "Updates"). |
 | `NO_UPDATE_NOTIFIER` | (0.4.0) The npm convention: any non-empty value also turns the check off. |
 
@@ -189,11 +189,9 @@ working directory: the directory your MCP client starts it in.
 
 ## Feedback: agents are asked to use `send_feedback` while they work
 
-**(0.4.0+)** The `send_feedback` tool sends a message straight to the Shardflux founder, who reads every one. The
+**(0.4.0+)** The `send_feedback` tool sends a message straight to the Shardflux team, who read every one. The
 server instructions and the tool description ask the agent to call it actively during its work, not once at the end:
-the moment a call fails unexpectedly, an error or doc is confusing, something is missing or slow, or it needed a
-workaround; when its user complains or is frustrated about Shardflux or the workflow around it (paraphrased, with what
-they were trying to do); and when its user asked for something Shardflux could not do, or made awkward. Short and
+the moment a call fails unexpectedly, an error or doc is confusing, something is missing, or it needed a workaround; when its user asks for a capability, an option or a smoother workflow (paraphrased, with what they were trying to do); and when its user has an idea for how Shardflux could fit their work better. Short and
 frequent beats polished, with the `request_id` and error code from the error. The agent tells its user it sent
 feedback, and leaves out private data about the user and secrets or code they did not mean to share (paraphrase, never
 transcripts). Failed calls carry a ready-made suggestion in a `feedback` field (see "Contract").
@@ -239,12 +237,11 @@ The management tools:
 | `workspace_status` | One workspace plus its five most recent operations. |
 | `workspace_suspend`, `workspace_resume` | Lifecycle operation. Returns at once unless `wait: true` (then once it finished, through the SDK's own `wait`). |
 | `workspace_suspend` with `after_seconds` | (0.4.1) Suspend when idle: the workspace is suspended once it has been idle for `after_seconds` (0-3600; 0 = as soon as it is idle, 0.5.1+), instead of now. The description tells the agent to use it when it finishes its work, so the workspace stops using RAM soon after. Its next tool call on the workspace cancels it; a running command or a keepalive postpones it. Returns `suspend_request` (`not_before`: the earliest suspend) and a `message`; `operation` when a suspend was already in progress. Not with `wait`. `workspace_status` shows a pending request as `workspace.suspend_request`. Not for file-first workspaces. |
-| `workspace_fork` | Fork into `new_key`. |
-| `operation_wait` | Keep waiting for an operation. |
+| `workspace_suspend` with `durable: true` | (0.6.0+) Returns once the suspend is in durable storage. A suspend returns as soon as the workspace is sealed on its host, typically in a few hundred ms; its operation's `durable` turns true when the copy lands in durable storage, typically within a second (`durability` shows its progress). |
+| `workspace_fork` | Fork into `new_key`. A fork of a running workspace carries `durable` and `durability` the same way (0.6.0+). |
+| `operation_wait` | Keep waiting for an operation. `durable: true` (0.6.0+): a suspend or fork, until its copy is in durable storage. |
 | `usage_summary` | The organization's usage summary for the current period: meters, allowances with their cap state, `allowance_exhausted` with `exhausted_reason`, and (0.4.1+, an API with opt-in overage) `spend_cap`: the overage state, cap, charges, lines per allowance and the date the cap is projected to be reached. |
-
-| `usage_summary` | The organization's usage summary for the current period. |
-| `send_feedback` | (0.4.0) Feedback straight to the Shardflux founder: `message`, `category`, and optional `workspace`, `request_id`, `error_code`, `command`. See [Feedback](#feedback-agents-are-asked-to-use-send_feedback-while-they-work). |
+| `send_feedback` | (0.4.0) Feedback straight to the Shardflux team: `message`, `category`, and optional `workspace`, `request_id`, `error_code`, `command`. See [Feedback](#feedback-agents-are-asked-to-use-send_feedback-while-they-work). |
 | `template_get` | (0.3.0) A template's versions with their settings (env, inputs, start commands, services, defaults); with `version`, that version's recipe in request form. |
 | `template_languages` | (0.3.0) The languages and versions a base (`<slug>@<version>`) offers `build.languages`. |
 | `template_build` | (0.3.0) Build a version of an organization template from a recipe v2: `recipe` (the document) or `file` (a template.yaml or .json path). File entries may name local `from` paths, uploaded first (folders as a tar). **Every local path must resolve inside the server's working directory**; others are refused before any request. Unpublished unless `publish: true`; `wait: true` follows the build within the call's deadline. |
@@ -259,24 +256,23 @@ The SDK's workspace tools come from `workspaceTools()`:
 - `browser_screenshot`, `browser_content`
 
 They are published with **the SDK's JSON Schemas verbatim**, plus `workspace_key` and, where the
-SDK schema has none, `timeout_ms`. They are filtered by the key's tool permissions (if the server
-cannot read them, for example because the API is unreachable, it lists every workspace tool and logs
-a warning). `exec`'s `cwd` is an absolute path (default `/home/user`): a relative one is an error result with
-`details.reason: invalid_cwd` whose message names the absolute path it likely means, and a command that could not
-start (a `cwd` that is not a directory, a program not on `PATH`) returns `exit_code: null` with `error: { code,
-message, reason: "exec_failed_to_start" }` naming the workspace's reason (0.4.1+). `browser_screenshot` returns an MCP image content block. `search_files` is annotated read-only; `edit_file` replaces
-exact text and, without an `expected_revision`, reads the file's revision first so a concurrent change fails the
+SDK schema has none, `timeout_ms`. They are filtered by the key's tool permissions when the server
+can read them; otherwise it lists every workspace tool. `exec`'s `cwd` is an absolute path (default
+`/home/user`): a relative one is an error result with `details.reason: invalid_cwd` whose message names the absolute
+path it likely means, and a command that could not start (a `cwd` that is not a directory, a program not on `PATH`)
+returns `exit_code: null` with `error: { code, message, reason: "exec_failed_to_start" }` naming the workspace's
+reason (0.4.1+). `browser_screenshot` returns an MCP image content block. `search_files` is annotated read-only;
+`edit_file` replaces exact text and, without an `expected_revision`, reads the file's revision first so a concurrent change fails the
 edit (`conflict`, `details.reason: revision_mismatch`) instead of being overwritten.
 
-Each workspace tool call first sends the wake hint (`POST /wake-hint`, without waiting for it): a workspace its host
-has parked starts restoring while the call is prepared, and a suspended one starts resuming. `read_file`,
-`list_files` and `search_files` send none (0.4.0+): a suspended workspace whose disk its host still holds is read,
+Each workspace tool call first sends the wake hint (`POST /wake-hint`, without waiting for it): a parked workspace
+starts restoring while the call is prepared, and a suspended one starts resuming. `read_file`,
+`list_files` and `search_files` send none (0.4.0+): a suspended workspace is read from its saved disk,
 listed and searched there without resuming it (the state at suspension).
 
-While the fleet is being upgraded a workspace may run on a host that predates `search_files` and `edit_file`: they
-fail with `conflict`, `reason: host_feature_unavailable` (`details.feature` `file_search` or `file_patch`),
-`retryable: false` and a `hint` naming another way (`exec` with `grep`; `read_file` then `write_file`). It lasts
-until the workspace runs on an upgraded host.
+If search or patches are not available for a workspace, `search_files` and `edit_file` fail with `conflict`,
+`reason: host_feature_unavailable` (`details.feature` `file_search` or `file_patch`), `retryable: false` and a `hint`
+naming the fallback (`exec` with `grep`; `read_file` then `write_file`).
 
 Deleting a workspace is deliberately not exposed to agents; use the
 [CLI](https://www.npmjs.com/package/@shardflux/cli) or the console.
@@ -295,13 +291,13 @@ the state of the template's start commands and services (`failed` names the step
 
 ### File-first workspaces (0.4.0)
 
-`workspace_open` with `mode: "file_first"` (or `SHARDFLUX_WORKSPACE_MODE=file_first`) opens a file-first workspace
-(contracts §29): a versioned file tree under /home/user with no VM between calls. It is ready at once and never
+`workspace_open` with `mode: "file_first"` (or `SHARDFLUX_WORKSPACE_MODE=file_first`) opens a file-first workspace:
+a versioned file tree under /home/user with no VM between calls. It is ready at once and never
 suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_revision`.
 
 - `exec` runs each command as an execution: a fresh VM on the workspace's files. Only files under /home/user persist
   between calls. The result adds `execution_id`, `state`, `tree_revision` and `changed` (the paths the command added,
-  modified or deleted, up to 200, with `changed_truncated`). An execution cannot be canceled: when the call's
+  modified or deleted, up to 200, with `changed_truncated`). An execution runs to completion: when the call's
   deadline passes first, the error carries its `execution_id` and the execution continues server side.
 - The files tools work as on a processful workspace. Each change publishes the next tree revision.
 - The process, terminal, git and browser tools and `workspace_suspend`, `workspace_resume`, `workspace_fork` and
@@ -311,17 +307,17 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
   `notifications/tools/list_changed`. An unpinned server lists every tool; calling one the named workspace's mode
   lacks returns an error with `reason: "not_supported_for_mode"` and a `hint`, before any request.
 - Errors of file-first workspaces carry `reason` and a `hint`: `not_supported_for_mode`, `mode_mismatch` (a key's
-  mode never changes), `mode_not_available` (the deployment does not offer file-first workspaces), `layout_unsupported`
+  mode never changes), `mode_not_available` (the account does not have file-first workspaces), `layout_unsupported`
   (a legacy template), `tree_revision_mismatch` (with `current_tree_revision`), `outside_tree_root`,
-  `execution_in_progress` (another execution holds the workspace), `execution_id_reused` and `no_execution_host` (no
-  host had room, also after the SDK's retries with the same execution id; nothing ran).
+  `execution_in_progress` (another execution holds the workspace), `execution_id_reused` and `no_execution_host`
+  (the execution cannot be placed right now; retried with the same id; nothing ran).
 
 ```json
 {
   "mcpServers": {
     "shardflux": {
-      "command": "node",
-      "args": ["/path/to/packages/mcp/src/bin.ts"],
+      "command": "npx",
+      "args": ["-y", "@shardflux/mcp"],
       "env": { "SHARDFLUX_API_KEY": "sfk_...", "SHARDFLUX_WORKSPACE_KEY": "me/agent-files", "SHARDFLUX_TEMPLATE": "python-node-browser", "SHARDFLUX_WORKSPACE_MODE": "file_first" }
     }
   }
@@ -343,25 +339,23 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
     `allowance_used` (upgrade, or turn on overage), `overage_paused` (a plan payment is past due) or
     `spend_cap_reached` (raise the spend cap or upgrade), and `details.spend_cap`. An owner or billing member acts
     on it in the console; retrying does not help.
-
   - **(0.4.0+)** A failed call has a `feedback` field next to `error`: a one-sentence suggestion to call
     `send_feedback` with category `bug`, the `request_id` and the error code. Not for `invalid_arguments`,
     `workspace_pinned` or `unauthenticated`. A failed `send_feedback` carries a `hint` instead (when to retry, or the
     email address).
-- **Starts wait for capacity for at most 15 minutes (0.2.1+).** An open, resume or fork that no host can admit waits
-  in `capacity_pending`; a wait that ends first returns `code: timeout`, and its message names when the start gives
-  up. A start still pending then fails: `operation_failed`, `details.error_code: capacity_unavailable`,
-  `retryable: true`, and a message telling the agent that nothing was started and it may retry later. The server
-  never retries it itself. The server instructions say the same.
+- **Start deadlines (0.2.1+).** A queued open, resume or fork (`capacity_pending`) has a deadline 15 minutes after
+  it was created; a wait that ends first returns `code: timeout`, and its message names the deadline. A start still
+  pending then fails: `operation_failed`, `details.error_code: capacity_unavailable`, `retryable: true`, and a
+  message telling the agent that nothing was started and it can retry. The server instructions say the same.
 - **Timing (0.2.0+).** A call that opens a workspace or waits says where the time went, from the SDK's lifecycle
   timing, compact for model context:
 
   ```json
   "timing": {
-    "action": "open", "outcome": "succeeded", "operation_id": "01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33", "total_ms": 34180,
-    "phases": ["request(held) 20010 ms", "capacity_pending(no_ready_host) 13520 ms", "running 590 ms", "view 42 ms", "token 61 ms"],
-    "server": { "queued_ms": 33400, "run_ms": 620, "total_ms": 34020, "start_path": "warm" },
-    "outside_server_ms": 160, "retries": 0
+    "action": "resume", "outcome": "succeeded", "operation_id": "01a0ead6-bd61-737a-ae88-66e2d01a6e25", "total_ms": 413,
+    "phases": ["request 218 ms", "queued 195 ms"],
+    "server": { "queued_ms": 51, "run_ms": 290, "total_ms": 341, "resume_path": "local_cache" },
+    "outside_server_ms": 72, "retries": 0
   }
   ```
 
@@ -369,7 +363,7 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
     `workspace_fork` carry it with `wait: true`. Workspace tools carry it when they had to wake the workspace
     (`action: "wake"`). Other results do not.
   - Phases are in order, as `phase(reason) ms`. `request(held)` means the API held the open until the workspace was
-    ready. `capacity_pending(no_ready_host)` is time spent waiting for a host.
+    ready. `capacity_pending(no_ready_host)` is time queued to start.
   - `server` is the operation's own queued, run and total time, plus the start or resume path the cell reported.
     A resume also has `memory_restored` (0.5.0+) when the API reports it, and `cold_boot_reason` when it is false.
   - `outside_server_ms` is everything else: network, polling, reading the workspace, the tool token.
@@ -378,7 +372,7 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
     with the first tool token, which the next tool call reuses.
 - **Deadlines.** Every call has one: `timeout_ms`, clamped to the ceiling.
   - Waits time out just before the deadline with `code: timeout` and the `operation_id`; the
-    operation continues server side (a start waiting for capacity for at most 15 minutes).
+    operation continues server side (a queued start until its 15-minute deadline).
   - Any request still in flight at the deadline is aborted.
   - `exec`'s command timeout is capped at the deadline minus 2 s, so its output comes back.
 - **Cancellation.** MCP `notifications/cancelled` aborts the SDK work behind the call: waits,
@@ -386,7 +380,7 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
   the server stays up. The lifecycle operation itself is not canceled.
 - **Workspace tools wake suspended workspaces, but do not open new ones.** A workspace that was
   never opened is `not_found`: call `workspace_open` first. Reads (`read_file`, `list_files`,
-  `search_files`) of a suspended workspace whose disk a host still holds are answered from that disk
+  `search_files`) of a suspended workspace are answered from its saved disk
   without waking it.
   - A suspended workspace is resumed (or the resume or open already running is joined), and the
     call runs once it is running. A call made during a suspend or resume waits for it to finish.
@@ -399,10 +393,10 @@ suspended. Workspace results carry `mode` and, for file-first workspaces, `tree_
     suspended).
   - With `SHARDFLUX_WAKE=off` the API's refusal comes back instead (`conflict`,
     `details.reason: workspace_not_running`, or `workspace_not_running` from the cell gateway).
-  - **A resume can restart processes (0.5.0+).** A resume normally restores memory and running processes. When the
-    platform's VM runtime changed after the suspend and no host can restore that memory snapshot, the resume boots
-    the workspace's saved disk instead (a cold boot), also when a workspace tool wakes it. The call still runs, and
-    files are as of the suspend, but every process was restarted. The result (or the error result) then carries
+  - **Detecting a cold resume (0.5.0+).** A resume restores memory and running processes. After a platform runtime
+    update, a resume can boot from the saved disk instead of restoring memory (a cold boot), also when a workspace
+    tool wakes it; check `memory_restored`. The call still runs with the files as of the suspend, and processes start
+    fresh. The result (or the error result) then carries
     `timing.server.resume_path: "cold_boot"`, `memory_restored: false`, `cold_boot_reason` (e.g. `runtime_changed`)
     and a `notice` the agent reads: to start its dev servers, databases, watchers and background jobs again. The
     server instructions and the `workspace_resume` description say so too.
@@ -423,3 +417,10 @@ await server.connect(transport); // any @modelcontextprotocol/sdk transport
 ## License
 
 Apache-2.0
+
+
+## Integration controls (0.6.0+)
+
+`workspace_open` accepts `labels` and `idle_policy`; `workspace_list` accepts exact label filters. `workspace_set_labels` replaces all labels. `workspace_idle` reads activity without waking, `workspace_keepalive` declares ongoing work, and `workspace_set_idle_policy` accepts adaptive, never, fixed:<seconds>, or default.
+`workspace_exec_start` starts a tracked background command with optional `stdin_open`; `workspace_exec_input` writes data at an acknowledged byte offset and can send EOF with `close`. Both require exec permission and processful workspaces. Frames are bounded to 64 KiB; use the returned offset after partial acknowledgements. The host and guest must advertise pipe-input support.
+`workspace_resume` recovers failed IDs without replacing their disks. A completed delete frees the key for a new workspace ID. Protocol errors include their source; a bare 404 is not a workspace tombstone.

package/dist/errors.d.ts

@@ -18,22 +18,22 @@ export interface ToolErrorInfo {
     execution_id?: string;
     /** tree_revision_mismatch: the revision the workspace's file tree is at (0.4.0). */
     current_tree_revision?: number;
-    source?: 'api' | 'cell';
+    source?: 'api' | 'cell' | 'unknown';
     details?: Record<string, unknown>;
     issues?: string[];
     last_state?: string;
-    /** What to do instead (0.4.0): refusals that concern a workspace's mode (contracts §29) or a host that predates a tool (§26.7). */
+    /** What to do instead (0.4.0): refusals that concern a workspace's mode or a tool that is not available for the workspace. */
     hint?: string;
 }
 export declare function redact(text: string, key?: string): string;
 /**
- * What the model can do about a refusal that concerns a workspace's mode (contracts §29.7, §29.8), from its
+ * What the model can do about a refusal that concerns a workspace's mode, from its
  * details.reason and details; undefined for every other refusal.
  */
 export declare function modeHint(reason: string | undefined, details?: Record<string, unknown>): string | undefined;
 /**
- * 409 conflict host_feature_unavailable (contracts §26.7; 0.4.0): the workspace runs on a host that predates the tool,
- * until it runs on an upgraded host (minutes to hours). Not retryable, so the hint names another way to do it now.
+ * 409 conflict host_feature_unavailable (0.4.0): the tool is not available for this workspace. Not retryable, so the
+ * hint names the fallback that works now.
  */
 export declare function hostFeatureHint(reason: string | undefined, details?: Record<string, unknown>): string | undefined;
 export interface DescribeContext {

package/dist/errors.js

@@ -3,11 +3,11 @@
  * content is `{ "error": { code, message, ... } }` with the API's closed error
  * code, never as protocol failures, so the calling model can react to them.
  * API and cell refusals add `reason` (their details.reason) and, for refusals
- * that concern a workspace's mode (file-first workspaces, contracts §29) or a
- * host that predates a tool (host_feature_unavailable, contracts §26.7), a
+ * that concern a workspace's mode (file-first workspaces) or a
+ * tool that is not available for the workspace (host_feature_unavailable), a
  * `hint` saying what to do instead.
  */
-import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateUploadError, ToolArgumentError, TreeRevisionMismatchError } from '@shardflux/sdk';
+import { DurabilityLostError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateUploadError, ToolArgumentError, TreeRevisionMismatchError } from '@shardflux/sdk';
 /** A refusal decided by this server (argument/pinning problems, unknown workspace key). */
 export class ToolError extends Error {
     name = 'ToolError';
@@ -31,7 +31,7 @@ const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
 /** The tools a file-first workspace has, for hints. */
 const FILE_FIRST_TOOLS_TEXT = 'Run commands with exec and use read_file, write_file, list_files, search_files and edit_file for files; only files under /home/user persist between exec calls.';
 /**
- * What the model can do about a refusal that concerns a workspace's mode (contracts §29.7, §29.8), from its
+ * What the model can do about a refusal that concerns a workspace's mode, from its
  * details.reason and details; undefined for every other refusal.
  */
 export function modeHint(reason, details = {}) {
@@ -52,7 +52,7 @@ export function modeHint(reason, details = {}) {
                 : "A workspace's mode never changes: open this key with the mode it was created with, or use another key.";
         }
         case 'mode_not_available':
-            return 'This deployment does not offer file-first workspaces yet: open the workspace with mode "processful" (or without mode).';
+            return 'This deployment does not offer file-first workspaces: open the workspace with mode "processful" (or without mode).';
         case 'layout_unsupported':
             return mode === 'file_first'
                 ? 'File-first workspaces run on layered template versions and this one is not: pick another template (template_get lists its versions and disk_layouts) or open with mode "processful".'
@@ -66,26 +66,26 @@ export function modeHint(reason, details = {}) {
         case 'execution_id_reused':
             return 'That execution id was already used for a different command; call exec again (each call uses a new execution id).';
         case 'no_execution_host':
-            return 'No host has room to run the command now and nothing ran; retry in a few seconds.';
+            return 'The execution cannot be placed right now and nothing ran; retry in a few seconds.';
         default:
             return undefined;
     }
 }
 /**
- * 409 conflict host_feature_unavailable (contracts §26.7; 0.4.0): the workspace runs on a host that predates the tool,
- * until it runs on an upgraded host (minutes to hours). Not retryable, so the hint names another way to do it now.
+ * 409 conflict host_feature_unavailable (0.4.0): the tool is not available for this workspace. Not retryable, so the
+ * hint names the fallback that works now.
  */
 export function hostFeatureHint(reason, details = {}) {
     if (reason !== 'host_feature_unavailable')
         return undefined;
-    const later = 'It will work once the workspace runs on an upgraded host; retrying now does not help.';
+    const retry = 'Retrying does not help.';
     switch (details.feature) {
         case 'file_search':
-            return `This workspace's host does not support search_files yet. Search with exec instead, e.g. grep -rn -- PATTERN PATH (add -i to ignore case, -E for a regular expression). ${later}`;
+            return `search_files is not available for this workspace. Search with exec instead, e.g. grep -rn -- PATTERN PATH (add -i to ignore case, -E for a regular expression). ${retry}`;
         case 'file_patch':
-            return `This workspace's host does not support edit_file yet. Use read_file, change the text, then write_file with the whole new content. ${later}`;
+            return `edit_file is not available for this workspace. Use read_file, change the text, then write_file with the whole new content. ${retry}`;
         default:
-            return `This workspace's host does not support this tool yet. ${later}`;
+            return `This tool is not available for this workspace. ${retry}`;
     }
 }
 export function describeToolError(err, context = {}) {
@@ -101,7 +101,7 @@ export function describeToolError(err, context = {}) {
             retryable: err.retryable,
             source: err.source,
             ...(err.operationId ? { operation_id: err.operationId } : {}),
-            // No execution_id: a refusal answers before anything ran, and the execution id stays unused (contracts §29.8).
+            // No execution_id: a refusal answers before anything ran, and the execution id stays unused.
             ...(err instanceof TreeRevisionMismatchError && err.currentTreeRevision !== null ? { current_tree_revision: err.currentTreeRevision } : {}),
             ...(err.details ? { details: err.details } : {}),
             ...(hint ? { hint } : {}),
@@ -112,21 +112,32 @@ export function describeToolError(err, context = {}) {
     if (err instanceof ToolError)
         return { code: err.code, message: err.message, ...(err.details ? { details: err.details } : {}) };
     if (err instanceof OperationTimeoutError) {
+        if (err.durable) {
+            return { code: 'timeout', message: `${err.message} Call operation_wait with this operation_id and durable: true to keep waiting.`, operation_id: err.operationId, last_state: err.lastState, retryable: true, details: { durable: false, state: 'pending' } };
+        }
         return { code: 'timeout', message: `${err.message} Call operation_wait with this operation_id to keep waiting.`, operation_id: err.operationId, last_state: err.lastState, retryable: true };
     }
+    // 0.6.0: the suspend (or fork) succeeded; its durable copy could not be made (durability.state lost).
+    if (err instanceof DurabilityLostError) {
+        return { code: 'durability_lost', message: err.message, operation_id: err.operationId, retryable: false, details: { state: 'lost', ...(err.durability.reason ? { reason: err.durability.reason } : {}), ...(err.durability.checkpointId ? { checkpoint_id: err.durability.checkpointId } : {}) } };
+    }
     if (err instanceof OperationFailedError) {
-        // retryable: the operation error's own flag. capacity_unavailable (no host could admit the start before its
-        // deadline) is retryable: nothing was started, so the agent may try again later.
+        // retryable: the operation error's own flag. capacity_unavailable (the start passed its deadline) is retryable:
+        // nothing was started, so the agent may send it again.
         const opDetails = err.operation.error?.details;
         const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
         const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
-        const hint = err.errorCode === 'capacity_unavailable' ? '. No host could admit it before its deadline and nothing was started; you may retry later.' : '';
+        const hint = err.errorCode === 'capacity_unavailable'
+            ? '. The start passed its deadline and nothing was started; send it again.'
+            : err.workspaceActive
+                ? '. The workspace was in use, so the suspend-when-idle was canceled; nothing changed and it keeps running.'
+                : '';
         return { code: 'operation_failed', message: `${err.message}${hint}`, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}) };
     }
     if (named(err, 'TimeoutError')) {
-        // A file-first execution cannot be canceled: it runs to its end server side and then publishes what it changed.
+        // A file-first execution runs to completion server side and then publishes what it changed.
         const continues = context.executionId
-            ? `; execution ${context.executionId} continues server side (a file-first execution cannot be canceled): the files it changes are published when it ends, and the next exec or file change on this workspace waits for it`
+            ? `; execution ${context.executionId} continues server side (a file-first execution runs to completion): the files it changes are published when it ends, and the next exec or file change on this workspace waits for it`
             : context.operationId
                 ? '; the operation continues server side (use operation_wait)'
                 : '';
@@ -141,7 +152,7 @@ export function describeToolError(err, context = {}) {
     if (err instanceof TemplateUploadError)
         return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
     if (err instanceof ShardfluxProtocolError)
-        return { code: 'protocol_error', message: err.message, status: err.status, ...(context.executionId ? { execution_id: context.executionId } : {}) };
+        return { code: 'protocol_error', message: err.message, status: err.status, source: err.source, ...(context.executionId ? { execution_id: context.executionId } : {}) };
     if (err instanceof TypeError && err.message === 'fetch failed') {
         const cause = err.cause;
         return {

package/dist/http.d.ts

@@ -1,13 +1,2 @@
-/**
- * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
- * every request (API and cell gateway).
- *
- * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
- * sent on a reused keep-alive connection until an unrelated timer fires (up to
- * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
- * with bare fetch against both node:http and Fastify servers; Node 22 (undici
- * 6.28) and `Connection: close` do not stall. A fresh connection per request
- * costs one TCP/TLS handshake, which is negligible for these call rates.
- * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
- */
+/** Share the SDK's pooled transport. A caller-supplied fetch stays under the caller's control. */
 export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch): typeof fetch;

package/dist/http.js

@@ -1,21 +1,5 @@
-/**
- * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
- * every request (API and cell gateway).
- *
- * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
- * sent on a reused keep-alive connection until an unrelated timer fires (up to
- * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
- * with bare fetch against both node:http and Fastify servers; Node 22 (undici
- * 6.28) and `Connection: close` do not stall. A fresh connection per request
- * costs one TCP/TLS handshake, which is negligible for these call rates.
- * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
- */
-export function makeFetch(env, base = fetch) {
-    if (env.SHARDFLUX_HTTP_KEEPALIVE === '1')
-        return base;
-    return (input, init) => {
-        const headers = new Headers(init?.headers);
-        headers.set('connection', 'close');
-        return base(input, { ...init, headers });
-    };
+import { defaultFetch } from '@shardflux/sdk';
+/** Share the SDK's pooled transport. A caller-supplied fetch stays under the caller's control. */
+export function makeFetch(env, base = defaultFetch(env)) {
+    return base;
 }

package/dist/server.d.ts

@@ -3,8 +3,8 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { ClientVersionStatus, JsonSchema, LifecycleTiming, Operation, TemplateBuild, TemplateDetail, TemplateOwner, ToolName, WorkspaceMode, WorkspaceTool, WorkspaceView } from '@shardflux/sdk';
 import type { McpConfig } from './config.js';
 import type { ToolErrorInfo } from './errors.js';
-export declare const MCP_SERVER_VERSION = "0.5.1";
-/** The package this server is distributed as: its entry in GET /v1/client-versions (contracts §30.4). */
+export declare const MCP_SERVER_VERSION = "0.6.0";
+/** The package this server is distributed as: its entry in GET /v1/client-versions. */
 export declare const MCP_PACKAGE = "@shardflux/mcp";
 export declare const ALL_TOOL_PERMISSIONS: readonly ToolName[];
 export type ObjectSchema = JsonSchema & {
@@ -36,6 +36,33 @@ export declare function summarizeWorkspace(v: WorkspaceView): {
         version: number;
     };
     active_operation: {
+        lost_suspend?: ({
+            checkpoint_id: string;
+            generation_id?: string;
+            reason?: string;
+            suspended_at?: string;
+            restored_checkpoint_id?: string;
+            state_as_of?: string;
+        } & {
+            [key: string]: unknown;
+        }) | undefined;
+        durability?: ({
+            state: "pending" | "durable" | "lost";
+            checkpoint_id?: string;
+            generation_id?: string;
+            local_commit_at?: string;
+            durable_by?: string;
+            durable_at?: string;
+            local_commit_to_durable_ms?: number;
+            overdue_at?: string;
+            reason?: string;
+            code?: string;
+            recovery_point_checkpoint_id?: string | null;
+        } & {
+            [key: string]: unknown;
+        }) | undefined;
+        suspend_path?: string | undefined;
+        durable?: boolean | undefined;
         error?: {
             [key: string]: unknown;
         } | undefined;
@@ -62,6 +89,9 @@ export declare function summarizeWorkspace(v: WorkspaceView): {
     purpose: "standard" | "template_draft" | "template_test";
     disk_layout: "legacy" | "layered";
     idle_timeout_seconds: number | null;
+    labels: {
+        [key: string]: string;
+    };
     ended_reason: "closed" | "idle_timeout" | "draft_discarded" | null;
     /** Start commands and services of the template version; null when it has none. */
     startup: {
@@ -171,6 +201,33 @@ export declare function summarizeTemplate(t: TemplateDetail): {
     versions_truncated: boolean;
 };
 export declare function summarizeOperation(o: Operation): {
+    lost_suspend?: ({
+        checkpoint_id: string;
+        generation_id?: string;
+        reason?: string;
+        suspended_at?: string;
+        restored_checkpoint_id?: string;
+        state_as_of?: string;
+    } & {
+        [key: string]: unknown;
+    }) | undefined;
+    durability?: ({
+        state: "pending" | "durable" | "lost";
+        checkpoint_id?: string;
+        generation_id?: string;
+        local_commit_at?: string;
+        durable_by?: string;
+        durable_at?: string;
+        local_commit_to_durable_ms?: number;
+        overdue_at?: string;
+        reason?: string;
+        code?: string;
+        recovery_point_checkpoint_id?: string | null;
+    } & {
+        [key: string]: unknown;
+    }) | undefined;
+    suspend_path?: string | undefined;
+    durable?: boolean | undefined;
     error?: {
         [key: string]: unknown;
     } | undefined;
@@ -185,13 +242,15 @@ export declare function summarizeOperation(o: Operation): {
 /**
  * The SDK's LifecycleTiming, compact enough for model context: where an open, a wait or a wake spent its time. Phases
  * are `phase(reason) ms` in order (`request(held)`: the server held the open; `capacity_pending(no_ready_host)`:
- * waiting for a host); `server` is the operation's own queued/run/total time; `outside_server_ms` is the rest
+ * queued); `server` is the operation's own queued/run/total time; `outside_server_ms` is the rest
  * (network, polling, view and token).
  */
 export declare function compactTiming(t: LifecycleTiming): {
     total_ms: number;
     phases: string[];
     server: {
+        durability_state?: "pending" | "durable" | "lost" | undefined;
+        durable?: boolean | undefined;
         cold_boot_reason?: string | undefined;
         memory_restored?: boolean | undefined;
         resume_path?: string | undefined;
@@ -213,6 +272,13 @@ export declare function compactTiming(t: LifecycleTiming): {
  * and background jobs it started are gone. Undefined for any other timing, including one whose memory_restored is unknown.
  */
 export declare function processRestartNotice(t: LifecycleTiming): string | undefined;
+/**
+ * (0.6.0) The `notice` of a result whose resume restored an earlier checkpoint because the workspace's latest suspend
+ * could not be kept (`lost_suspend`): the files and processes are as of that checkpoint.
+ */
+export declare function lostSuspendNotice(t: LifecycleTiming): string | undefined;
+/** The notices of a timing (cold boot, lost suspend), joined; undefined when there are none. */
+export declare function timingNotice(t: LifecycleTiming): string | undefined;
 export declare function okResult(value: unknown): CallToolResult;
 /**
  * `timing` (optional): where the failed open/wait/wake spent its time, next to `error`. `extra` (0.4.0): more sibling
@@ -239,7 +305,7 @@ export interface ServerOptions {
     versionCheck?: boolean;
 }
 /**
- * The startup version check (0.4.0; contracts §30.4): one GET <api>/v1/client-versions through the server's fetch
+ * The startup version check (0.4.0): one GET <api>/v1/client-versions through the server's fetch
  * (the SDK's checkClientVersion: 3 s timeout, never throws) for @shardflux/mcp at MCP_SERVER_VERSION. Outdated or
  * unsupported: one `warn` line whose message is the notice (`@shardflux/mcp 0.4.0 is outdated: 0.5.0 is available.
  * Update: <upgrade command>`) plus the status fields. Anything else (current; unknown: not listed, `latest` null while

package/dist/server.js

@@ -8,7 +8,7 @@
  *   - templates (0.3.0): template_get (versions, settings, a version's recipe), template_languages and
  *     template_build (a recipe v2 object or a template.yaml path inside the
  *     server's working directory; local `from` paths are uploaded by the SDK);
- *   - send_feedback (0.4.0): feedback straight to the Shardflux founder; the instructions, its description and
+ *   - send_feedback (0.4.0): feedback straight to the Shardflux team; the instructions, its description and
  *     the `feedback` field of error results ask agents to use it while they work;
  *   - the SDK's workspace tools (`workspaceTools()`: exec, files, processes,
  *     terminal, git, browser), published with the SDK's own JSON Schemas plus
@@ -21,14 +21,14 @@
  * call first sends the wake hint (the SDK tool runner's `workspace.hint()`,
  * fire-and-forget) so a parked workspace restores while the call is prepared,
  * except read_file, list_files and search_files, which a sleeping workspace
- * answers from its disk without waking (contracts §26.4). Each call has a deadline
+ * answers from its disk without waking. Each call has a deadline
  * (`timeout_ms`, clamped to SHARDFLUX_MCP_TOOL_TIMEOUT_MS) and MCP cancellation
  * (notifications/cancelled -> `extra.signal`) aborts the underlying SDK
  * request or wait. Failures come back as `isError` tool results carrying the
  * API error code. stdout is the protocol; logs go to stderr. Opens, waits and
  * wakes carry the SDK's lifecycle timing, compacted (`compactTiming`).
  *
- * File-first workspaces (0.4.0; contracts §29: `workspace_open` `mode:
+ * File-first workspaces (0.4.0: `workspace_open` `mode:
  * "file_first"`) have files and executions only. A pinned server lists the
  * tools of its workspace's mode (the key's mode once it resolves, else
  * SHARDFLUX_WORKSPACE_MODE, else processful) and sends
@@ -53,8 +53,8 @@ import { parse as parseYaml } from 'yaml';
 import { DEFAULT_WAKE_TIMEOUT_MS } from "./config.js";
 import { ToolError, describeToolError, redact } from "./errors.js";
 import { makeFetch } from "./http.js";
-export const MCP_SERVER_VERSION = '0.5.1';
-/** The package this server is distributed as: its entry in GET /v1/client-versions (contracts §30.4). */
+export const MCP_SERVER_VERSION = '0.6.0';
+/** The package this server is distributed as: its entry in GET /v1/client-versions. */
 export const MCP_PACKAGE = '@shardflux/mcp';
 const USER_AGENT = `shardflux-mcp/${MCP_SERVER_VERSION} shardflux-sdk-ts/${SDK_VERSION}`;
 export const ALL_TOOL_PERMISSIONS = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
@@ -75,7 +75,7 @@ export function sdkToolDefinitions(tools = ALL_TOOL_PERMISSIONS, mode = 'process
     return workspaceTools(noWorkspace, { tools: [...tools], mode });
 }
 /** Management tools that need a workspace VM or an operation: not listed for a pinned file-first workspace. */
-const VM_ONLY_MANAGEMENT = new Set(['workspace_suspend', 'workspace_resume', 'workspace_fork', 'operation_wait']);
+const VM_ONLY_MANAGEMENT = new Set(['workspace_suspend', 'workspace_resume', 'workspace_fork', 'operation_wait', 'workspace_idle', 'workspace_keepalive', 'workspace_set_idle_policy', 'workspace_exec_start', 'workspace_exec_input']);
 /** What to use instead of a workspace tool a file-first workspace does not have, by the tool's permission. */
 const FILE_FIRST_INSTEAD = {
     process: 'Nothing runs between exec calls: run the program, and whatever needs it, within one exec command.',
@@ -132,6 +132,7 @@ export function summarizeWorkspace(v) {
         purpose: v.purpose,
         disk_layout: v.disk_layout,
         idle_timeout_seconds: v.idle_timeout_seconds,
+        labels: v.labels,
         ended_reason: v.ended_reason,
         /** Start commands and services of the template version; null when it has none. */
         startup: v.startup ?? null,
@@ -194,6 +195,11 @@ export function summarizeOperation(o) {
         created_at: o.created_at,
         completed_at: o.completed_at ?? null,
         ...(o.error ? { error: o.error } : {}),
+        // 0.6.0: suspend and fork say whether their copy is in durable storage; a resume names a suspend it could not restore.
+        ...(typeof o.result?.durable === 'boolean' ? { durable: o.result.durable } : {}),
+        ...(o.result?.suspend_path ? { suspend_path: o.result.suspend_path } : {}),
+        ...(o.result?.durability ? { durability: o.result.durability } : {}),
+        ...(o.result?.lost_suspend ? { lost_suspend: o.result.lost_suspend } : {}),
     };
 }
 function isObject(v) {
@@ -202,7 +208,7 @@ function isObject(v) {
 /**
  * The SDK's LifecycleTiming, compact enough for model context: where an open, a wait or a wake spent its time. Phases
  * are `phase(reason) ms` in order (`request(held)`: the server held the open; `capacity_pending(no_ready_host)`:
- * waiting for a host); `server` is the operation's own queued/run/total time; `outside_server_ms` is the rest
+ * queued); `server` is the operation's own queued/run/total time; `outside_server_ms` is the rest
  * (network, polling, view and token).
  */
 export function compactTiming(t) {
@@ -225,6 +231,8 @@ export function compactTiming(t) {
                 // 0.5.0: false when the resume booted the saved disk (processes restarted); absent when the API did not say.
                 ...(typeof s.memoryRestored === 'boolean' ? { memory_restored: s.memoryRestored } : {}),
                 ...(s.coldBootReason ? { cold_boot_reason: s.coldBootReason } : {}),
+                ...(typeof s.durable === 'boolean' ? { durable: s.durable } : {}),
+                ...(s.durability ? { durability_state: s.durability.state } : {}),
             }
             : null,
         outside_server_ms: ms(t.outsideServerMs),
@@ -248,6 +256,23 @@ export function processRestartNotice(t) {
     return (`The workspace was resumed from its saved disk, not from memory${why}. Its files are as they were when it was suspended, ` +
         'but every process was restarted, as after a reboot: start again any dev server, database, watcher or background job you had running, and open new terminals.');
 }
+/**
+ * (0.6.0) The `notice` of a result whose resume restored an earlier checkpoint because the workspace's latest suspend
+ * could not be kept (`lost_suspend`): the files and processes are as of that checkpoint.
+ */
+export function lostSuspendNotice(t) {
+    const l = t.server?.lostSuspend;
+    if (!l)
+        return undefined;
+    return (`The workspace was resumed from its checkpoint${l.stateAsOf ? ` of ${l.stateAsOf}` : ''} (${l.restoredCheckpointId ?? 'the previous one'}); ` +
+        `its suspend${l.suspendedAt ? ` at ${l.suspendedAt}` : ''} was not kept${l.reason ? ` (${l.reason})` : ''}. ` +
+        'Work done between those times is not in the workspace: check the files you changed and run again what you need.');
+}
+/** The notices of a timing (cold boot, lost suspend), joined; undefined when there are none. */
+export function timingNotice(t) {
+    const parts = [processRestartNotice(t), lostSuspendNotice(t)].filter((x) => x !== undefined);
+    return parts.length ? parts.join(' ') : undefined;
+}
 export function okResult(value) {
     if (isObject(value) && value.mime_type === 'image/png' && typeof value.data_base64 === 'string') {
         const { data_base64: data, ...meta } = value;
@@ -268,7 +293,7 @@ const FEEDBACK_EMAIL = 'shardflux@heliosone.fi';
  * When to use send_feedback, for the agent: the same words as `shard feedback --help`, in the server instructions and
  * the tool description. It has to make an agent actually call it while it works.
  */
-const FEEDBACK_USE = 'Call it actively while you work, not once at the end. Send a short note the moment: something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround; your user complains or is frustrated about Shardflux or the workflow around it (slowness, cost or limits, confusing setup, a missing feature, a workaround): paraphrase it, with what they were trying to do; your user asked for something Shardflux could not do, or made awkward. Short and frequent beats polished; include the request_id and error code (failed calls carry a ready-made "feedback" field). No need to ask first, but tell your user you sent it. Leave out private data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts.';
+const FEEDBACK_USE = 'Call it actively while you work, not once at the end. Send a short note the moment: something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround; your user asks for a capability, an option or a smoother workflow: paraphrase it, with what they were trying to do; your user has an idea for how Shardflux could fit their work better. Short and frequent beats polished; include the request_id and error code (failed calls carry a ready-made "feedback" field). No need to ask first, but tell your user you sent it. Leave out private data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts.';
 /**
  * No send_feedback suggestion for the expected flow: argument, configuration or credential problems of the call itself,
  * a wait that gave up while the work continues, and refusals whose error names the exact next step (the same list as
@@ -302,18 +327,18 @@ const INSTRUCTIONS = [
     'Call workspace_open first (it creates the workspace on first use and reconnects afterwards, never resetting it), then use exec, read_file, write_file and the other workspace tools with the same workspace_key.',
     'Lifecycle calls return operations; operation_wait keeps waiting. Workspace tools resume a suspended workspace on use (read_file, list_files and search_files read its disk without resuming it when they can); if that takes too long the error (code timeout) names the operation to pass to operation_wait. Errors are tool results with error.code from the Shardflux API.',
     'When you finish your work on a workspace, call workspace_suspend with after_seconds (e.g. 60): it is suspended once idle that long, so it stops using RAM; your next tool call on it cancels that.',
-    'A start (open, resume, fork) that no host can admit waits for capacity for at most 15 minutes, then fails with code operation_failed, details.error_code capacity_unavailable and retryable true: nothing was started; retry later if you still need it. retryable false means retrying will not help.',
+    'A queued start (open, resume, fork) has a deadline 15 minutes after it was created; past it, it fails with code operation_failed, details.error_code capacity_unavailable and retryable true. Nothing was started, so send it again. retryable false means retrying will not help.',
     'Opens, waits and wakes add timing (phases, server queued/run time) saying where the time went.',
     'A resume (also the automatic one when a tool call finds the workspace suspended) normally restores memory and running processes. If a result carries notice and timing.server.memory_restored false (resume_path cold_boot), the workspace booted from its saved disk instead: files are kept, but every process was restarted, so start your dev servers and background jobs again.',
     'Templates: template_get shows a template’s versions and settings (the inputs workspace_open takes); template_languages lists what a base offers build.languages; template_build builds a new version from a recipe v2 (unpublished unless publish is true).',
     'search_files finds text in files under a directory; edit_file replaces exact text in a file (each old_text must occur once) and returns the new revision, which you can pass as expected_revision to the next edit_file of that file so a change made by someone else is detected.',
     'File-first workspaces (workspace_open mode "file_first"; results show mode and tree_revision) keep only files: there is no VM between calls, each exec runs in a fresh VM, and only files under /home/user persist between exec calls (install dependencies there, e.g. a virtualenv, and start servers within the command that needs them).',
-    'An exec result on a file-first workspace carries the paths it changed (changed) and the new tree_revision; an execution cannot be canceled. Process, terminal, git and browser tools and workspace_suspend, workspace_resume and workspace_fork do not apply to them (error reason not_supported_for_mode).',
+    'An exec result on a file-first workspace carries the paths it changed (changed) and the new tree_revision; an execution runs to completion. Process, terminal, git and browser tools and workspace_suspend, workspace_resume and workspace_fork do not apply to them (error reason not_supported_for_mode).',
     'Account-level actions are not tools of this server: it works inside one project with a project API key, which the API refuses for them. Registering, signing in, organizations, projects, API keys, members, billing and plan upgrades, spend alerts and audit export are done with the shard CLI: `npx @shardflux/cli@latest --help` (for example `shard auth login`, `shard setup`, `shard billing upgrade <plan>`). A person still opens the verification email and pays on the Checkout page the CLI prints.',
-    `Feedback: send_feedback goes straight to the Shardflux founder, who reads every message. ${FEEDBACK_USE}`,
+    `Feedback: send_feedback goes straight to the Shardflux team, who read every message. ${FEEDBACK_USE}`,
 ].join(' ');
 /**
- * The startup version check (0.4.0; contracts §30.4): one GET <api>/v1/client-versions through the server's fetch
+ * The startup version check (0.4.0): one GET <api>/v1/client-versions through the server's fetch
  * (the SDK's checkClientVersion: 3 s timeout, never throws) for @shardflux/mcp at MCP_SERVER_VERSION. Outdated or
  * unsupported: one `warn` line whose message is the notice (`@shardflux/mcp 0.4.0 is outdated: 0.5.0 is available.
  * Update: <upgrade command>`) plus the status fields. Anything else (current; unknown: not listed, `latest` null while
@@ -421,7 +446,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
      * Wake on use for a workspace's tools: `workspace.wake()` within the SDK's transition budget (SHARDFLUX_WAKE_TIMEOUT_MS)
      * and 250 ms short of the call's deadline, so a wake that runs out reports the operation (OperationTimeoutError) rather
      * than a bare deadline. null when SHARDFLUX_WAKE=off: the refusal (workspace_not_running) comes back instead. The
-     * wake's held resume (contracts §22.6) returns the token of this server's tools (its agent label), so the woken call
+     * wake's held resume returns the token of this server's tools (its agent label), so the woken call
      * runs at once with it.
      */
     const wakeFor = (ws) => config.wake === false
@@ -480,7 +505,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
     /**
      * The workspace a key names, across every lifetime and purpose (sessions, drafts and test instances are hidden from
      * the default list), preferring the live workspace over tombstones: an ended session leaves a tombstone with the same
-     * key, and the key then opens a new workspace (contracts §19.11). Null when the key names none.
+     * key, and the key then opens a new workspace. Null when the key names none.
      */
     const lookup = async (key, opts2) => {
         const cached = handles.get(key);
@@ -544,7 +569,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
         {
             name: 'workspace_open',
             title: 'Open workspace',
-            description: 'Open a persistent workspace by key: creates it from the template on first use, reconnects (or resumes) it afterwards, never resets it. Waits until it is ready unless wait is false; on timeout the start continues server side (operation_wait), for at most 15 minutes while it waits for capacity. The result’s timing says where the time went. mode "file_first" opens a file-first workspace (files only, ready at once; see mode).',
+            description: 'Open a persistent workspace by key: creates it from the template on first use, reconnects (or resumes) it afterwards, never resets it. Waits until it is ready unless wait is false; on timeout the start continues server side (operation_wait); a queued start has a deadline 15 minutes after it was created. The result’s timing says where the time went. mode "file_first" opens a file-first workspace (files only, ready at once; see mode).',
             inputSchema: obj({
                 workspace_key: workspaceKeyProp(pinned),
                 template: {
@@ -554,6 +579,8 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     description: config.template ? `Template slug (default "${config.template}").` : 'Template slug for a new workspace, e.g. "python-node-browser".',
                 },
                 ...capsProps,
+                labels: { type: 'object', additionalProperties: true, description: 'Searchable workspace labels; replaces existing labels when supplied.' },
+                idle_policy: { type: 'string', pattern: '^(adaptive|never|fixed:[0-9]+)$', description: 'Automatic suspend policy.' },
                 lifetime: {
                     type: 'string',
                     enum: ['persistent', 'session'],
@@ -590,6 +617,8 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     ...(caps ? { caps } : {}),
                     ...(lifetime ? { lifetime } : {}),
                     ...(inputs ? { inputs } : {}),
+                    ...(args.labels !== undefined ? { labels: stringMap(args.labels, 'labels') } : {}),
+                    ...(typeof args.idle_policy === 'string' ? { idlePolicy: args.idle_policy } : {}),
                     ...(mode ? { mode } : {}),
                     agentLabel: config.agentLabel,
                     wait: args.wait === false ? false : waitOpts(call),
@@ -605,6 +634,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
             description: 'List the workspaces of this API key’s project (key, state, template, active operation).',
             inputSchema: obj({
                 prefix: { type: 'string', minLength: 1, maxLength: 200, description: 'Only keys starting with this prefix.' },
+                labels: { type: 'object', additionalProperties: true, description: 'Exact label matches; all supplied pairs must match.' },
                 state: { type: 'string', enum: OBSERVED_STATES, description: 'Observed state filter.' },
                 include_deleted: { type: 'boolean', description: 'Include deleted workspaces (and ended sessions).' },
                 lifetime: { type: 'string', enum: ['persistent', 'session', 'any'], description: 'Lifetime filter (default persistent: session workspaces are hidden).' },
@@ -616,6 +646,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
             run: async (args) => {
                 const page = await cloud.workspaces.list({
                     ...(typeof args.prefix === 'string' ? { keyPrefix: args.prefix } : {}),
+                    ...(args.labels !== undefined ? { labels: stringMap(args.labels, 'labels') } : {}),
                     ...(typeof args.state === 'string' ? { state: args.state } : {}),
                     ...(args.include_deleted === true ? { includeDeleted: true } : {}),
                     ...(typeof args.lifetime === 'string' ? { lifetime: args.lifetime } : {}),
@@ -641,10 +672,49 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 return { workspace: summarizeWorkspace(ws.data), recent_operations: ops.data.map(summarizeOperation) };
             },
         },
+        {
+            name: 'workspace_idle', title: 'Inspect idle status', description: 'Read idle policy and activity without waking or recording activity.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned) }, keyRequired),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).idle(call.signal),
+        },
+        {
+            name: 'workspace_keepalive', title: 'Declare ongoing work', description: 'Prevent idle suspension for seconds; never shortens an existing keepalive.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), seconds: { type: 'integer', minimum: 1 } }, [...keyRequired, 'seconds']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).keepalive(args.seconds, call.signal),
+        },
+        {
+            name: 'workspace_set_idle_policy', title: 'Set idle policy', description: 'Set adaptive, never or fixed:<seconds> (60..604800); default restores the inherited policy.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), policy: { type: 'string', description: 'adaptive, never, fixed:<seconds>, or default' } }, [...keyRequired, 'policy']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+            run: async (args, call) => summarizeWorkspace((await (await resolve(keyOf(args), { signal: call.signal })).setIdlePolicy(args.policy === 'default' ? null : args.policy)).data),
+        },
+        {
+            name: 'workspace_set_labels', title: 'Replace workspace labels', description: 'Replace all labels; an empty object clears them. Labels are searchable metadata, not secrets.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), labels: { type: 'object', additionalProperties: true } }, [...keyRequired, 'labels']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+            run: async (args, call) => summarizeWorkspace((await (await resolve(keyOf(args), { signal: call.signal })).setLabels(stringMap(args.labels, 'labels'))).data),
+        },
+        {
+            name: 'workspace_exec_start', permission: 'exec', title: 'Start background command', description: 'Start a tracked exec session. stdin_open keeps a pipe open for workspace_exec_input. Processful workspaces only.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), argv: { type: 'array', items: { type: 'string' }, minItems: 1 }, session_id: { type: 'string' }, stdin_open: { type: 'boolean' }, cwd: { type: 'string' } }, [...keyRequired, 'argv']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).cell().exec.start({ argv: args.argv,
+                ...(typeof args.session_id === 'string' ? { session_id: args.session_id } : {}), stdin_open: args.stdin_open === true,
+                ...(typeof args.cwd === 'string' ? { cwd: args.cwd } : {}) }, call.signal),
+        },
+        {
+            name: 'workspace_exec_input', permission: 'exec', title: 'Write command stdin', description: 'Write up to 64 KiB at the acknowledged byte offset (0 initially). close sends EOF. A repeated identical last frame cannot duplicate bytes; continue from a partial acknowledgement.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), session_id: { type: 'string' }, data: { type: 'string', maxLength: 65536 }, offset: { type: 'integer', minimum: 0 }, close: { type: 'boolean' } }, [...keyRequired, 'session_id', 'offset']),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+            run: async (args, call) => (await resolve(keyOf(args), { signal: call.signal })).cell().exec.input(args.session_id, typeof args.data === 'string' ? args.data : '', { offset: args.offset, close: args.close === true, signal: call.signal }),
+        },
         {
             name: 'workspace_suspend',
             title: 'Suspend workspace',
-            description: 'Suspend a running workspace (durable full-state checkpoint; processes stop, files and state are kept, and the next tool call resumes it). Returns the suspend operation (with wait: once finished, and its timing). ' +
+            description: 'Suspend a running workspace (full-state checkpoint; processes stop, files and state are kept, and the next tool call resumes it). Returns the suspend operation (with wait: once finished, and its timing). ' +
+                'A finished suspend returns as soon as the workspace is sealed on its host (typically a few hundred ms); its durable field turns true when the copy lands in durable storage, typically within a second. Pass durable: true to return only then. ' +
                 'With after_seconds the suspend is deferred instead: the workspace is suspended once it has been idle that long. Use it when you finish your work (the end of your turn), e.g. after_seconds 60, so the workspace stops using RAM soon after instead of waiting for its idle timeout. ' +
                 'Your next tool call on the workspace cancels it; a command still running or a keepalive postpones it until after_seconds after it ends. Returns suspend_request (not_before: the earliest suspend). Not for file-first workspaces (never suspended).',
             inputSchema: obj({
@@ -656,10 +726,14 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     description: 'Suspend once the workspace has been idle this many seconds (0-3600; 0 = as soon as it is idle) instead of now. Omit to suspend now.',
                 },
                 wait: { type: 'boolean', description: 'Wait until the suspend finishes (default false). Not with after_seconds.' },
+                durable: { type: 'boolean', description: 'Wait until the suspend is in durable storage (result durable: true; implies wait). Not with after_seconds.' },
             }, keyRequired),
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
             run: async (args, call) => {
                 const afterSeconds = typeof args.after_seconds === 'number' ? args.after_seconds : undefined;
+                if (afterSeconds !== undefined && args.durable === true) {
+                    throw new ToolError('invalid_arguments', 'durable does not apply with after_seconds: the suspend happens later, once the workspace has been idle. Omit durable, or omit after_seconds to suspend now.');
+                }
                 if (afterSeconds !== undefined && args.wait === true) {
                     throw new ToolError('invalid_arguments', 'wait does not apply with after_seconds: the suspend happens later, once the workspace has been idle. Omit wait, or omit after_seconds to suspend now.');
                 }
@@ -669,7 +743,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     throw notForMode(ws, 'suspend', 'api', `workspace_suspend is not available for the file-first workspace "${key}": nothing runs between its exec calls, so it is never suspended; its files persist as they are.`);
                 }
                 if (afterSeconds === undefined) {
-                    const op = await cloud.workspaces.suspend(ws.id, lifecycleOpts(args, call));
+                    const op = await cloud.workspaces.suspend(ws.id, args.durable === true ? { ...lifecycleOpts({ ...args, wait: true }, call), durable: true } : lifecycleOpts(args, call));
                     call.operationId = op.id;
                     return { operation: summarizeOperation(op) };
                 }
@@ -687,7 +761,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
             },
         },
         lifecycleTool('workspace_resume', 'Resume workspace', 'Resume a suspended workspace. Returns the resume operation (with wait: once finished, and its timing). A notice in the result (timing.server.memory_restored false) means it booted from its saved disk: files kept, processes restarted. Not for file-first workspaces (never suspended).', 'resume', 
-        // Through the server's handle: a waited resume is held until the workspace runs (contracts §22.6) and the handle
+        // Through the server's handle: a waited resume is held until the workspace runs and the handle
         // keeps the view and this server's tool token, so the next workspace tool starts at once.
         (ws, o) => ws.resume({ ...o, agentLabel: config.agentLabel })),
         {
@@ -716,10 +790,19 @@ export function createShardfluxMcpServer(config, opts = {}) {
         {
             name: 'operation_wait',
             title: 'Wait for operation',
-            description: 'Wait for a lifecycle operation (open, suspend, resume, fork, ...) to finish, up to timeout_ms. Returns the operation and the wait’s timing.',
-            inputSchema: obj({ operation_id: { type: 'string', minLength: 36, maxLength: 36, description: 'Operation id (UUID).' } }, ['operation_id']),
+            description: 'Wait for a lifecycle operation (open, suspend, resume, fork, ...) to finish, up to timeout_ms. Returns the operation and the wait’s timing. With durable (a suspend or fork), also wait until its copy is in durable storage.',
+            inputSchema: obj({
+                operation_id: { type: 'string', minLength: 36, maxLength: 36, description: 'Operation id (UUID).' },
+                durable: { type: 'boolean', description: 'A suspend or fork: also wait until result durable is true.' },
+            }, ['operation_id']),
             annotations: { readOnlyHint: true, openWorldHint: false },
-            run: async (args, call) => ({ operation: summarizeOperation(await wait(call, String(args.operation_id))) }),
+            run: async (args, call) => {
+                if (args.durable !== true)
+                    return { operation: summarizeOperation(await wait(call, String(args.operation_id))) };
+                call.timed = true;
+                call.operationId = String(args.operation_id);
+                return { operation: summarizeOperation(await cloud.workspaces.waitForDurable(String(args.operation_id), waitOpts(call))) };
+            },
         },
         {
             name: 'template_get',
@@ -838,13 +921,13 @@ export function createShardfluxMcpServer(config, opts = {}) {
     management.push({
         name: 'send_feedback',
         title: 'Send feedback',
-        description: `Send feedback straight to the Shardflux founder, who reads every message. ${FEEDBACK_USE} Categories: bug (something failed or behaved wrongly), confusing (an error, doc, name or output was unclear or misleading), missing (a capability, option or template you needed does not exist), idea, praise (something worked well), other. Rate limited per API key (rate_limited with details.retry_after_seconds); the same message within 24 hours is recorded once (duplicate: true).`,
+        description: `Send feedback straight to the Shardflux team, who read every message. ${FEEDBACK_USE} Categories: bug (something failed or behaved wrongly), confusing (an error, doc, name or output was unclear or misleading), missing (a capability, option or template you needed does not exist), idea, praise (something worked well), other. Rate limited per API key (rate_limited with details.retry_after_seconds); the same message within 24 hours is recorded once (duplicate: true).`,
         inputSchema: obj({
             message: { type: 'string', minLength: 1, maxLength: FEEDBACK_MESSAGE_MAX_LENGTH, description: 'What you did, what happened and what you expected (1-8000 characters). Leave secrets out.' },
             category: { type: 'string', enum: [...FEEDBACK_CATEGORIES], description: 'bug, confusing, missing, idea, praise or other.' },
             workspace: { type: 'string', minLength: 1, maxLength: 200, description: pinned ? `Workspace key or id it is about (default "${pinned}").` : 'Workspace key or id it is about.' },
-            request_id: { type: 'string', minLength: 1, maxLength: 200, description: 'request_id from the error, so the founder can find the logs.' },
-            error_code: { type: 'string', minLength: 1, maxLength: 100, description: 'The error code seen (error.code, or details.error_code of a failed operation), e.g. capacity_unavailable.' },
+            request_id: { type: 'string', minLength: 1, maxLength: 200, description: 'request_id from the error, so the team can find the logs.' },
+            error_code: { type: 'string', minLength: 1, maxLength: 100, description: 'The error code seen (error.code, or details.error_code of a failed operation), e.g. template_not_found.' },
             command: { type: 'string', minLength: 1, maxLength: 2000, description: 'The tool call (name and arguments) or command that led to it.' },
         }, ['message', 'category']),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -870,7 +953,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 id: r.id,
                 received_at: r.receivedAt,
                 duplicate: r.duplicate,
-                note: r.duplicate ? 'The same message was already received in the last 24 hours; it was not emailed again.' : 'Delivered to the Shardflux founder. Keep sending feedback as you work.',
+                note: r.duplicate ? 'The same message was already received in the last 24 hours; it was not emailed again.' : 'Delivered to the Shardflux team. Keep sending feedback as you work.',
             };
         },
     });
@@ -883,7 +966,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
      */
     const execDescription = (sdkDescription, listing) => {
         if (listing === 'file_first')
-            return `${sdkDescription}${execDeadline} An execution cannot be canceled: if the deadline passes first it continues server side (the error names its execution_id) and the next exec waits for it.`;
+            return `${sdkDescription}${execDeadline} An execution runs to completion: if the deadline passes first it continues server side (the error names its execution_id) and the next exec waits for it.`;
         if (listing === 'processful')
             return `${sdkDescription}${execDeadline}`;
         return `${sdkDescription} On a file-first workspace (workspace_open mode "file_first") each call instead runs in a fresh VM on the workspace’s files: only files under /home/user persist between calls, and the result adds execution_id, state, tree_revision and changed (the paths the command added, modified or deleted).${execDeadline}`;
@@ -921,7 +1004,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 }
                 const ws = await resolve(key, { signal: call.signal });
                 // The SDK's tools for the workspace's mode: a file-first workspace has exec (as executions) and the file tools.
-                // A file-first execution cannot be canceled; its id is kept so a deadline error can name it.
+                // A file-first execution runs to completion; its id is kept so a deadline error can name it.
                 const tool = workspaceTools(ws, {
                     agentLabel: config.agentLabel,
                     tools: [...ALL_TOOL_PERMISSIONS],
@@ -982,7 +1065,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
         if (mode !== undefined)
             listedMode = mode;
         const fileFirst = mode === 'file_first';
-        const mgmt = fileFirst ? management.filter((d) => !VM_ONLY_MANAGEMENT.has(d.name)) : management;
+        const mgmt = management.filter((d) => (!fileFirst || !VM_ONLY_MANAGEMENT.has(d.name)) && (d.permission === undefined || permitted.includes(d.permission)));
         const tools = (fileFirst ? fileFirstDefs : workspaceDefs).filter((d) => d.permission !== undefined && permitted.includes(d.permission));
         return { tools: [...mgmt, ...tools].map(toMcpTool) };
     });
@@ -1015,7 +1098,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
         try {
             const value = await Promise.race([running, aborted]);
             log('info', 'tool call', { tool: name, outcome: 'ok', ms: Date.now() - started });
-            const notice = call.timed && call.timing ? processRestartNotice(call.timing) : undefined;
+            const notice = call.timed && call.timing ? timingNotice(call.timing) : undefined;
             return okResult(call.timed && call.timing && isObject(value) ? { ...value, timing: compactTiming(call.timing), ...(notice ? { notice } : {}) } : value);
         }
         catch (err) {
@@ -1045,7 +1128,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
                 ...(info.request_id ? { request_id: info.request_id } : {}),
                 ...(info.execution_id ? { execution_id: info.execution_id } : {}),
             });
-            // A failure suggests send_feedback; a failed send_feedback says how to still reach the founder.
+            // A failure suggests send_feedback; a failed send_feedback says how to still reach the Shardflux team.
             const s = info.details?.retry_after_seconds;
             const siblings = name === 'send_feedback'
                 ? info.code === 'invalid_arguments'
@@ -1055,7 +1138,7 @@ export function createShardfluxMcpServer(config, opts = {}) {
                     ? { feedback: feedbackSuggestion(info) }
                     : {};
             // A wake that booted the saved disk before the failure still restarted every process: said next to the error.
-            const notice = call.timed && call.timing ? processRestartNotice(call.timing) : undefined;
+            const notice = call.timed && call.timing ? timingNotice(call.timing) : undefined;
             return errorResult(info, call.timed && call.timing ? compactTiming(call.timing) : undefined, { ...siblings, ...(notice ? { notice } : {}) });
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/mcp",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "mcpName": "dev.shardflux/mcp",
   "type": "module",
   "description": "Shardflux MCP server (stdio): give Claude, Cursor, Codex or any MCP client persistent cloud workspaces to run commands, edit files, use git and a browser in. Uses your scoped Shardflux API key.",
@@ -46,7 +46,7 @@
     "@modelcontextprotocol/sdk": "1.30.0",
     "yaml": "2.9.1",
     "zod": "4.6.5",
-    "@shardflux/sdk": "^0.11.0"
+    "@shardflux/sdk": "^0.12.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",