@shardflux/cli 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,7 +1,65 @@
 # Changelog
 
-Every command and option the README shows is available from the version named here. Below 1.0, a minor release may
-break compatibility; breaking changes are marked **Breaking**.
+Every command and option the README shows is available from the version named here. Breaking changes ship in minor
+releases and are marked **Breaking**.
+
+## 0.6.2
+
+Needs `@shardflux/sdk` 0.11.1 or later.
+
+### The signup trial: when it ends, and it is never for sale
+
+New organizations can start on a trial: 60 days at Developer limits, no card. The API gives the plan in force an end
+(`plan.ends_at`) and the usage period of a trial its own window (`period.source` `grant`).
+
+- `shard billing status` shows the end: `plan  trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog ...)`, and
+  on a trial the next step is `keep these limits after the trial: shard billing upgrade developer` (a subscription
+  outranks the trial and ends it). A design-partner plan shows its end the same way. Plans without an end read as
+  before.
+- `shard billing plans` lists the public plans only: the trial and the design-partner plan are granted, never bought,
+  and are left out (also of the purchasable plans `billing upgrade` names). `--json` still prints the API's catalog.
+- `shard usage`: a trial's period reads `<start> .. <end> (the trial; then free)`, and a used-up trial allowance
+  `yes (the trial ends; the organization is back on free)` instead of "new opens/resumes are refused".
+
+### Wording: help, hints and messages say what to do, without internals (no behaviour change)
+
+- `shard feedback` goes to the Shardflux team: `Sent to the Shardflux team (feedback <id>). Thank you.`, and the help
+  asks agents to also pass on what their user asks for (a capability, an option or a smoother workflow) and their
+  ideas. The help examples are a `template_not_found` bug report and an idea; `--error-code` shows
+  `e.g. template_not_found`.
+- `capacity_unavailable` hint: `nothing was started; run the same command again`. A wait that times out on a queued
+  start says `it stays queued server side until <deadline_at> and fails with capacity_unavailable if it has not
+  started by then`.
+- `no_execution_host`: `the execution cannot be placed right now, also after retries with the same execution id;
+  nothing ran. Retry`. `host_capacity`: `the workspace cannot be woken right now and the call did not run; retry in a
+  few seconds`.
+- `host_feature_unavailable`: `files search is not available for this workspace (retrying does not help); search with
+  a command instead: ...` (the same for `files patch` and other calls).
+- An interrupted file-first `ws exec` says `(an execution runs to completion)`; `mode_not_available` drops "yet";
+  `--open` no longer says "best effort"; `templates init --help` no longer names an internal document.
+
+## 0.7.0 (release candidate)
+
+Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
+
+Uses SDK 0.12.0 and its pooled transport. Adds --labels/--idle-policy to open, --labels to list, ws labels, ws idle, ws exec-start --stdin-open and ws exec-input --offset. Protocol-error JSON includes source. Resume recovers failed workspaces; completed deletion permits key reuse.
+
+Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
+
+### Instant suspend: durable storage
+
+- `shard ws suspend --wait` still returns when the suspend succeeds (sealed on its host); a finished suspend or fork
+  now prints `durable: yes (<n> ms after the suspend)` or `durable: in progress ...` when the result says so.
+- `shard ws suspend --durable`: waits until `result.durable` is true (implies `--wait`, shares `--timeout`). A copy
+  that cannot be made exits 6 with code `durability_lost` (operation id, `details.state` `lost`, `details.reason`); a
+  timeout exits 5 with `details.durable` false and `details.state` `pending`. `--durable` with `--when-idle` or
+  `--cancel-when-idle` is a usage error.
+- `shard operations wait <id> --durable`, and a `durable` line in `operations get|wait` for suspends and forks.
+- `--timing --json`: `server` gains `durable`, `suspend_path`, `durability` and `lost_suspend`.
+- A resume (or a command's wake) whose result carries `lost_suspend` prints a note on stderr naming the restored
+  checkpoint and its time.
+- A suspend-when-idle canceled `workspace_active` says the workspace was in use and keeps running.
+- The `ws suspend` summary no longer says "durable checkpoint".
 
 ## 0.6.1
 
@@ -19,9 +77,9 @@ range is still exit 2 before any request: `--when-idle must be between 0s and 1h
 
 Needs `@shardflux/sdk` 0.11.0 or later.
 
-### A resume that restarted processes says so (cold boot, contracts §12)
+### A resume that restarted processes says so (cold boot)
 
-When the platform's VM runtime changed after a suspend and no host can restore the memory snapshot, the cell resumes
+After a platform runtime change, the cell resumes
 the workspace by booting its saved disk (a cold boot), automatically, also when a command wakes it. Files are as of the
 suspend; every process was restarted.
 
@@ -87,7 +145,7 @@ cell had ended the session `failed_to_start` (`working directory "app" is not a
   `overage_paused` (a payment is past due: update the payment method, `shard billing portal --open`). The exit code
   stays 1.
 
-### Suspend when idle (contracts §20.6)
+### Suspend when idle
 
 - `shard workspaces suspend <id|key> --when-idle <duration>` (30s to 1h): the workspace is suspended once it has been
   idle that long, counted from the later of its last work and the request (suspend when idle, for the end of an agent
@@ -95,11 +153,11 @@ cell had ended the session `failed_to_start` (`working directory "app" is not a
   `--cancel-when-idle` cancels it. `--json` prints `{workspace, operation, suspend_request}`.
 - `shard workspaces get` shows a pending request (`suspend when idle  after N s idle, not before ...`).
 
-## 0.5.0 (not yet published; npm `latest` is 0.4.1)
+## 0.5.0
 
 Needs `@shardflux/sdk` 0.9.0 or later.
 
-### File search, patches and revisions (contracts §26)
+### File search, patches and revisions
 
 - `shard files search <id|key> <path> <pattern>`: content search under a directory (or in one file), printed
   grep-style (`path:line:column: text`, context lines as `path-line- text`). `--regex` (RE2), `-i`/`--ignore-case`,
@@ -115,20 +173,20 @@ Needs `@shardflux/sdk` 0.9.0 or later.
 - Hints for the new refusals: `revision_mismatch` (exit 1) names the current revision; `edit_not_found` and
   `edit_ambiguous` (exit 2, like any `validation_failed`) name the `--old` by position; `host_capacity` says to retry
   shortly (reads, searches and patches already retry it after `Retry-After`).
-- A workspace on a host that predates search and patches (contracts §26.7, while the fleet is upgraded): `files
+- A workspace without search and patches: `files
   search` and `files patch` fail at once with 409 `conflict` `host_feature_unavailable` (exit 1, not retried, no
   wake), with a hint naming `details.feature` and another way to do it now (`shard ws exec <id|key> -- grep -rn ...`
-  for a search; `files read` then `files write` for a patch); they work once the workspace runs on an upgraded host.
-  Such a host returns no revisions (`files stat --revision` prints none).
+  for a search; `files read` then `files write` for a patch).
+  Such a workspace returns no revisions (`files stat --revision` prints none).
 - All three take `--timing`. `files patch` wakes a suspended workspace like `files write`; `files search` and
   `files stat` read its disk (below).
 - `files read|ls|stat|search` of a suspended workspace are answered from its disk without resuming it (the state at
   suspension), also on the first command after the suspend: every `shard` run fetches a new tool token, which the API
   refused for a suspended workspace, so these commands used to resume it. Needs `@shardflux/sdk` 0.9.0 and an API
-  that issues tool tokens for suspended workspaces (contracts §26.4); with an older API they resume it as before.
+  that issues tool tokens for suspended workspaces; with an older API they resume it as before.
   Every other command still resumes it.
 
-### File-first workspaces (contracts §29)
+### File-first workspaces
 
 - `shard workspaces open --mode processful|file-first` (`file_first` too): a file-first workspace is a versioned file
   tree with no VM between commands. It is ready at once, never suspended and always persistent. Without `--mode` a new
@@ -165,7 +223,7 @@ Needs `@shardflux/sdk` 0.9.0 or later.
   `host_restarted`, `tree_moved`, ...).
 - The error line names `execution_id=` when the error is about an execution.
 
-### Waking a suspended workspace is one request (contracts §22.6)
+### Waking a suspended workspace is one request
 
 - Through `@shardflux/sdk` 0.9.0: a command on a suspended workspace (`ws exec`, `files ...`, `ws changes`) wakes it
   with one held resume that returns the running workspace and the CLI's tool token, then runs (refused call, resume,
@@ -173,10 +231,9 @@ Needs `@shardflux/sdk` 0.9.0 or later.
 - `--timing` shows the wake as one `request` phase `(held)`; a wake that runs out of time shows the hold, then the
   states it saw after it (`request 1.00 s (held) → queued …`).
 - `shard workspaces resume --wait` is one held request; its tool token is attributed to the CLI's agent label.
-### The account plane (contracts §30)
+### The account plane
 
-Needs `@shardflux/sdk` 0.9.0 or later (`ShardfluxAccount`, `checkClientVersion`) and an API with CLI sessions
-(contracts §30).
+Needs `@shardflux/sdk` 0.9.0 or later (`ShardfluxAccount`, `checkClientVersion`) and an API with CLI sessions.
 
 ### Everything the web app does, from a terminal (docs/progress/account-cli.md §5)
 
@@ -247,10 +304,10 @@ unchanged and still stores nothing.
 - The top help starts with the no-browser path and groups commands by the credential they use; `shard <group>`
   and `shard auth totp` (a sub-group) list their commands.
 
-### Feedback straight to the founder (needs an API with POST /v1/feedback)
+### Feedback straight to the Shardflux team (needs an API with POST /v1/feedback)
 
 - `shard feedback [--category bug|confusing|missing|idea|praise|other] [--workspace W] [--request-id ID]
-  [--error-code CODE] [--command TEXT] [--from-file F|-] <message...>` sends feedback to the Shardflux founder by
+  [--error-code CODE] [--command TEXT] [--from-file F|-] <message...>` sends feedback to the Shardflux team by
   email. The message is the remaining words (no quotes needed unless the shell needs them) or `--from-file` (`-`:
   standard input, for logs). It is checked before any request (1-8000 characters, a known category, the context
   bounds). The context carries `client: shard-cli/0.5.0` and, unless it is the default `cli`, the agent label as
@@ -260,8 +317,7 @@ unchanged and still stores nothing.
   continue or to email shardflux@heliosone.fi.
 - `shard --help` opens with a Feedback section, and `shard feedback --help` explains when to use each category: coding
   agents are asked to send short feedback while they work, the moment something fails, confuses or is missing, and to
-  pass on (paraphrased, without private data) what their user is frustrated about or asked for that Shardflux could not
-  do, telling the user they sent it.
+  pass on (paraphrased, without private data) what their user asks for, telling the user they sent it.
 - A failure ends with
   `feedback: shard feedback --category bug --request-id <id> --error-code <code> "<what you expected>"`; with `--json`
   the error object gains a sibling `"feedback"` field holding that command. Existing fields are unchanged. Not for
@@ -280,7 +336,7 @@ exports type-check without casts), and the CLI moves to it so `shardflux` instal
 
 Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
 
-### Template editor (contracts §24)
+### Template editor
 
 - `shard templates build <file> [--slug] [--display-name] [--description] [--publish] [--acknowledge PATH]... [--wait]
   [--timeout] [--timing]`: builds a template from template.yaml. Local `from` files and folders are uploaded (folders
@@ -308,13 +364,12 @@ Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
 
 Needs `@shardflux/sdk` 0.6.2 or later.
 
-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).
 
 - A failed operation's error has `retryable` (the operation error's own flag): `retryable=true|false` in the error line,
   `"retryable"` in the `--json` error document, next to `details.error_code`. `details.reason` carries the operation
-  error's reason (for `capacity_unavailable`, why no host fit, e.g. `no_ready_hosts`), printed after the message.
+  error's reason (for `capacity_unavailable`, e.g. `no_ready_hosts`), printed after the message.
 - A retryable failure gets a hint to retry later. Exit codes are unchanged (6 for any failed operation); `shard` does
   not retry.
 - A `--timeout` that ends while the start waits for capacity names the time it gives up (the SDK's message).

package/README.md

@@ -8,8 +8,8 @@ invitations and keys, buy or change a plan, export data and delete an account. B
 [`@shardflux/sdk`](https://www.npmjs.com/package/@shardflux/sdk), so it gets the SDK's retries,
 idempotency keys, operation polling and tool-token handling.
 
-> **Early access.** Shardflux is in early access, and this CLI is below 1.0: commands and output
-> 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.
 
@@ -63,21 +63,20 @@ shard login                                   # verify the key: organization, pr
 
 ## Feedback: agents, use this while you work
 
-**(0.5.0+)** `shard feedback` sends a message straight to the Shardflux founder, who reads every one. If you are a
+**(0.5.0+)** `shard feedback` sends a message straight to the Shardflux team, who read every one. If you are a
 coding agent (Claude Code, Codex, Cursor, ...) driving `shard`, use it actively while you work, not once at the end.
 Send a short message the moment:
 
 - something fails unexpectedly (`--category bug`),
 - an error, doc, name or output is confusing (`--category confusing`),
 - a capability, option or template you need is missing (`--category missing`),
-- something is slow, 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.
+- 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: what you ran, what happened, what you expected. 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. Pass the request id and error code from the error so the founder can find the logs. A failed
+never paste transcripts. Pass the request id and error code from the error so the team can find the logs. A failed
 `shard` command ends with a ready-made line to fill in:
 
 ```text
@@ -86,11 +85,11 @@ feedback: shard feedback --category bug --request-id req-2b9d4f6a8c0e4a1b3d5f7e9
 ```
 
 ```sh
-shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code capacity_unavailable \
-  "ws open failed twice in 10 min; expected a start within a minute"
-shard feedback --category confusing \
-  "user was frustrated that ws open needs a template slug they had to look up; they expected a default"
-shard feedback --category missing no way to copy a file between two workspaces, piped files read into files write
+shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code template_not_found \
+  "ws open --template python-node failed; expected a suggestion of the closest slug"
+shard feedback --category idea \
+  "user would like shard ws open to remember the last template they used"
+shard feedback --category praise forking a workspace with its dev server still running is exactly what we needed
 npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo --from-file -
 ```
 
@@ -131,7 +130,7 @@ terminal, `--json` on every command, secrets only on standard input, and documen
    authentication; valid 10 minutes). Without a terminal `shard` does not ask: the command fails with
    `step_up_required` (exit 4) and the hint names this command.
 7. **Feedback:** send `shard feedback` as you work, the moment something fails, confuses you or is
-   missing, or your user is frustrated with Shardflux (see [Feedback](#feedback-agents-use-this-while-you-work)).
+   missing, or your user asks for an improvement (see [Feedback](#feedback-agents-use-this-while-you-work)).
 
 What stays human: reading the verification email, entering a card in Stripe Checkout, and the
 authenticator app's codes.
@@ -228,7 +227,7 @@ the workspace commands instead of printing it. Revoking the saved key also remov
 
 ```sh
 shard billing plans                                  # public: no sign-in needed
-shard billing status                                 # plan, billing state, period end, pending checkout
+shard billing status                                 # plan (a trial with its end), billing state, period end, pending checkout
 shard billing upgrade <plan> [--open] [--wait] [--timeout 15m]
 shard billing portal [--open]                        # plan changes, payment methods, invoices, cancellation
 shard billing invoices [--all]
@@ -241,12 +240,17 @@ shard billing overage off                            # turn it off (always allow
 
 `billing upgrade` checks the plan against the public catalog (an unknown one lists the purchasable
 plans), starts Stripe Checkout and prints its URL: a person pays there. `--open` also opens it in the
-default browser (`$BROWSER`, else `xdg-open`, `open` or `start`; best effort). The API activates the
+default browser (`$BROWSER`, else `xdg-open`, `open` or `start`). The API activates the
 plan only when Stripe confirms the payment, so `--wait` polls until the subscription is active (exit
 0), the checkout expires or is canceled (exit 6), or `--timeout` runs out (exit 5; the checkout stays
 open). An organization that already has a subscription changes plans in the billing portal: the
 command prints the portal URL instead (exit 0).
 
+On the signup trial (60 days at Developer limits, no card), `billing status` shows when it ends and
+what follows (0.6.2+): `plan  trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog ...)`, then
+`keep these limits after the trial: shard billing upgrade developer`. A subscription outranks the
+trial and ends it. The trial is granted, never bought, so `billing plans` leaves it out.
+
 `billing overage` shows and changes opt-in overage (owners and billing members). With it on,
 workspaces keep opening and running past the CPU-hours and RAM GiB-hours allowances, and the usage
 past them is charged on the next invoice until the charges reach the spend cap. The cap is per
@@ -261,7 +265,7 @@ already charged this period (`spend_cap_below_charges`); a plan without overage
 ```text
 $ shard billing overage on --cap 9
 Acme: overage is on, spend cap $9.00 per billing period ($1.00 to $9.00, the plan price).
-Rates past the allowances: $0.04 per RAM GiB-hour, $0.12 per CPU-hour, charged on the next invoice (this period: shard usage).
+Rates past the allowances: $0.03 per RAM GiB-hour, $0.12 per CPU-hour, charged on the next invoice (this period: shard usage).
 Saved (policy version 1).
 ```
 
@@ -369,9 +373,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `login`, `whoami` | Show the principal behind the project key (`SHARDFLUX_API_KEY`, else the saved one). |
 | `version [--check]` | Print the CLI and SDK versions and the update status (`--check` asks the API now). |
 | `usage [--org <id>] [--estimate \| --series \| --workspace <id\|key>] [--from T] [--to T] [--granularity hour\|day] [--meter M]` | Usage summary for the current period: plan, meters and allowances. `--estimate`: the bill so far and projected allowance use; `--series`: usage over time; `--workspace`: one workspace's usage over time (0.5.0+). The summary includes the [overage](#usage-and-overage) block (0.5.1+). |
-
-| `feedback [--category C] [--workspace W] [--request-id ID] [--error-code CODE] [--command TEXT] [--from-file F\|-] <message...>` | Send feedback straight to the Shardflux founder (0.5.0+). See [Feedback](#feedback-agents-use-this-while-you-work). |
-| `usage [--org <id>] [--estimate \| --series \| --workspace <id\|key>] [--from T] [--to T] [--granularity hour\|day] [--meter M]` | Usage summary for the current period: plan, meters and allowances. `--estimate`: the bill so far and projected allowance use; `--series`: usage over time; `--workspace`: one workspace's usage over time (0.5.0+). |
+| `feedback [--category C] [--workspace W] [--request-id ID] [--error-code CODE] [--command TEXT] [--from-file F\|-] <message...>` | Send feedback straight to the Shardflux team (0.5.0+). See [Feedback](#feedback-agents-use-this-while-you-work). |
 | `workspaces open <key> --template <slug> [--secret NAME]... [--input NAME=value]... [--input-file F] [--lifetime persistent\|session] [--mode processful\|file-first] [--cpu-millis N --memory-mib N --disk-gib N] [--no-wait] [--timeout 5m] [--timing]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready (the template's start commands and services included) unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--input` (0.4.0+) passes the template's text inputs (replacing those of an existing workspace); `--input-file` reads `NAME=value` lines or a JSON object. `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. `--mode file-first` (0.5.0+) opens a [file-first workspace](#file-first-workspaces); the default is processful for a new key and the stored mode for an existing one. |
 | `workspaces list [--state S] [--prefix P] [--lifetime persistent\|session\|any] [--purpose standard\|template_draft\|template_test\|any] [--include-deleted] [--all] [--limit N] [--cursor C]` | One page, or every page with `--all`. The next cursor is printed on stderr. By default only persistent standard workspaces are listed. A file-first workspace's state reads `running (file-first)` (0.5.0+). |
 | `workspaces get <id\|key>` | One workspace (deleted ones included), with the startup of its template's start commands and services (0.4.0+): a failed step shows its exit code, reason and output tail. Its mode, and a file-first workspace's tree revision (0.5.0+). |
@@ -385,9 +387,10 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `files search <id\|key> <path> <pattern> [--regex] [-i\|--ignore-case] [--include G]... [--exclude G]... [--max N]` | Search file contents under a directory (or in one file; gitignore-style globs): `path:line:column: text` per match (0.5.0+). |
 | `files patch <id\|key> <path> (--old T --new T)... [--replace-all] \| --content-file F\|- [--expected-revision R] [--if-revision N]` | Replace exact text (each `--old` must occur once unless `--replace-all`), or the whole content, atomically; `R` is a revision from `files stat --revision` or `absent` (0.5.0+). `--if-revision` (0.5.0+): file-first workspaces only. |
 | `workspaces suspend\|resume <id\|key> [--wait] [--timeout T] [--timing]` | Lifecycle operation. Returns immediately unless you pass `--wait`. |
+| `workspaces suspend <id\|key> --durable [--timeout T]` | (0.7.0+) Suspend and wait until the copy is in durable storage. See "Durable storage". |
 | `workspaces suspend <id\|key> --when-idle D` / `--cancel-when-idle` | (0.5.1+) Suspend once the workspace has been idle for `D` (0 to 1h; `0` = as soon as it is idle, 0.6.1+), or cancel that. See "Suspend when idle". |
 | `workspaces fork <id\|key> <new-key> [caps] [--wait]` | Fork into a new key. |
-| `workspaces delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once. The key of a persistent workspace is never reused. |
+| `workspaces delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once. After deletion finishes, the key can open a new workspace ID. |
 | `workspaces close <id\|key> [--wait]` | End a session workspace now: it is deleted, and the key then opens a new workspace. A persistent workspace is refused (`not_session`). |
 | `workspaces reset <id\|key> --yes [--wait]` | Layered workspaces: wipe every change and restart on the template. The previous state stays restorable for 7 days. |
 | `workspaces save-as-template <id\|key> --template <slug> [--display-name N] [--description T] [--checkpoint ID] [--default-lifetime L] [--default-idle-timeout D] [--acknowledge PATH]... [--no-auto-publish] [--wait]` | Save a layered workspace as the next version of an organization template. `--wait` follows the build. |
@@ -504,8 +507,8 @@ A /home/user/app/out.txt
 
 - **Exit code**: the command's own once it ran to its end: 124 if it timed out (`--timeout`), 128+N if a signal N
   killed it. An execution that `failed` (it could not run the command, e.g. `exec_failed_to_start`) or was `lost`
-  (its host stopped answering, e.g. `lease_expired`) published nothing and exits 6. The error names the reason and
-  says `retryable=true|false`; running it again needs a new `--execution-id`.
+  (see `details.reason`) published nothing and exits 6. The error names the reason and says `retryable=true|false`;
+  running it again needs a new `--execution-id`.
 - **Output** is printed when the command ended, not streamed: stdout and stderr byte for byte, also when they are not
   UTF-8. `--output-limit <bytes>` keeps at most that much of each (default 1 MiB, at most 16 MiB). A cut stream is
   noted on stderr.
@@ -521,13 +524,13 @@ A /home/user/app/out.txt
   with a letter or digit; default a fresh `ex-<uuid>`). The same id with the same command returns the recorded result
   (`replayed`) instead of running it twice, so a script can repeat the call safely; the same id with another command
   is refused (`execution_id_reused`). `shard` re-sends the request with the same id after a dropped connection and
-  after `no_execution_host` (no host had room; `Retry-After`, at most 5 times), and waits within `--wake-timeout` while
-  another execution holds the workspace (`execution_in_progress`).
-- **Ctrl-C**: an execution cannot be canceled. Ctrl-C stops waiting (exit 130) and prints the command that fetches the
-  result later:
+  after `no_execution_host` (the execution cannot be placed right now; `Retry-After`, at most 5 times), and waits
+  within `--wake-timeout` while another execution holds the workspace (`execution_in_progress`).
+- **Ctrl-C**: an execution runs to completion. Ctrl-C stops waiting (exit 130) and prints the command that fetches
+  the result later:
 
   ```text
-  error: Interrupted; execution build-42 keeps running server side if it started (an execution cannot be canceled). [code=interrupted execution_id=build-42]
+  error: Interrupted; execution build-42 keeps running server side if it started (an execution runs to completion). [code=interrupted execution_id=build-42]
   hint: fetch its result later with: shard executions get acme/agent-7 build-42
   ```
 - **`shard executions get <id|key> <execution-id> [--wait D]`** (also `shard ws executions get`): prints the output and
@@ -537,9 +540,9 @@ A /home/user/app/out.txt
   without sending them (`not_supported_for_mode`, exit 1, with a hint). Only paths under `/home/user` exist
   (`outside_tree_root`). `--mode file-first` with `--lifetime session` is a usage error (exit 2), and so are
   `--execution-id`, `--output-limit` and `--if-revision` on a processful workspace.
-- **Opening**: reopening a key with the other mode is `mode_mismatch` (exit 1); a deployment that does not offer
-  file-first workspaces yet answers `mode_not_available` (exit 2); a template version without layered disks
-  `layout_unsupported` (exit 1). Each comes with a hint.
+- **Opening**: reopening a key with the other mode is `mode_mismatch` (exit 1); an account without file-first
+  workspaces gets `mode_not_available` (exit 2); a template version without layered disks `layout_unsupported`
+  (exit 1). Each comes with a hint.
 
 ### Tree revisions
 
@@ -566,7 +569,7 @@ API is waited for as before).
 
 A file-first workspace (0.5.0+) is never suspended, so none of this applies to it.
 
-`files read|ls|stat|search` of a suspended workspace whose disk a host still holds are answered from that disk
+`files read|ls|stat|search` of a suspended workspace are answered from its saved disk
 without waking it (the state at suspension); `files search` then notes it on stderr (`served_from: "disk"` with
 `--json`).
 
@@ -575,13 +578,15 @@ without waking it (the state at suspension); `files search` then notes it on std
   is still queued after 120000 ms`). The operation continues server side:
   `shard operations wait <id>` keeps waiting.
 - A resume or open that fails exits 6.
+- `--no-wake` (or `SHARDFLUX_NO_WAKE=1`) turns this off. A workspace that is not running is then
+  refused at once (exit 1, `workspace_not_running`).
 
-**A resume can restart processes (0.6.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), automatically, also when a command wakes the workspace. The command
-still runs, and the files are as of the suspend, but every process was restarted, as after a reboot: start dev
-servers and background jobs again. `shard` then prints one line on stderr after the output (also with `--json`,
-except on a failure, whose stderr is only the error document), whether or not you pass `--timing`:
+**Detecting a cold resume (0.6.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 command wakes the
+workspace; check `memory_restored`. The command still runs with the files as of the suspend, and processes start
+fresh, as after a reboot: start dev servers and background jobs again. `shard` then prints one line on stderr after
+the output (also with `--json`, except on a failure, whose stderr is only the error document), whether or not you
+pass `--timing`:
 
 ```text
 note: workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342 resumed from its saved disk; running processes were restarted (runtime_changed)
@@ -603,7 +608,6 @@ shard ws suspend acme/demo --cancel-when-idle
 ```
 
 - `--when-idle 0` (0.6.1+) suspends the workspace as soon as it is idle (a few seconds after its last work).
-
 - The idle time counts from the later of the workspace's last work and the request.
 - A command still running, an attached stream or a keepalive postpones the suspend until the duration after it ends.
 - The next tool call on the workspace (the next turn) or a resume cancels the request. Repeating replaces it.
@@ -613,22 +617,20 @@ shard ws suspend acme/demo --cancel-when-idle
   workspace that is not running is refused with `conflict` (`not_running`, exit 1), and a file-first workspace (never
   suspended) with `not_supported_for_mode` (exit 1).
 
-## Starts that wait for capacity
+## Start deadlines
 
-An open, resume or fork that no host can admit yet waits in `capacity_pending` for at most 15
-minutes. If `--timeout` ends first, the timeout error names the time it gives up. A start still
-pending then fails with `capacity_unavailable`: nothing was started, and a suspended
-workspace stays suspended. `shard` exits 6 as for any failed operation, and the error says
-`retryable=true` (with `--json`, `"retryable": true`) with a hint to retry later:
+A queued open, resume or fork (`capacity_pending`) has a deadline 15 minutes after it was created.
+If `--timeout` ends first, the timeout error names the deadline. A start still pending at the
+deadline fails with `capacity_unavailable`: nothing was started, and a suspended workspace stays
+suspended. `shard` exits 6 as for any failed operation, and the error says `retryable=true` (with
+`--json`, `"retryable": true`) with a hint to retry:
 
 ```text
 error: Operation 01a0df37-b3a9-7a14-a3e7-11395c349c39 (open) failed: capacity_unavailable (no_ready_hosts) [code=operation_failed operation_id=01a0df37-b3a9-7a14-a3e7-11395c349c39 retryable=true]
-hint: no host could admit it before its deadline; nothing was started. Retry later.
+hint: nothing was started; run the same command again
 ```
 
-`shard` does not retry it for you. A definitive failure has `retryable=false`.
-- `--no-wake` (or `SHARDFLUX_NO_WAKE=1`) turns this off. A workspace that is not running is then
-  refused at once (exit 1, `workspace_not_running`).
+A definitive failure has `retryable=false`.
 
 ## Usage and overage
 
@@ -640,11 +642,11 @@ amount:
 ```text
 overage          accruing (usage past the allowances is charged on the next invoice)
 spend cap        $9.00 (at most $9.00, the plan price)
-overage charges  $3.00 of $9.00 (33.33%), $6.00 left; billed on the next invoice
+overage charges  $2.40 of $9.00 (26.67%), $6.60 left; billed on the next invoice
 cap reached      2026-09-29 15:02:46Z (projected at this period's average use)
 
 OVERAGE        UNIT       PAST ALLOWANCE  BILLED  RATE   AMOUNT
-ram_gib_hours  gib_hours  70              60      $0.04  $2.40
+ram_gib_hours  gib_hours  70              60      $0.03  $1.80
 cpu_hours      hours      5               5       $0.12  $0.60
 ```
 
@@ -665,19 +667,18 @@ names `details.reason`, and a hint says what to do (0.5.0+):
 `--timing` (0.3.0+) says where the time of an open or a wait went. After the call, `shard` prints the lifecycle
 timing that [`@shardflux/sdk`](https://www.npmjs.com/package/@shardflux/sdk) measured (its `formatTiming()`) on
 stderr. It is printed when the call fails, times out or is interrupted too, before the error, and the exit code does
-not change. A slow open reads, for example:
+not change. A resume reads, for example:
 
 ```text
-$ shard ws open acme/demo --template python-node-browser --timing
-Workspace acme/demo (01a0e5a8-3edd-74ba-b489-d62b8925e342) is ready.
-...
-open 34.18 s, succeeded (workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342, operation 01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33)
-  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 0.59 s → view 42 ms ∥ token 61 ms
-  server: queued 33.40 s, ran 0.62 s, total 34.02 s; start warm, boot to ready 79 ms
-  outside the server: 0.16 s
+$ shard ws resume acme/demo --wait --timing
+Resuming acme/demo (01a0ead6-92e5-7d19-ab7a-f565bf4676cb): operation 01a0ead6-bd61-737a-ae88-66e2d01a6e25 resume succeeded
+resume 413 ms, succeeded (workspace 01a0ead6-92e5-7d19-ab7a-f565bf4676cb, operation 01a0ead6-bd61-737a-ae88-66e2d01a6e25)
+  client: request 218 ms → queued 195 ms
+  server: queued 51 ms, ran 290 ms, total 341 ms; resume from local_cache, boot to ready 211 ms, host disk 0 ms, load 6 ms, ready 62 ms, total 211 ms, after_restore 36 ms
+  outside the server: 72 ms
 ```
 
-Here the time went to waiting for a host with capacity; the network and the VM start were fast.
+This resume brought the workspace back from its host's local cache, memory and running processes included, in 341 ms on the server and 413 ms end to end.
 
 - **client**: phases on your clock. `request` is the API call; `(held)` means the API held it until the workspace
   was ready, up to 20 s at a time. Then come the operation states seen while waiting, with the server's reason, and
@@ -708,7 +709,7 @@ With `--json`, stdout carries the timing as a `timing` field of the command's JS
 not say), `boot_to_ready_ms`, ...) and `outside_server_ms`. It is `null` when the command made no lifecycle call. On a failure the error document on stderr
 carries it: `{"error": {...}, "timing": {...}}`.
 
-`shard` does not stream progress while it waits. For live events, use the SDK's `onProgress`.
+For live progress events, use the SDK's `onProgress`.
 
 ## Secrets
 
@@ -787,17 +788,54 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 | 2 | usage error: bad arguments, or input the API rejected as `validation_failed` |
 | 3 | not found: workspace, operation or route |
 | 4 | authentication or authorization: missing, malformed, revoked or insufficient key or session; `step_up_required` (run `shard auth step-up`), `mfa_required` (a sign-in waiting for its code), `email_unverified`, `invalid_credentials` |
-| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`), a start waiting for capacity for at most 15 minutes. `executions get` (0.5.0+): the execution is still queued or running. `billing upgrade --wait` (0.5.0+): nobody paid in time (the checkout stays open) |
-| 6 | the awaited operation ended `failed` or `canceled` (also a resume or open that failed while waking a workspace). `retryable=true` in the error means it may succeed later (`capacity_unavailable`). Also a file-first execution that ended `failed` or `lost` (0.5.0+): nothing was published. `exec` (0.5.1+): the command could not start (`exec_failed_to_start`). `billing upgrade --wait` (0.5.0+): the checkout expired or was canceled (`checkout_ended`) |
-| 130 | interrupted (Ctrl-C). Waits stop at once, and exec sends a cancel to the session. A file-first execution cannot be canceled: it keeps running, and the error names the `shard executions get` command for its result. |
+| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`), up to a queued start's 15-minute deadline. `executions get` (0.5.0+): the execution is still queued or running. `billing upgrade --wait` (0.5.0+): nobody paid in time (the checkout stays open) |
+| 6 | the awaited operation ended `failed` or `canceled` (also a resume or open that failed while waking a workspace). `retryable=true` in the error means a retry can succeed (`capacity_unavailable`). Also a file-first execution that ended `failed` or `lost` (0.5.0+): nothing was published. `exec` (0.5.1+): the command could not start (`exec_failed_to_start`). `billing upgrade --wait` (0.5.0+): the checkout expired or was canceled (`checkout_ended`) |
+| 130 | interrupted (Ctrl-C). Waits stop at once, and exec sends a cancel to the session. A file-first execution runs to completion, and the error names the `shard executions get` command for its result. |
 | exec, executions get | the command's own code: 124 if it timed out, 128+N if killed by signal N. Failures before the command ran use the codes above; use `--json` to tell them apart. |
 
+## Durable storage (0.7.0+)
+
+`shard ws suspend --wait` returns as soon as the workspace is sealed on its host, typically in a few hundred ms, and
+its RAM and CPU are released then. The copy lands in durable storage right after, typically within a second:
+
+```sh
+shard ws suspend acme/demo --wait
+# Suspending acme/demo (<id>): operation <op> suspend succeeded
+# durable: in progress, typically within a second (wait with: shard operations wait <op> --durable)
+shard ws suspend acme/demo --durable      # returns once it is durable: "durable: yes (435 ms after the suspend)"
+shard operations wait <op> --durable      # the same for a suspend or fork you already started
+```
+
+- `--durable` implies `--wait` and shares its `--timeout`.
+- `--json` prints the operation as the API returns it: `result.durable` and `result.durability` (`state`
+  `pending` or `durable`, `local_commit_at`, `durable_at`, ...). `--timing` adds `durable`, `suspend_path` and
+  `durability` to `server`.
+- `operations get|wait` show a `durable` line for suspends and forks. A fork of a running workspace reports its copy the
+  same way.
+- The exit codes and errors of `--durable` are in the CLI reference on docs.shardflux.dev.
+
 ## HTTP connections
 
-`shard` opens a fresh HTTP connection for every request (`Connection: close`). On some Node.js
-releases a request sent on a reused keep-alive connection can stall until the request timeout.
-Set `SHARDFLUX_HTTP_KEEPALIVE=1` to reuse connections instead.
+`shard` 0.7.0 uses the SDK’s pooled HTTP/1.1 transport on Node 26. Custom fetch is preserved. `SHARDFLUX_HTTP_KEEPALIVE=0` forces connection closure for diagnosis; `=1` opts into native pooling.
 
 ## License
 
 Apache-2.0
+
+
+## Integration controls (0.7.0+)
+
+```sh
+shard ws open qm/project-42 --template python-node-browser --labels '{"scope":"project-42"}' --idle-policy never
+shard ws list --labels '{"scope":"project-42"}' --json
+shard ws labels qm/project-42 --set '{"scope":"project-42","owner":"qm"}'
+shard ws idle qm/project-42 --json
+shard ws idle qm/project-42 --keepalive 60
+shard ws idle qm/project-42 --policy adaptive
+shard ws suspend qm/project-42 --when-idle 2s
+shard ws exec-start qm/project-42 --stdin-open --session-id qm-worker-1 -- cat
+shard ws exec-input qm/project-42 qm-worker-1 hello --offset 0
+shard ws exec-input qm/project-42 qm-worker-1 --offset 5 --close
+```
+
+Use the byte offset in each acknowledgement, including partial writes. `ws resume` can recover a failed workspace with its existing ID and disk. A completed delete frees the key; old IDs remain deleted. Protocol-error JSON includes `source`; HTTP 404 alone does not mean a workspace was deleted.

package/dist/account-args.js

@@ -16,7 +16,7 @@ const PAGE = {
     limit: { type: 'string', value: '<n>', description: 'Page size.' },
     cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
 };
-const OPEN = { open: { type: 'boolean', description: 'Also open the page in the default browser (best effort; the URL is printed either way).' } };
+const OPEN = { open: { type: 'boolean', description: 'Also open the page in the default browser (the URL is printed either way).' } };
 const AUDIT_FILTERS = {
     source: { type: 'string', value: '<app|cell_tool>', description: 'API events (app) or workspace tool calls (cell_tool).' },
     'actor-type': { type: 'string', value: '<type>', description: 'user, api_key, system, operator or anonymous.' },

package/dist/account-commands.js

@@ -18,7 +18,7 @@ import { UUID, parseDuration, parsePositiveInt } from "./args.js";
 import { openUrl } from "./browser.js";
 import { fileExists, oneOf, out, parseSlugVersion, principal, readInput, resolveWorkspace, str, strs, waitTimeout } from "./commands.js";
 import { AuthConfigError, CheckoutEndedError, InterruptedError, MfaPendingError, NotFoundError, UsageError } from "./errors.js";
-import { apiKeyTable, attachmentTable, auditTable, authSessionTable, billingStatusText, dataExportText, egressVersionTable, invitationTable, invoiceTable, kv, memberTable, money, orgTable, overagePolicyText, planTable, projectEgressText, projectTable, table, time, toolsText, volumeDetail, volumeTable, workspaceEgressText, WORKSPACE_HEADERS, workspaceRow, } from "./format.js";
+import { apiKeyTable, attachmentTable, auditTable, authSessionTable, billingStatusText, dataExportText, egressVersionTable, invitationTable, invoiceTable, isGrantPlan, kv, memberTable, money, orgTable, overagePolicyText, planTable, projectEgressText, projectTable, table, time, toolsText, volumeDetail, volumeTable, workspaceEgressText, WORKSPACE_HEADERS, workspaceRow, } from "./format.js";
 export const DEFAULT_API_URL = 'https://api.shardflux.dev';
 const TOTP = /^\d{6}$/;
 const ROLES = ['owner', 'admin', 'member', 'billing'];
@@ -418,7 +418,7 @@ export function dollarsToMinor(text, what) {
     return Number(m[1]) * 100 + Number((m[2] ?? '').padEnd(2, '0'));
 }
 function purchasablePlans(catalog) {
-    return catalog.plans.filter((p) => p.prices.some((x) => x.purchasable)).map((p) => p.plan_key);
+    return catalog.plans.filter((p) => !isGrantPlan(p) && p.prices.some((x) => x.purchasable)).map((p) => p.plan_key);
 }
 function priceText(catalog, planKey) {
     const plan = catalog.plans.find((p) => p.plan_key === planKey);
@@ -1280,7 +1280,14 @@ export const ACCOUNT_HANDLERS = {
         const account = ctx.account();
         const org = await resolveOrg(ctx, account, values);
         const s = await account.billing.subscription(org.id);
-        const next = s.subscription ? 'manage it: shard billing portal' : s.purchase_available ? 'buy a plan: shard billing plans, then shard billing upgrade <plan>' : '';
+        // The trial has Developer limits: Developer keeps them (a subscription outranks the trial and ends it).
+        const next = s.subscription
+            ? 'manage it: shard billing portal'
+            : s.purchase_available
+                ? s.plan?.plan_key === 'trial'
+                    ? 'keep these limits after the trial: shard billing upgrade developer'
+                    : 'buy a plan: shard billing plans, then shard billing upgrade <plan>'
+                : '';
         out(ctx, `${billingStatusText(s, org)}${next ? `${next}\n` : ''}`, s);
         return 0;
     },

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.6.1";
+export declare const CLI_VERSION = "0.7.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;