@shardflux/cli 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 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**.
 
+## 0.5.1 (not yet published; npm `latest` is 0.5.0)
+
+### A command that could not start is never a silent exit
+
+Production (2026-09-29): `shard ws exec <key> --cwd app -- ls` exited 1 and printed nothing on stdout or stderr. The
+cell had ended the session `failed_to_start` (`working directory "app" is not a directory`).
+
+- `shard ws exec` on a processful workspace: a command that could not start (a `--cwd` that is not a directory, a
+  program not on `PATH`, an unknown user) exits 6, as a failed file-first execution does, with the workspace's reason
+  and a hint on stderr: `error: The command could not start: working directory "/home/user/app" is not a directory
+  (exec_failed_to_start) [code=conflict source=cell]`, then `hint: --cwd must name a directory that exists in the
+  workspace, ...` (or the `PATH` hint). It exited 1 with no output. With `--json` the error document has
+  `details.reason` `exec_failed_to_start`, `details.error` and `details.session_id`. Through `@shardflux/sdk` 0.10.0
+  (`ExecStartError`).
+- A relative `--cwd` is refused by the API before anything runs: 422 `invalid_cwd`, exit 2, and the message names the
+  absolute path it likely means (`use "/home/user/app"`). That holds for every CLI version once the cell refuses it.
+- A session that ended without an exit code, timeout or signal (`lost`, when its host restarted) prints `exec session
+  <id> ended lost without an exit code: <reason>` on stderr; the exit code stays 1. `--json` adds `state` (and `error`
+  when the session has one) to the result.
+- The file-first hint for `exec_failed_to_start` names `--cwd` when the reason is a working directory, instead of
+  always asking whether argv[0] is on `PATH`. `--cwd` help: an absolute path, default `/home/user`.
+
+- A 402 `allowance_exhausted` and a spend-policy `version_mismatch` end without the `feedback:` line: they are billing
+  states whose hint names the next step, not problems to report.
+### Opt-in overage with a spend cap
+
+- `shard usage` prints an overage block from the summary's `spend_cap`: the state (`off`, `paused`, `accruing`,
+  `warning`, `reached`, ...), the spend cap, the charges of the cap with what is left, the date the cap is projected
+  to be reached, and a table of the units past each allowance (CPU-hours, RAM GiB-hours) with the billed units, rate
+  and amount. Allowances past `included` while overage is on show cap state `overage`; `allowance exhausted` names the
+  reason (`allowance_used`, `overage_paused`, `spend_cap_reached`). An API without overage prints no block.
+- `shard billing overage` (signed in; owners and billing members change it): `status` (the default: the state, the
+  spend cap and its range up to the plan price, the rates), `on [--cap <dollars>]`, `cap <dollars>` (e.g. `9` or
+  `9.50`) and `off`, with `--if-version <n>` and `--json` (the API's spend policy). A refusal exits 2 with a hint that
+  names the bound (`spend_cap_above_plan_price`: the plan price; `spend_cap_below_minimum`; `spend_cap_below_charges`:
+  what overage already charged) or the next step (`overage_unavailable`, `spend_cap_required`); a 409
+  `version_mismatch` (also from `egress set --if-version`) exits 1 and names the current version.
+- 402 `allowance_exhausted` gets a hint per `details.reason`: `allowance_used` (upgrade, or `shard billing overage on
+  --cap <dollars>`), `spend_cap_reached` (raise the cap with `shard billing overage cap <dollars>`, or upgrade),
+  `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)
+
+- `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
+  turn). A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.
+  `--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)
 
 Needs `@shardflux/sdk` 0.9.0 or later.
@@ -75,7 +125,7 @@ Needs `@shardflux/sdk` 0.9.0 or later.
 
 ### Waking a suspended workspace is one request (contracts §22.6)
 
-- Through `@shardflux/sdk` 0.8.0: a command on a suspended workspace (`ws exec`, `files ...`, `ws changes`) wakes it
+- 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,
   the command; before: also a wait, a view and a token request). An API without the held resume works as before.
 - `--timing` shows the wake as one `request` phase `(held)`; a wake that runs out of time shows the hold, then the
@@ -178,6 +228,7 @@ unchanged and still stores nothing.
   edit that does not match, a mode the workspace lacks, a reused execution id), and `shard feedback` itself.
 - The positional usage of `shard feedback` is shown as `<message...>`; `--agent-label` also names the reporting agent.
 
+
 ## 0.4.1 (2026-09-28)
 
 Needs `@shardflux/sdk` 0.8.0 or later. No command changes: the SDK's 0.8.0 is a types-only release (its provider tool

package/README.md

@@ -222,6 +222,10 @@ shard billing upgrade <plan> [--open] [--wait] [--timeout 15m]
 shard billing portal [--open]                        # plan changes, payment methods, invoices, cancellation
 shard billing invoices [--all]
 shard billing alerts [--set 50,80,100 | --clear]     # usage alert emails, percent of each allowance
+shard billing overage [status]                       # opt-in overage: state, spend cap and its range, rates
+shard billing overage on [--cap <dollars>]           # turn it on (a cap is needed the first time)
+shard billing overage cap <dollars>                  # change the spend cap, e.g. 9 or 9.50
+shard billing overage off                            # turn it off (always allowed)
 ```
 
 `billing upgrade` checks the plan against the public catalog (an unknown one lists the purchasable
@@ -232,6 +236,24 @@ plan only when Stripe confirms the payment, so `--wait` polls until the subscrip
 open). An organization that already has a subscription changes plans in the billing portal: the
 command prints the portal URL instead (exit 0).
 
+`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
+billing period, from $1 up to the plan price; `shard usage` shows this period's charges. Every owner
+and billing member gets an email when overage is turned on or off or the cap changes. `--json`
+prints the API's spend policy; `--if-version <n>` (its `version`) refuses the change if someone
+changed the policy since (exit 1, `version_mismatch`). A refused cap exits 2 and the hint names the
+bound: the plan price (`spend_cap_above_plan_price`), $1 (`spend_cap_below_minimum`) or what overage
+already charged this period (`spend_cap_below_charges`); a plan without overage answers
+`overage_unavailable`, and turning it on without a cap `spend_cap_required`.
+
+```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).
+Saved (policy version 1).
+```
+
 ## Audit, account export and deletion (0.5.0+)
 
 ```sh
@@ -330,26 +352,29 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `auth register\|verify-email\|resend-verification\|login\|mfa\|status\|logout\|sessions\|step-up`, `auth password change\|reset\|reset-confirm`, `auth email change\|confirm`, `auth totp enroll\|confirm\|disable\|recovery-codes` | The account and its sign-in (0.5.0+): see [Accounts and sign-in](#accounts-and-sign-in-050). |
 | `setup [--org O] [--project P] [--org-name N] [--project-name N] [--key-name N] [--tool T]... [--new-key]`, `env [--shell sh\|fish\|powershell]` | Organization, project and a saved API key in one step; the saved key as shell exports (0.5.0+). See [Setup](#setup-050). |
 | `orgs`, `projects`, `api-keys`, `members`, `invitations`, `templates publish\|archive` | Organizations, projects, API keys, members and invitations with the session (0.5.0+). See [Organizations, projects, keys, members](#organizations-projects-keys-members-050). |
-| `billing plans\|status\|upgrade\|portal\|invoices\|alerts` | Plans, Stripe Checkout, the billing portal, invoices and usage alerts (0.5.0+). See [Billing](#billing-050). |
+| `billing plans\|status\|upgrade\|portal\|invoices\|alerts\|overage` | Plans, Stripe Checkout, the billing portal, invoices, usage alerts (0.5.0+) and opt-in overage (`overage`, 0.5.1+). See [Billing](#billing-050). |
 | `audit list\|export`, `account status\|export\|delete\|cancel-deletion` | The audit log, data exports and account deletion (0.5.0+). |
 | `egress get\|set\|history\|clear`, `volumes list\|create\|get\|delete\|attachments\|attach\|detach` | Outbound network policies and shared volumes with the project key (0.5.0+). |
 | `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+). |
 | `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+). |
 | `workspaces inputs <id\|key>` | The workspace's text inputs (0.4.0+). |
-| `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr. On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). |
+| `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] [-v] [--execution-id ID] [--output-limit N] -- <cmd> [args...]` | Runs argv with no shell. Output is streamed and resumes from byte offsets after dropped connections. `shard` exits with the command's exit code. Ctrl-C cancels the command. `-v` (0.5.0+) then prints the session id and exit status on stderr. `--cwd` is an absolute path (default `/home/user`); a relative one is refused (`invalid_cwd`, exit 2). A command that could not start (a `--cwd` that is not a directory, a program not on `PATH`) exits 6 with the workspace's reason and a hint (0.5.1+; before, it exited 1 with no output). On a file-first workspace (0.5.0+) the command runs as an execution instead: see [File-first workspaces](#file-first-workspaces). |
 | `executions get <id\|key> <execution-id> [--wait D]` | The result of a file-first workspace's execution (0.5.0+): its output, then what ran. Exits with the command's code, 6 if the execution failed or was lost, 5 while it still runs. |
 | `files read <id\|key> <path> [--out F]` | Raw bytes to stdout, or to a local file. |
 | `files write <id\|key> <path> [--from F\|-] [--append] [--no-parents] [--if-revision N]` | Atomic write. The default source is stdin. `--if-revision` (0.5.0+): file-first workspaces only, see [Tree revisions](#tree-revisions). |
 | `files ls <id\|key> <path> [--limit N]` | Directory listing. |
-| `files stat <id\|key> <path> [--revision]` | One path's metadata; `--revision` adds the content's SHA-256 (0.4.0+). |
-| `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.4.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.4.0+). `--if-revision` (0.5.0+): file-first workspaces only. |
+| `files stat <id\|key> <path> [--revision]` | One path's metadata; `--revision` adds the content's SHA-256 (0.5.0+). |
+| `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> --when-idle D` / `--cancel-when-idle` | (0.5.1+) Suspend once the workspace has been idle for `D` (30s to 1h), 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 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`). |
@@ -540,6 +565,26 @@ without waking it (the state at suspension); `files search` then notes it on std
   `shard operations wait <id>` keeps waiting.
 - A resume or open that fails exits 6.
 
+## Suspend when idle (0.5.1+)
+
+A running workspace is billed while it is awake. When an agent's turn ends, ask for a suspend once the workspace has
+been idle for a short time, instead of waiting for its idle policy:
+
+```sh
+shard ws suspend acme/demo --when-idle 2m    # 30s to 1h; whole seconds
+shard ws get acme/demo                       # "suspend when idle  after 120 s idle, not before ..."
+shard ws suspend acme/demo --cancel-when-idle
+```
+
+- 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.
+- If a suspend is already in progress, `shard` names its operation and schedules nothing.
+- `--json` prints `{workspace, operation, suspend_request}`; with `--cancel-when-idle`, the workspace.
+- `--when-idle` and `--cancel-when-idle` cannot be combined with each other, `--wait` or `--timeout` (exit 2). A
+  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
 
 An open, resume or fork that no host can admit yet waits in `capacity_pending` for at most 15
@@ -557,6 +602,36 @@ hint: no host could admit it before its deadline; nothing was started. Retry lat
 - `--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`).
 
+## Usage and overage
+
+`shard usage` prints the current period's plan, meters and allowances. With opt-in overage (0.5.1+), an allowance past
+`included` while overage is on shows cap state `overage`, and a block follows with the overage state, the spend cap,
+the charges of the cap, the date the cap is projected to be reached, and per allowance the units past it and their
+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
+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
+cpu_hours      hours      5               5       $0.12  $0.60
+```
+
+`--json` prints the API's summary, with `spend_cap` and `exhausted_reason`. Owners and billing members turn overage on
+and set the cap with [`shard billing overage`](#billing-050) or under **Usage & billing** in the console.
+
+While an allowance is used up, opens, resumes and forks are refused with 402 `allowance_exhausted` (exit 1). The error
+names `details.reason`, and a hint says what to do (0.5.0+):
+
+| Reason | Hint |
+| --- | --- |
+| `allowance_used` | Upgrade (`shard billing plans`), or turn on overage: `shard billing overage on --cap <dollars>`. |
+| `spend_cap_reached` | The spend cap is reached: raise it (`shard billing overage cap <dollars>`, at most the plan price) or upgrade. |
+| `overage_paused` | A payment is past due: update the payment method (`shard billing portal --open`). |
+
 ## Timing
 
 `--timing` (0.3.0+) says where the time of an open or a wait went. After the call, `shard` prints the lifecycle
@@ -684,7 +759,7 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 | 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. `billing upgrade --wait` (0.5.0+): the checkout expired or was canceled (`checkout_ended`) |
+| 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. |
 | 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. |
 

package/dist/account-args.js

@@ -303,6 +303,18 @@ export const ACCOUNT_COMMANDS = [
         },
         examples: ['shard billing alerts --set 50,80,100'],
     },
+    {
+        path: ['billing', 'overage'],
+        summary: 'Show or change opt-in overage and its spend cap: status (default), on --cap <dollars>, off, cap <dollars>',
+        description: 'With overage on, workspaces keep opening and running past the CPU-hours and RAM GiB-hours allowances; the usage past them is charged on the next invoice until the charges reach the spend cap (per billing period, $1 up to the plan price). Off by default; turning it off is always allowed and what it charged stays on the invoice. Owners and billing members change it, and each of them gets an email about the change. This period\'s charges: shard usage.',
+        positionals: [{ name: 'status|on|off|cap' }, { name: 'dollars' }],
+        options: {
+            ...ORG,
+            cap: { type: 'string', value: '<dollars>', description: 'With on: the spend cap per billing period in dollars, e.g. 9 or 9.50 (needed unless a cap is set already).' },
+            'if-version': { type: 'string', value: '<n>', description: 'Only if the policy version is still n (shard billing overage --json shows it): refuses a concurrent change.' },
+        },
+        examples: ['shard billing overage', 'shard billing overage on --cap 9', 'shard billing overage cap 25.50', 'shard billing overage off'],
+    },
     {
         path: ['audit', 'list'],
         summary: 'List the organization’s audit log, newest first (owners and admins)',

package/dist/account-commands.d.ts

@@ -13,4 +13,6 @@ export type ShellKind = 'sh' | 'fish' | 'powershell';
 export declare function exportLine(shell: ShellKind, name: string, value: string): string;
 /** An RFC 3339 time, or a duration ago (`90m`, `24h`, `7d`, `2w`). */
 export declare function parseTime(text: string, option: string, now?: number): string;
+/** A spend cap in dollars ("9", "9.5", "9.50", "$9") as minor units (cents); at most two decimals. */
+export declare function dollarsToMinor(text: string, what: string): number;
 export declare const ACCOUNT_HANDLERS: Record<string, Handler>;

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, 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, 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'];
@@ -409,6 +409,14 @@ function auditFilters(values) {
     return f;
 }
 // ---- billing ---------------------------------------------------------------------------------------------------
+const OVERAGE_ACTIONS = ['status', 'on', 'off', 'cap'];
+/** A spend cap in dollars ("9", "9.5", "9.50", "$9") as minor units (cents); at most two decimals. */
+export function dollarsToMinor(text, what) {
+    const m = /^\$?(\d{1,7})(?:\.(\d{1,2}))?$/.exec(text.trim());
+    if (!m)
+        throw new UsageError(`${what} must be an amount in dollars such as 9 or 9.50 (got "${text}")`);
+    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);
 }
@@ -1377,6 +1385,39 @@ export const ACCOUNT_HANDLERS = {
         out(ctx, `${org.name}: ${now}${thresholds === null ? '' : ' (saved)'}.\n`, policy);
         return 0;
     },
+    async 'billing overage'(ctx, values, [action = 'status', amount]) {
+        if (!OVERAGE_ACTIONS.includes(action))
+            throw new UsageError(`unknown action "${action}"; use status, on, off or cap (shard billing overage --help)`);
+        const capText = str(values.cap);
+        if (capText !== undefined && action !== 'on')
+            throw new UsageError(action === 'cap' ? 'give the cap as an argument: shard billing overage cap <dollars>' : `--cap goes with on: shard billing overage on --cap <dollars>`);
+        if (action === 'cap' && amount === undefined)
+            throw new UsageError('missing <dollars> for "shard billing overage cap" (e.g. shard billing overage cap 9)');
+        if (action !== 'cap' && amount !== undefined)
+            throw new UsageError(`unexpected argument "${amount}"${action === 'on' ? '; give the cap with --cap <dollars>' : ''}`);
+        const update = {};
+        if (action === 'on')
+            update.overageEnabled = true;
+        if (action === 'off')
+            update.overageEnabled = false;
+        if (action === 'on' && capText !== undefined)
+            update.spendCapMinor = dollarsToMinor(capText, '--cap');
+        if (action === 'cap')
+            update.spendCapMinor = dollarsToMinor(amount, 'the cap');
+        const version = str(values['if-version']);
+        if (version !== undefined) {
+            if (action === 'status')
+                throw new UsageError('--if-version goes with on, off or cap');
+            if (!/^\d+$/.test(version))
+                throw new UsageError('--if-version must be a policy version number (shard billing overage --json shows it)');
+            update.ifMatch = Number(version);
+        }
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const policy = action === 'status' ? await account.billing.spendPolicy(org.id) : await account.billing.setSpendPolicy(org.id, update);
+        out(ctx, overagePolicyText(policy, org.name, action !== 'status'), policy);
+        return 0;
+    },
     async 'audit list'(ctx, values) {
         const filters = auditFilters(values);
         const limitText = str(values.limit);

package/dist/args.d.ts

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

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.5.0';
+export const CLI_VERSION = '0.5.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -241,10 +241,10 @@ const KEY_COMMANDS = [
     {
         path: ['workspaces', 'exec'],
         summary: 'Run a command in a workspace; prints its output and exits with its exit code',
-        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution cannot be canceled: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6.',
+        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution cannot be canceled: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
-            cwd: { type: 'string', value: '<dir>', description: 'Working directory (absolute; under /home/user on a file-first workspace).' },
+            cwd: { type: 'string', value: '<dir>', description: 'Working directory, an absolute path (default /home/user; under /home/user on a file-first workspace). A relative path is refused (invalid_cwd).' },
             env: { type: 'string', multiple: true, value: '<K=V>', description: 'Environment variable (repeatable).' },
             timeout: { type: 'string', value: '<duration>', description: 'Kill the command after this long (exit code 124).' },
             stdin: { type: 'string', value: '<file|->', description: 'Send this file (or - for standard input) to the command’s stdin (max 1 MiB).' },
@@ -268,7 +268,18 @@ const KEY_COMMANDS = [
             'shard ws exec acme/agent-7 --json -- python3 /home/user/report.py > result.json',
         ],
     },
-    { path: ['workspaces', 'suspend'], summary: 'Suspend a running workspace (durable checkpoint)', positionals: [REF], options: { ...WAIT } },
+    {
+        path: ['workspaces', 'suspend'],
+        summary: 'Suspend a running workspace (durable checkpoint), now or once it has been idle',
+        description: 'Without options the suspend is requested now. --when-idle (0.5.1+) defers it instead: the workspace is suspended once it has been idle for that long, counted from the later of its last work and the request, so call it when an agent turn ends. A command still running, an attached exec or terminal stream, or a keepalive postpones it; the next tool call (the next turn) or a resume cancels it. Repeating replaces the pending request. --cancel-when-idle cancels it.',
+        positionals: [REF],
+        options: {
+            'when-idle': { type: 'string', value: '<duration>', description: 'Suspend once the workspace has been idle this long (30s to 1h, e.g. 30s, 2m; 0.5.1+). Cannot be combined with --wait.' },
+            'cancel-when-idle': { type: 'boolean', description: 'Cancel a pending --when-idle request (0.5.1+; idempotent).' },
+            ...WAIT,
+        },
+        examples: ['shard ws suspend acme/demo --wait', 'shard ws suspend acme/demo --when-idle 2m', 'shard ws suspend acme/demo --cancel-when-idle'],
+    },
     { path: ['workspaces', 'resume'], summary: 'Resume a suspended workspace', positionals: [REF], options: { ...WAIT } },
     {
         path: ['workspaces', 'fork'],
@@ -700,7 +711,7 @@ const GROUPS = {
     'api-keys': 'Project API keys (signed in; secrets are shown once)',
     members: 'Members of an organization and their roles (signed in)',
     invitations: 'Invite people to an organization and accept invitations (signed in)',
-    billing: 'Plans, upgrades (Stripe Checkout), the billing portal, invoices and usage alerts (signed in; plans is public)',
+    billing: 'Plans, upgrades (Stripe Checkout), the billing portal, invoices, usage alerts and overage (signed in; plans is public)',
     audit: 'The organization audit log and its export (signed in; owners and admins)',
     account: 'Your account: data export and deletion (signed in)',
     egress: 'Outbound network policies of the project and its workspaces (project API key)',

package/dist/commands.d.ts

@@ -70,6 +70,8 @@ export type Handler = (ctx: Ctx, values: Values, positionals: string[]) => Promi
 export declare const str: (v: Values[string]) => string | undefined;
 export declare const strs: (v: Values[string]) => string[];
 export declare function out(ctx: Ctx, human: string, machine: unknown): void;
+/** `--when-idle <duration>`: whole seconds from 30 to 3600 (the API's after_seconds bounds, contracts §20.6). */
+export declare function whenIdleSeconds(text: string): number;
 export declare function waitTimeout(values: Values): number;
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every

package/dist/commands.js

@@ -16,7 +16,7 @@ import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -66,6 +66,16 @@ function caps(values) {
         c.disk_gib = parsePositiveInt(disk, 'disk-gib', 1_000_000);
     return Object.keys(c).length ? c : undefined;
 }
+/** `--when-idle <duration>`: whole seconds from 30 to 3600 (the API's after_seconds bounds, contracts §20.6). */
+export function whenIdleSeconds(text) {
+    const ms = parseDuration(text, 'when-idle');
+    if (ms % 1000 !== 0)
+        throw new UsageError('--when-idle must be a whole number of seconds (e.g. 30s, 90s, 2m)');
+    const s = ms / 1000;
+    if (s < 30 || s > 3600)
+        throw new UsageError(`--when-idle must be between 30s and 1h (got "${text}")`);
+    return s;
+}
 export function waitTimeout(values) {
     const t = str(values.timeout);
     return t === undefined ? DEFAULT_WAIT_MS : parseDuration(t, 'timeout');
@@ -697,12 +707,30 @@ export const KEY_HANDLERS = {
             throw err;
         }
         const code = execExitCode(r);
+        // No exit code, no timeout, no signal: the session ended without the command's own ending (e.g. lost when its host
+        // restarted). Say so rather than exit 1 in silence (0.5.1); a command that could not start threw ExecStartError.
+        const unexplained = r.exitCode === null && !r.timedOut && !(r.termSignal !== null && r.termSignal > 0);
         if (values.verbose === true && !ctx.json) {
-            const status = r.timedOut ? 'timed out' : r.canceled ? 'canceled' : r.termSignal ? `killed by signal ${r.termSignal}` : `exit code ${r.exitCode ?? '-'}`;
+            const status = r.timedOut ? 'timed out' : r.canceled ? 'canceled' : r.termSignal ? `killed by signal ${r.termSignal}` : unexplained ? r.session.state : `exit code ${r.exitCode ?? '-'}`;
             ctx.io.stderr.write(kv([['session', r.sessionId], ['status', status], ['output', `${r.stdoutBytes} bytes stdout, ${r.stderrBytes} bytes stderr`], ['reconnects', String(r.reconnects)]]));
         }
         if (ctx.json) {
-            ctx.io.stdout.write(json(withTiming(ctx, { session_id: r.sessionId, exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, canceled: r.canceled, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, reconnects: r.reconnects })));
+            ctx.io.stdout.write(json(withTiming(ctx, {
+                session_id: r.sessionId,
+                state: r.session.state,
+                exit_code: r.exitCode,
+                term_signal: r.termSignal,
+                timed_out: r.timedOut,
+                canceled: r.canceled,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                truncated: r.truncated,
+                reconnects: r.reconnects,
+                ...(r.session.error ? { error: r.session.error } : {}),
+            })));
+        }
+        else if (unexplained) {
+            ctx.io.stderr.write(`exec session ${r.sessionId} ended ${r.session.state} without an exit code${r.session.error ? `: ${r.session.error}` : ''}\n`);
         }
         return code;
     },
@@ -822,7 +850,28 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'workspaces suspend'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, o), ['suspend', 'Suspend']);
+        const whenIdle = str(values['when-idle']);
+        const cancel = values['cancel-when-idle'] === true;
+        if (whenIdle === undefined && !cancel)
+            return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, o), ['suspend', 'Suspend']);
+        if (whenIdle !== undefined && cancel)
+            throw new UsageError('--when-idle and --cancel-when-idle cannot be combined');
+        const flag = cancel ? '--cancel-when-idle' : '--when-idle';
+        if (values.wait === true || str(values.timeout) !== undefined)
+            throw new UsageError(`${flag} cannot be combined with --wait or --timeout (nothing is suspended now)`);
+        if (cancel) {
+            const ws = await resolveWorkspace(ctx, ref);
+            const pending = ws.suspendRequest;
+            const after = await ctx.cloud().workspaces.cancelSuspendWhenIdle(ws.id);
+            out(ctx, pending ? `Canceled the pending suspend-when-idle request of ${ws.key} (${ws.id}): ${suspendRequestText(pending)}.\n` : `No suspend-when-idle request was pending for ${ws.key} (${ws.id}).\n`, after.data);
+            return 0;
+        }
+        const afterSeconds = whenIdleSeconds(whenIdle);
+        const ws = await resolveWorkspace(ctx, ref);
+        requireProcessful(ws, 'suspend_when_idle', 'Suspend when idle');
+        const r = await ctx.cloud().workspaces.suspendWhenIdle(ws.id, { afterSeconds });
+        out(ctx, suspendWhenIdleText(ws, { suspend_request: r.suspendRequest, operation: r.operation }), { workspace: r.workspace.data, operation: r.operation, suspend_request: r.suspendRequest });
+        return 0;
     },
     async 'workspaces resume'(ctx, values, [ref]) {
         // With --wait the resume is held until the workspace runs (contracts §22.6); its tool token is the CLI's label.

package/dist/errors.js

@@ -3,7 +3,7 @@
  * stderr with the API's error code, message and request id; the process exit
  * code tells scripts what kind of failure it was (README "Exit codes").
  */
-import { CheckoutTimeoutError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
+import { CheckoutTimeoutError, ExecStartError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
 export const EXIT = {
     ok: 0,
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -120,6 +120,10 @@ function isNamed(err, name) {
     return typeof err === 'object' && err !== null && err.name === name;
 }
 export function describeError(err) {
+    // A processful command that could not start (0.5.1; the SDK's ExecStartError): the workspace's reason, no HTTP status
+    // (the start itself was answered 201) and details.error, details.session_id.
+    if (err instanceof ExecStartError)
+        return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}), source: err.source };
     if (err instanceof ShardfluxApiError) {
         return {
             code: err.code,
@@ -205,6 +209,9 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.operationFailed;
     if (err instanceof ExecutionPendingError)
         return EXIT.timeout;
+    // A command that could not start exits 6 in both modes, as a failed execution does (0.5.1).
+    if (err instanceof ExecStartError)
+        return EXIT.operationFailed;
     if (err instanceof ShardfluxApiError) {
         if (AUTH_CODES.has(err.code) || err.status === 401)
             return EXIT.auth;

package/dist/format.d.ts

@@ -3,7 +3,7 @@
  * `--json` output is the API's own objects (see README "JSON output"), so
  * these functions only shape what people read.
  */
-import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } from '@shardflux/sdk';
+import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
 export declare function json(value: unknown): string;
 export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;
@@ -28,6 +28,16 @@ export declare function isReady(w: WorkspaceView): boolean;
 export declare function startupText(s: WorkspaceView['startup'] | undefined): string | null;
 /** The failed step's output tail, indented, after the detail block (empty otherwise). */
 export declare function startupTail(s: WorkspaceView['startup'] | undefined): string;
+/** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
+export declare function suspendRequestText(r: SuspendRequest): string;
+/** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
+export declare function suspendWhenIdleText(w: {
+    key: string;
+    id: string;
+}, r: {
+    suspend_request: SuspendRequest | null;
+    operation: Operation | null;
+}): string;
 export declare function workspaceDetail(w: WorkspaceView): string;
 export declare const OPERATION_HEADERS: readonly ["ID", "KIND", "STATE", "REASON", "CREATED", "COMPLETED"];
 export declare function operationTable(ops: readonly Operation[]): string;
@@ -44,9 +54,12 @@ export declare function secretDetail(s: Secret): string;
 export declare function secretVersionTable(rows: readonly SecretVersion[]): string;
 export declare function secretAccessTable(rows: readonly SecretAccessEvent[]): string;
 export declare function bindingsText(b: WorkspaceSecretBindings): string;
+/** Minor units as money (the overage block): `$3.00` for usd, else `3.00 EUR`. A fractional minor amount (a sub-cent rate) keeps its digits. */
+export declare function capMoney(minor: unknown, currency: string): string;
 /**
  * The usage summary (GET /v1/organizations/{id}/usage/summary): plan, period, measurement
- * freshness, then meters and allowances as tables. Columns absent from the response are omitted.
+ * freshness, then meters and allowances as tables (cap state `overage` past an allowance while opt-in overage is on),
+ * then the overage block. Columns absent from the response are omitted.
  */
 export declare function usageText(summary: unknown): string;
 /**
@@ -131,3 +144,8 @@ export declare function attachmentTable(rows: readonly VolumeAttachment[]): stri
 export declare function projectEgressText(p: ProjectEgressPolicy): string;
 export declare function workspaceEgressText(w: WorkspaceEgressPolicy): string;
 export declare function egressVersionTable(rows: readonly EgressPolicyVersion[]): string;
+/**
+ * The spend policy's overage settings for people (GET/PUT /v1/organizations/{id}/spend-policy): the state, the spend
+ * cap and its bounds, the rates, and the next step. `saved` adds the version the change was saved as.
+ */
+export declare function overagePolicyText(p: SpendPolicy, orgName: string, saved?: boolean): string;

package/dist/format.js

@@ -107,9 +107,25 @@ export function startupTail(s) {
     const lines = s.output_tail.replace(/\n$/, '').split('\n');
     return `startup output (last ${Buffer.byteLength(s.output_tail)} bytes):\n${lines.map((l) => `  | ${l}`).join('\n')}\n`;
 }
+/** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
+export function suspendRequestText(r) {
+    return `after ${r.after_seconds} s idle, not before ${time(r.not_before)} (requested ${time(r.requested_at)})`;
+}
+/** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
+export function suspendWhenIdleText(w, r) {
+    if (r.suspend_request) {
+        const s = r.suspend_request;
+        return (`Suspend when idle: ${w.key} (${w.id}) is suspended once it has been idle for ${s.after_seconds} s, not before ${time(s.not_before)}.\n` +
+            'A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.\n' +
+            `cancel with: shard workspaces suspend ${w.key} --cancel-when-idle\n`);
+    }
+    const op = r.operation;
+    return `A suspend of ${w.key} (${w.id}) is already in progress (operation ${op.id} ${op.kind} ${op.state}); nothing was scheduled.\nwait with: shard operations wait ${op.id}\n`;
+}
 export function workspaceDetail(w) {
     const c = w.ceilings;
     const startup = startupText(w.startup);
+    const suspendRequest = w.idle?.suspend_request;
     return kv([
         ['id', w.id],
         ['key', w.workspace_key],
@@ -125,6 +141,7 @@ export function workspaceDetail(w) {
         ['caps', pairs(w.caps)],
         ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
         ['pending', w.pending_reason ?? '-'],
+        ...(suspendRequest ? [['suspend when idle', suspendRequestText(suspendRequest)]] : []),
         ...(startup ? [['startup', startup]] : []),
         ['forked from', w.forked_from_workspace_id ?? '-'],
         ...(w.lifetime !== undefined
@@ -232,10 +249,66 @@ function objectTable(rows, columns) {
     const cols = columns.filter(([k]) => objs.some((o) => k in o));
     return table(cols.map(([, h]) => h), objs.map((o) => cols.map(([k]) => (k === 'percent_used' && typeof o[k] === 'number' ? `${o[k]}%` : scalar(o[k])))));
 }
-const USAGE_KNOWN = new Set(['plan', 'period', 'measurement', 'allowance_exhausted', 'meters', 'allowances', 'exhausted', 'alert_thresholds']);
+const USAGE_KNOWN = new Set(['plan', 'period', 'measurement', 'allowance_exhausted', 'exhausted_reason', 'egress_override', 'meters', 'allowances', 'exhausted', 'alert_thresholds', 'spend_cap']);
+/** Minor units as money (the overage block): `$3.00` for usd, else `3.00 EUR`. A fractional minor amount (a sub-cent rate) keeps its digits. */
+export function capMoney(minor, currency) {
+    if (typeof minor !== 'number')
+        return '-';
+    const major = minor / 100;
+    const digits = Number.isInteger(minor) ? 2 : Math.min(6, Math.max(2, String(major).split('.')[1]?.length ?? 2));
+    const n = major.toFixed(digits);
+    return currency.toLowerCase() === 'usd' ? `$${n}` : `${n} ${currency.toUpperCase()}`;
+}
+/** What each spend_cap.state means for the reader (API contract: SpendCap.state). */
+const OVERAGE_STATES = {
+    unavailable: 'not available on this plan',
+    off: 'starts are refused once an allowance is used up; an owner or billing member can turn overage on under Usage & billing',
+    paused: 'a plan payment is past due; overage resumes once it is paid',
+    within_allowance: 'on, no usage past the allowances yet',
+    accruing: 'usage past the allowances is charged on the next invoice',
+    warning: '80% or more of the spend cap is used',
+    reached: 'the spend cap is reached: new opens/resumes are refused and running workspaces are suspended',
+};
+/**
+ * The opt-in overage block (0.5.1; `spend_cap` of the summary, SDK 0.10.0): state, cap, charges of the cap, the
+ * projected date the cap is reached, and per allowance the units past it and their amount. Empty without spend_cap
+ * (an API older than overage).
+ */
+function spendCapText(cap) {
+    if (!isObject(cap) || typeof cap.state !== 'string')
+        return '';
+    const cur = typeof cap.currency === 'string' ? cap.currency : 'usd';
+    const rows = [['overage', `${cap.state}${OVERAGE_STATES[cap.state] ? ` (${OVERAGE_STATES[cap.state]})` : ''}`]];
+    if (cap.state === 'unavailable')
+        return kv(rows);
+    const charges = typeof cap.charges_minor === 'number' ? cap.charges_minor : 0;
+    if (cap.state !== 'off') {
+        const plan = typeof cap.max_cap_minor === 'number' ? capMoney(cap.max_cap_minor, cur) : undefined;
+        if (cap.cap_minor === null || cap.cap_minor === undefined)
+            rows.push(['spend cap', `not set: ${capMoney(cap.effective_cap_minor, cur)}${plan ? ' (the plan price)' : ''} applies`]);
+        else if (typeof cap.effective_cap_minor === 'number' && typeof cap.cap_minor === 'number' && cap.effective_cap_minor < cap.cap_minor) {
+            rows.push(['spend cap', `${capMoney(cap.cap_minor, cur)}, lowered to ${capMoney(cap.effective_cap_minor, cur)}${plan ? ' (the plan price)' : ''}`]);
+        }
+        else
+            rows.push(['spend cap', `${capMoney(cap.cap_minor, cur)}${plan ? ` (at most ${plan}, the plan price)` : ''}`]);
+    }
+    if (cap.state !== 'off' || charges > 0) {
+        const percent = typeof cap.percent_of_cap === 'number' ? ` (${cap.percent_of_cap}%)` : '';
+        rows.push(['overage charges', `${capMoney(charges, cur)} of ${capMoney(cap.effective_cap_minor, cur)}${percent}, ${capMoney(cap.remaining_minor, cur)} left; billed on the next invoice`]);
+    }
+    if (typeof cap.projected_reached_at === 'string')
+        rows.push(['cap reached', `${time(cap.projected_reached_at)} (projected at this period's average use)`]);
+    let out = kv(rows);
+    const lines = Array.isArray(cap.lines) ? cap.lines.filter(isObject) : [];
+    if (lines.some((l) => (typeof l.units_over === 'number' && l.units_over > 0) || (typeof l.amount_minor === 'number' && l.amount_minor > 0))) {
+        out += `\n${table(['OVERAGE', 'UNIT', 'PAST ALLOWANCE', 'BILLED', 'RATE', 'AMOUNT'], lines.map((l) => [scalar(l.allowance), scalar(l.unit), scalar(l.units_over), scalar(l.billed_units), capMoney(l.rate_minor, cur), capMoney(l.amount_minor, cur)]))}`;
+    }
+    return out;
+}
 /**
  * The usage summary (GET /v1/organizations/{id}/usage/summary): plan, period, measurement
- * freshness, then meters and allowances as tables. Columns absent from the response are omitted.
+ * freshness, then meters and allowances as tables (cap state `overage` past an allowance while opt-in overage is on),
+ * then the overage block. Columns absent from the response are omitted.
  */
 export function usageText(summary) {
     if (!isObject(summary))
@@ -251,8 +324,10 @@ export function usageText(summary) {
         head.push(['measured through', time(m.measured_through)]);
     if (isObject(s.measurement) && s.measurement.estimate_status !== undefined)
         head.push(['estimate', scalar(s.measurement.estimate_status)]);
-    if (typeof s.allowance_exhausted === 'boolean')
-        head.push(['allowance exhausted', s.allowance_exhausted ? 'yes (new opens/resumes are refused)' : 'no']);
+    if (typeof s.allowance_exhausted === 'boolean') {
+        const reason = typeof s.exhausted_reason === 'string' ? `${s.exhausted_reason}: ` : '';
+        head.push(['allowance exhausted', s.allowance_exhausted ? `yes (${reason}new opens/resumes are refused)` : 'no']);
+    }
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
             head.push([k.replace(/_/g, ' '), scalar(v)]);
@@ -280,6 +355,9 @@ export function usageText(summary) {
     ]);
     if (allowances)
         out += `\n${allowances}`;
+    const overage = spendCapText(s.spend_cap);
+    if (overage)
+        out += `\n${overage}`;
     return out || json(summary);
 }
 /** Request ids and error codes pasted unquoted into the suggested command must be shell-inert. */
@@ -755,3 +833,35 @@ export function workspaceEgressText(w) {
 export function egressVersionTable(rows) {
     return table(['VERSION', 'KIND', 'POLICY', 'BY', 'CREATED'], rows.map((v) => [String(v.version), v.kind, v.kind === 'cleared' ? '-' : egressPolicyLine({ mode: v.mode ?? 'allow_all', rules: v.rules, cidrs: v.cidrs }), `${v.created_by.type}:${v.created_by.id}`, time(v.created_at)]));
 }
+// ---- Overage settings (0.5.1; shard billing overage) -----------------------------------------------------------
+const RATE_UNITS = { ram_gib_hours: 'RAM GiB-hour', cpu_hours: 'CPU-hour' };
+/**
+ * The spend policy's overage settings for people (GET/PUT /v1/organizations/{id}/spend-policy): the state, the spend
+ * cap and its bounds, the rates, and the next step. `saved` adds the version the change was saved as.
+ */
+export function overagePolicyText(p, orgName, saved = false) {
+    const m = (minor) => capMoney(minor, p.currency);
+    const bound = p.spend_cap_max_minor === null ? '' : `${m(p.spend_cap_min_minor)} to ${m(p.spend_cap_max_minor)}, the plan price`;
+    const cap = p.spend_cap_minor === null ? 'no spend cap set' : `spend cap ${m(p.spend_cap_minor)} per billing period`;
+    const lines = [];
+    switch (p.overage_state) {
+        case 'unavailable':
+            lines.push(`${orgName}: overage is not available on this plan: it needs a paid plan with opt-in overage (shard billing plans).`);
+            break;
+        case 'off':
+            lines.push(`${orgName}: overage is off (${cap}): new opens and resumes are refused once an allowance is used up.`);
+            lines.push(`Turn it on${p.spend_cap_minor === null ? ` with a spend cap${bound ? ` of ${bound}` : ''}: shard billing overage on --cap <dollars>` : ': shard billing overage on'}`);
+            break;
+        case 'paused':
+            lines.push(`${orgName}: overage is on but paused while a plan payment is past due (update the payment method: shard billing portal --open); ${cap}.`);
+            break;
+        default:
+            lines.push(`${orgName}: overage is on, ${cap}${bound ? ` (${bound})` : ''}.`);
+    }
+    if (p.overage_state !== 'unavailable' && p.rates.length > 0) {
+        lines.push(`Rates past the allowances: ${p.rates.map((r) => `${m(r.amount_minor_per_unit)} per ${RATE_UNITS[r.allowance] ?? r.unit}`).join(', ')}, charged on the next invoice (this period: shard usage).`);
+    }
+    if (saved)
+        lines.push(`Saved (policy version ${p.version}).`);
+    return `${lines.join('\n')}\n`;
+}

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type { MainOptions, RunOptions } from './main.js';
 export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, HELP_SECTIONS, commandHelp, findCommand, groupHelp, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from './args.js';
 export type { CommandSpec, OptionSpec, Parsed, PositionalSpec, Values } from './args.js';
 export { HANDLERS } from './handlers.js';
-export { KEY_HANDLERS, execExitCode, resolveWorkspace } from './commands.js';
+export { KEY_HANDLERS, execExitCode, resolveWorkspace, whenIdleSeconds } from './commands.js';
 export type { Ctx, Handler, Io, ResolvedApiKey, Writer } from './commands.js';
 export { ACCOUNT_HANDLERS, DEFAULT_API_URL, defaultOrgName, exportLine, parseTime } from './account-commands.js';
 export type { ShellKind } from './account-commands.js';
@@ -21,5 +21,5 @@ export type { Distribution, UpdateView } from './update-check.js';
 export { openUrl, openerFor } from './browser.js';
 export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, ExecutionPendingError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from './errors.js';
 export type { ErrorInfo } from './errors.js';
-export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
+export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
 export { TimingRecorder, timingJson, timingText } from './timing.js';

package/dist/index.js

@@ -6,12 +6,12 @@
 export { run, main, abortableSleep } from "./main.js";
 export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, HELP_SECTIONS, commandHelp, findCommand, groupHelp, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, resolveWake, resolveWakeTimeout, topHelp } from "./args.js";
 export { HANDLERS } from "./handlers.js";
-export { KEY_HANDLERS, execExitCode, resolveWorkspace } from "./commands.js";
+export { KEY_HANDLERS, execExitCode, resolveWorkspace, whenIdleSeconds } from "./commands.js";
 export { ACCOUNT_HANDLERS, DEFAULT_API_URL, defaultOrgName, exportLine, parseTime } from "./account-commands.js";
 export { CREDENTIALS_FILE, CredentialStore, CredentialsFileError, configDir, ensurePrivateDir, parseCredentials, writePrivateFile } from "./credentials.js";
 export { Input } from "./input.js";
 export { CHECK_INTERVAL_MS, CLI_DISTRIBUTION, NOTICE_WAIT_MS, UPDATE_CHECK_FILE, UpdateCheck, noticeOf, statusFromEntry, updateCheckDisabled, updateView } from "./update-check.js";
 export { openUrl, openerFor } from "./browser.js";
 export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, ExecutionPendingError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
-export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
+export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
 export { TimingRecorder, timingJson, timingText } from "./timing.js";

package/dist/main.js

@@ -15,7 +15,7 @@ import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shard
 import { CLI_VERSION, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { CredentialStore, configDir } from "./credentials.js";
 import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
-import { errorText, feedbackCommand, json } from "./format.js";
+import { errorText, feedbackCommand, json, time } from "./format.js";
 import { HANDLERS } from "./handlers.js";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
@@ -74,6 +74,11 @@ function hintFor(info, cred, file) {
         return 'change plans in the billing portal: shard billing portal --open';
     if (info.code === 'dependency_unavailable' && reasonOf(info) === 'billing_disabled')
         return 'this API has no billing configured: plans cannot be bought here';
+    if (info.code === 'allowance_exhausted')
+        return allowanceHint(info);
+    const policyHint = spendPolicyHint(info);
+    if (policyHint)
+        return policyHint;
     // File patches (contracts §26.2): what to do about each refusal. details.index is the 0-based edit (--old) index.
     const reason = info.details?.reason;
     const index = typeof info.details?.index === 'number' ? ` #${info.details.index + 1}` : '';
@@ -91,8 +96,76 @@ function hintFor(info, cred, file) {
         return 'the workspace’s host has no room to run it right now; retry in a few seconds';
     if (reason === 'host_feature_unavailable')
         return hostFeatureHint(info.details?.feature);
+    // A processful command that could not start (0.5.1): what to change, from the workspace's reason.
+    if (info.code === 'conflict' && reason === 'exec_failed_to_start')
+        return startFailureHint(typeof info.details?.error === 'string' ? info.details.error : info.message, false);
     return fileFirstHint(info);
 }
+/**
+ * What to do about a command that could not start (exec_failed_to_start), from the workspace's reason: a working
+ * directory that is not a directory, else a program that is not on PATH. An unknown user needs no more than the reason.
+ */
+function startFailureHint(why, fileFirst) {
+    if (/working directory|chdir|\bcwd\b/i.test(why)) {
+        return fileFirst
+            ? '--cwd must name a directory that exists in the workspace’s files, as an absolute path under /home/user'
+            : '--cwd must name a directory that exists in the workspace, as an absolute path (commands start in /home/user without --cwd)';
+    }
+    if (/unknown user/i.test(why))
+        return undefined;
+    return 'is argv[0] installed and on PATH? shell syntax needs -- bash -lc "..."';
+}
+/**
+ * 402 allowance_exhausted (0.5.1): what to do per details.reason (opt-in overage with a spend cap). An API older than
+ * overage sends no reason: no hint.
+ */
+function allowanceHint(info) {
+    const resets = typeof info.details?.resets_at === 'string' ? ` (the period resets ${time(info.details.resets_at)})` : '';
+    switch (info.details?.reason) {
+        case 'allowance_used':
+            return `upgrade (shard billing plans), or turn on overage: shard billing overage on --cap <dollars>${resets}`;
+        case 'spend_cap_reached':
+            return `the spend cap is reached: raise it (shard billing overage cap <dollars>, at most the plan price) or upgrade${resets}`;
+        case 'overage_paused':
+            return 'a payment is past due: update the payment method (shard billing portal --open); overage resumes once the invoice is paid';
+        default:
+            return undefined;
+    }
+}
+/** Dollars for a hint: `9` for 900 minor units, `9.50` for 950. */
+const dollars = (minor) => (typeof minor === 'number' ? (minor % 100 === 0 ? String(minor / 100) : (minor / 100).toFixed(2)) : undefined);
+/**
+ * The spend-policy refusals (0.5.1; shard billing overage): 422 validation_failed per details.reason, with the bound the
+ * API names (min_minor, max_minor, charges_minor), and a 409 version_mismatch (--if-version, here or on egress set).
+ */
+function spendPolicyHint(info) {
+    const d = info.details ?? {};
+    const reason = reasonOf(info);
+    if (info.code === 'conflict' && reason === 'version_mismatch') {
+        const now = typeof d.current_version === 'number' ? d.current_version : undefined;
+        return `it changed since that version${now === undefined ? '' : ` (it is at version ${now} now)`}; nothing was saved. Look at it again, then retry${now === undefined ? '' : ` with --if-version ${now}`}`;
+    }
+    if (info.code !== 'validation_failed')
+        return undefined;
+    switch (reason) {
+        case 'overage_unavailable':
+            return 'overage needs a paid plan with opt-in overage: shard billing plans, then shard billing upgrade <plan>';
+        case 'spend_cap_required':
+            return 'give a spend cap: shard billing overage on --cap <dollars> (shard billing overage shows the range)';
+        case 'spend_cap_below_minimum':
+            return `the smallest spend cap is $${dollars(d.min_minor) ?? '1'}: shard billing overage cap ${dollars(d.min_minor) ?? '1'}`;
+        case 'spend_cap_above_plan_price': {
+            const max = dollars(d.max_minor);
+            return `the spend cap is at most the plan price${max ? `, $${max}: shard billing overage cap ${max}` : ''}; a higher cap needs a larger plan (shard billing plans)`;
+        }
+        case 'spend_cap_below_charges': {
+            const charged = dollars(d.charges_minor);
+            return `overage already charged ${charged ? `$${charged}` : 'more than that'} this period: set a cap of at least that${charged ? ` (shard billing overage cap ${charged})` : ''}, or turn overage off (shard billing overage off)`;
+        }
+        default:
+            return undefined;
+    }
+}
 /**
  * 409 conflict host_feature_unavailable (contracts §26.7; 0.5.0): the workspace runs on a host agent that predates the
  * call. Not retryable: it lasts until the workspace runs on an upgraded host (minutes to hours), so the hint names
@@ -121,7 +194,8 @@ function fileFirstHint(info) {
     const d = info.details ?? {};
     const reason = d.reason;
     if (info.code === 'execution_failed') {
-        const cause = typeof reason === 'string' ? EXECUTION_CAUSES[reason] : undefined;
+        const startHint = reason === 'exec_failed_to_start' ? startFailureHint(info.message, true) : undefined;
+        const cause = startHint ? `the command could not start (${startHint})` : typeof reason === 'string' ? EXECUTION_CAUSES[reason] : undefined;
         return `${cause ? `${cause}; ` : ''}nothing was published (the tree is unchanged). Running it again needs a new --execution-id (omit it for a fresh one)${info.retryable ? '; a retry may succeed' : ''}.`;
     }
     switch (reason) {
@@ -166,7 +240,9 @@ const FEEDBACK_EMAIL = 'shardflux@heliosone.fi';
  * or step-up to finish, a wait that gave up while the work continues, a checkout nobody paid, and the refusals whose
  * hint names the exact next step (a stale revision, an edit that does not match, a mode the workspace lacks).
  */
-const NO_NUDGE_CODES = new Set(['usage', 'interrupted', 'unauthenticated', 'validation_failed', 'mfa_required', 'step_up_required', 'email_unverified', 'timeout', 'checkout_ended']);
+// allowance_exhausted (0.5.1): a used-up allowance, a reached spend cap or a paused overage is a billing state whose hint
+// names the next step (upgrade, overage, the cap, the payment method), not a problem to report.
+const NO_NUDGE_CODES = new Set(['usage', 'interrupted', 'unauthenticated', 'validation_failed', 'mfa_required', 'step_up_required', 'email_unverified', 'timeout', 'checkout_ended', 'allowance_exhausted']);
 const NO_NUDGE_REASONS = new Set([
     'revision_mismatch',
     'tree_revision_mismatch',
@@ -182,6 +258,8 @@ const NO_NUDGE_REASONS = new Set([
     'layout_unsupported',
     'host_feature_unavailable',
     'subscription_exists',
+    // A stale spend policy (If-Match): the hint names the version to retry with (0.5.1).
+    'version_mismatch',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.9.0"
+    "@shardflux/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",