@shardflux/mcp 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,7 +1,27 @@
 # 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.5.1
 
@@ -16,8 +36,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 +78,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 +88,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 +111,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 +119,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 +127,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 +160,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 +168,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 +217,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=1` | Reuse HTTP connections. By default every request uses a fresh connection (`Connection: close`). |
 | `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").
@@ -242,9 +240,7 @@ The management tools:
 | `workspace_fork` | Fork into `new_key`. |
 | `operation_wait` | Keep waiting for an operation. |
 | `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 +255,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 +290,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 +306,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 +338,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 +362,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 +371,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 +379,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 +392,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.

package/dist/errors.d.ts

@@ -22,18 +22,18 @@ export interface ToolErrorInfo {
     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,8 +3,8 @@
  * 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';
@@ -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 } : {}),
@@ -115,18 +115,18 @@ export function describeToolError(err, context = {}) {
         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 };
     }
     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.' : '';
         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)'
                 : '';

package/dist/http.d.ts

@@ -1,13 +1,6 @@
 /**
- * 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.
+ * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
+ * default every request uses a fresh connection (`Connection: close`);
+ * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
  */
 export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch): typeof fetch;

package/dist/http.js

@@ -1,16 +1,10 @@
 /**
- * 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.
+ * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
+ * default every request uses a fresh connection (`Connection: close`);
+ * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
  */
 export function makeFetch(env, base = fetch) {
+    // Why a fresh connection by default (Node 26 keep-alive measurements): docs/progress/startup-latency.md.
     if (env.SHARDFLUX_HTTP_KEEPALIVE === '1')
         return base;
     return (input, init) => {

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.5.2";
+/** 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 & {
@@ -185,7 +185,7 @@ 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): {
@@ -239,7 +239,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.5.2';
+/** 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'];
@@ -202,7 +202,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) {
@@ -268,7 +268,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 +302,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 +421,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 +480,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 +544,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: {
@@ -687,7 +687,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 })),
         {
@@ -838,13 +838,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 +870,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 +883,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 +921,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],
@@ -1045,7 +1045,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'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/mcp",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "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.11.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",