@shardflux/sdk 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,64 @@
 Every API the README shows is available from the version named here. Below 1.0, a minor release may break
 compatibility; breaking changes are marked **Breaking**.
 
+## 0.10.0 (not yet published; npm `latest` is 0.9.0)
+
+### A command that could not start rejects exec.run() (ExecStartError)
+
+A minor release for one runtime change. Production (2026-09-29): `shard ws exec <key> --cwd app -- ls` exited 1 and
+printed nothing, because the session ended `failed_to_start` and `exec.run()` dropped its reason.
+
+- **Breaking:** `cell.exec.run()` rejects with the new `ExecStartError` when the command could not start (a `cwd` that
+  is not a directory, a program not on `PATH`, an unknown user). It was resolving with `exitCode: null`, empty output
+  and the reason only in `session.error`. `ExecStartError` extends `ShardfluxApiError` as a 409 `conflict` with
+  `reason` `exec_failed_to_start` (as a file-first execution that could not start reports it), `details.session_id`,
+  `details.error`, `sessionId` and `session`; its message is `The command could not start: <the workspace's reason>`,
+  e.g. `working directory "/home/user/app" is not a directory`. Also when a start answered `starting` ends that way.
+- The `exec` agent tool (processful) returns `error: { code, message, reason }` with `exit_code: null` for such a
+  command, as the file-first `exec` tool does for a failed execution, instead of an empty result. Tool definitions
+  are unchanged.
+- The cell API now refuses a relative `cwd` on exec, execution and PTY starts with 422 `validation_failed`,
+  `details.reason` `invalid_cwd`, `details.field` `cwd` (for every SDK version); the message names the absolute path
+  it likely means, e.g. `use "/home/user/app"`. `KnownErrorReason` adds `invalid_cwd`; `RunOptions.cwd` and the cell
+  types (regenerated) document it.
+
+### Opt-in overage with a spend cap
+
+Additive: an API without overage sends no `spend_cap` and no `reason`. The usage reads change types only (regenerated
+from the API's OpenAPI); the account client's `setSpendPolicy()` gains the overage fields.
+
+- Opt-in overage: `usage.summary()`, `spend()` and `estimate()` report `spend_cap` (new type `SpendCap`: `state`
+  `unavailable` | `off` | `paused` | `within_allowance` | `accruing` | `warning` | `reached`, `cap_minor`,
+  `effective_cap_minor`, `max_cap_minor`, `charges_minor`, `remaining_minor`, `percent_of_cap`, `currency`,
+  `resets_at`, `lines` per allowance with `units_over`, `billed_units`, `rate_minor`, `amount_minor`, and
+  `projected_reached_at`). Allowances past `included` while overage is on have `cap_state: 'overage'`; `summary()`
+  and `spend()` add `exhausted_reason`, and `spend.usage_charges_minor` and the estimate's charges are real amounts.
+- `usage.spendPolicy()` and `ShardfluxAccount.billing.spendPolicy()` return the overage settings:
+  `overage_available`, `overage_enabled`, `overage_state` (`unavailable` | `off` | `on` | `paused`),
+  `spend_cap_minor`, `spend_cap_min_minor`, `spend_cap_max_minor`, `rates`, `currency` and `version`.
+- `ShardfluxAccount.billing.setSpendPolicy(orgId, update)` (owners and billing members, with a user session; an API
+  key gets 403) takes `overageEnabled` and `spendCapMinor` besides `alertThresholdsPercent`, all optional (at least
+  one; an empty update throws before any request), and `ifMatch` (the `version` read, or `'*'`), sent as If-Match. New
+  type `SpendPolicyUpdate`. Runtime change: the body carries only the fields given.
+- 402 `allowance_exhausted` carries `details.reason` (`allowance_used`, `overage_paused`, `spend_cap_reached`; also
+  `err.reason`) and `details.spend_cap` (`cap_minor`, `effective_cap_minor`, `charges_minor`, `currency`).
+  `KnownErrorReason` adds them, the spend-policy refusals (422 `overage_unavailable`, `spend_cap_required`,
+  `spend_cap_below_minimum`, `spend_cap_above_plan_price`, `spend_cap_below_charges`) and 409 `version_mismatch`.
+
+### Suspend when idle (contracts §20.6)
+
+- `workspace.suspendWhenIdle({ afterSeconds, idempotencyKey? })` and `cloud.workspaces.suspendWhenIdle(id, {
+  afterSeconds })` (POST /v1/workspaces/{id}/suspend-when-idle): the workspace is suspended once it has been idle for
+  `afterSeconds` (30..3600), counted from the later of its last work and the request. Meant 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.
+  Resolves with `{ suspendRequest, operation, workspace }`: `operation` is the suspend already in progress, if any
+  (then nothing is recorded).
+- `workspace.cancelSuspendWhenIdle()` and `cloud.workspaces.cancelSuspendWhenIdle(id)` (DELETE, idempotent).
+- `workspace.suspendRequest`: the pending request from the view's `idle.suspend_request`, or null.
+- Tool-call capture writes recorded before `suspendWhenIdle` land first, as for `suspend`, since a later write would
+  count as the next turn and cancel the request.
+- Types `SuspendRequest`, `SuspendWhenIdleOptions`, `SuspendWhenIdleResult`, `SuspendWhenIdleResponse`.
+
 ## 0.9.0 (not yet published; npm `latest` is 0.8.0)
 
 Elastic compute (decision 0007): file tools and wake hints for parked workspaces. Additive; older APIs and cell
@@ -202,6 +260,7 @@ behavior is the automatic version check (below), which makes one background requ
 - New exports: `FeedbackCategory`, `FeedbackContext`, `FeedbackReceipt`, `SendFeedbackParams`, `AccountFeedbackParams`,
   `FEEDBACK_CATEGORIES`, `FEEDBACK_MESSAGE_MAX_LENGTH`.
 
+
 ## 0.8.0 (2026-09-28)
 
 Types only; nothing changes at run time and the API is unchanged.

package/README.md

@@ -10,7 +10,7 @@ tool calls into the workspace ([tool-call capture](#tool-call-capture-070)).
 > **Early access.** Shardflux is in early access. The API is versioned (`/v1`), but this SDK is
 > below 1.0: a minor release may contain breaking changes (see [Compatibility](#compatibility)).
 
-> **Versions.** This README describes 0.9.0. Anything marked **(0.9.0+)** is not in 0.8.x, **(0.8.0+)** not in 0.7.x,
+> **Versions.** This README describes 0.10.0. Anything marked **(0.10.0+)** is not in 0.9.0, **(0.9.0+)** not in 0.8.x, **(0.8.0+)** not in 0.7.x,
 > **(0.7.0+)** not in 0.6.x and **(0.6.0+)** not in 0.5.0; [CHANGELOG.md](./CHANGELOG.md) lists what each version added. Check yours with
 > `npm ls @shardflux/sdk` or the exported `SDK_VERSION`.
 
@@ -101,6 +101,23 @@ await cell.files.remove('/home/user/data.bin');
 twice. Aborting its `signal` also cancels the command in the workspace. File writes are atomic
 and durable (acknowledged after fsync).
 
+`cwd` is an absolute path (commands start in `/home/user` without one). The API refuses a relative
+`cwd` with 422 `validation_failed` (`err.reason === 'invalid_cwd'`); the message names the absolute
+path it likely means. A command that could not start (a `cwd` that is not a directory, a program
+that is not on `PATH`) rejects with `ExecStartError` **(0.10.0+)**, whose message is the workspace's
+reason; before 0.10.0 `exec.run()` resolved with `exitCode: null` and no output.
+
+```ts
+import { ExecStartError } from '@shardflux/sdk';
+
+try {
+  await cell.exec.run(['ls'], { cwd: '/home/user/app' });
+} catch (err) {
+  if (!(err instanceof ExecStartError)) throw err;
+  console.error(err.message); // The command could not start: working directory "/home/user/app" is not a directory
+}
+```
+
 ### Search, patch and revisions (0.9.0+)
 
 ```ts
@@ -194,6 +211,29 @@ try {
 }
 ```
 
+### Suspend when idle (0.10.0+)
+
+A running workspace is billed while it is awake, and its idle policy waits a while before suspending it. When your
+agent's turn ends, ask for a suspend once the workspace has been idle for a short time instead:
+
+```ts
+const { suspendRequest } = await workspace.suspendWhenIdle({ afterSeconds: 60 }); // 30..3600
+workspace.suspendRequest;               // { requested_at, after_seconds, not_before } until it applies or is cancelled
+await workspace.cancelSuspendWhenIdle(); // idempotent
+```
+
+- The idle time counts from the later of the workspace's last work and the request; `not_before` is the earliest
+  suspend.
+- A command still running, an attached exec or terminal stream, or a keepalive postpones the suspend until
+  `afterSeconds` after it ends.
+- The next tool call on the workspace (the next turn) or a resume cancels the request. Repeating replaces it.
+- It applies under every idle policy, `never` included, and never delays a suspend the policy would do sooner.
+- When a suspend is already in progress, the result's `operation` is that suspend and nothing is recorded.
+- Errors: `ShardfluxApiError` 409 with `reason` `not_running`, `operation_in_progress`, `session_lifetime` or
+  `workspace_deleted`, and 422 `validation_failed` for `afterSeconds` outside 30..3600. A file-first workspace is never
+  suspended: `NotSupportedForModeError` (409 `not_supported_for_mode`).
+- By id: `cloud.workspaces.suspendWhenIdle(id, { afterSeconds })` and `cloud.workspaces.cancelSuspendWhenIdle(id)`.
+
 **Suspended workspaces wake on use.** A tool call on a suspended workspace resumes it (or joins the resume or open
 already running), then runs. A call made during a suspend or resume waits for the transition to finish. The call
 never runs twice: the cell executes nothing it refused.
@@ -589,7 +629,7 @@ never injected).
 
 **Read-your-writes.** Calls through the same client first wait for capture writes recorded before them (bounded by
 `settleTimeoutMs`, 30 s; they never fail because of capture): `exec` and files calls through `workspace.cell()`,
-`workspaceTools`, `snapshot`, `fork`, `suspend`, `saveAsTemplate` and `close` (on the workspace handle and on
+`workspaceTools`, `snapshot`, `fork`, `suspend`, `suspendWhenIdle` (0.10.0+), `saveAsTemplate` and `close` (on the workspace handle and on
 `cloud.workspaces.*(id)`). A lifecycle call's timing shows the wait as a `capture_flush` phase. `delete` and `reset`
 drop pending writes. A write to a suspended workspace wakes it (`wake: null` opts out).
 
@@ -703,6 +743,26 @@ if (!done.subscription_active) console.log(`checkout ${done.status}`);
 // After timeoutMs: CheckoutTimeoutError (err.checkout is the last status); on abort: the signal's reason.
 ```
 
+Opt-in overage and its spend cap (owners and billing members): read the policy, then change it. Every field is
+optional (give at least one); `ifMatch` (the `version` you read) makes a concurrent change a 409 `version_mismatch`
+instead of overwriting it.
+
+```ts
+const policy = await account.billing.spendPolicy(org.id);
+// overage_state: unavailable | off | on | paused; the cap range: spend_cap_min_minor..spend_cap_max_minor (the plan price)
+if (policy.overage_available) {
+  await account.billing.setSpendPolicy(org.id, { overageEnabled: true, spendCapMinor: 900, ifMatch: policy.version }); // $9.00
+}
+await account.billing.setSpendPolicy(org.id, { overageEnabled: false });           // always allowed
+await account.billing.setSpendPolicy(org.id, { alertThresholdsPercent: [50, 80, 100] });
+```
+
+A refused change is a `ShardfluxApiError` 422 `validation_failed` with `reason` `overage_unavailable`,
+`spend_cap_required`, `spend_cap_below_minimum` (`details.min_minor`), `spend_cap_above_plan_price`
+(`details.max_minor`) or `spend_cap_below_charges` (`details.charges_minor`: the cap cannot go below what overage
+already charged this period). Every owner and billing member gets an email when overage is turned on or off or the cap
+changes.
+
 ## Errors
 
 - `ShardfluxApiError`: the API or the workspace refused the request. Fields: `status`, `code`,
@@ -724,6 +784,18 @@ if (!done.subscription_active) console.log(`checkout ${done.status}`);
 
 Treat unknown error codes and reasons as generic errors: show `message`, and use `retryable`.
 
+A 402 `allowance_exhausted` (opens, resumes and forks refused while a CPU-hours or RAM GiB-hours allowance is used up)
+carries `reason` **(0.9.0+)**:
+
+| `reason` | Meaning | What to do |
+| --- | --- | --- |
+| `allowance_used` | The allowance is used up and overage is off or not on the plan. | Upgrade, or have an owner or billing member turn on overage under Usage & billing; or wait for `details.resets_at`. |
+| `overage_paused` | Overage is on but paused while a plan payment is past due. | An owner or billing member updates the payment method. |
+| `spend_cap_reached` | Overage charges reached the spend cap for this billing period. | Raise the cap (up to the plan price) or upgrade under Usage & billing; or wait for `details.resets_at`. |
+
+`details.spend_cap` is `{ cap_minor, effective_cap_minor, charges_minor, currency }` (minor units, `null` when the plan
+has no overage). An older API sends no `reason`. Do not retry these in a loop.
+
 Retryable 429/502/503/504 refusals (for example 503 `host_capacity`, when the workspace's host has no room to restore
 it right now, or `wake_failed`) are retried after `Retry-After` for reads, searches and calls that carry an
 Idempotency-Key (writes and patches); other calls surface them with `retryable: true` and `retryAfterSeconds`.
@@ -733,6 +805,36 @@ A read of a sleeping workspace that its disk cannot answer (409 `workspace_not_r
 `host_feature_unavailable` (the workspace's host predates the call, `details.feature`) is neither retried nor
 woken: it lasts until the workspace runs on an upgraded host.
 
+## Usage and overage
+
+`cloud.usage` reads the organization's usage (API keys see organization totals and their own project's workspaces):
+`summary(orgId)`, `series(orgId, params)`, `workspace(workspaceId, params)`, `estimate(orgId)`, `grants(orgId)`,
+`spend(orgId)` and `spendPolicy(orgId)`.
+
+```ts
+const s = await cloud.usage.summary(orgId);
+if (s.allowance_exhausted) console.log('starts are refused:', s.exhausted_reason); // allowance_used | overage_paused | spend_cap_reached
+const cap = s.spend_cap; // opt-in overage this period (0.10.0+)
+const usd = (minor: number) => `$${(minor / 100).toFixed(2)}`; // amounts are minor units of cap.currency
+if (cap.state === 'accruing' || cap.state === 'warning') {
+  console.log(`overage ${usd(cap.charges_minor)} of ${usd(cap.effective_cap_minor)}; cap reached ${cap.projected_reached_at ?? 'not this period'}`);
+}
+```
+
+Opt-in overage **(0.10.0+)**: while an owner or billing member has turned it on, workspaces keep opening and running
+past the CPU-hours and RAM GiB-hours allowances (those allowances show `cap_state: 'overage'`), and the usage past them
+is charged on the next invoice until the charges reach the spend cap.
+
+- `summary()`, `spend()` and `estimate()` carry `spend_cap` (type `SpendCap`): `state` (`unavailable`, `off`,
+  `paused`, `within_allowance`, `accruing`, `warning`, `reached`), `cap_minor`, `effective_cap_minor`,
+  `charges_minor`, `remaining_minor`, `percent_of_cap`, `currency`, `resets_at`, `lines` (per allowance: `units_over`,
+  `billed_units`, `rate_minor`, `amount_minor`) and `projected_reached_at`. `summary()` and `spend()` also carry
+  `exhausted_reason`.
+- `spendPolicy()` returns the settings: `overage_available`, `overage_enabled`, `overage_state` (`unavailable`, `off`,
+  `on`, `paused`), `spend_cap_minor`, `spend_cap_min_minor`, `spend_cap_max_minor`, `rates` and `currency`.
+- An API key only reads them. Owners and billing members turn overage on or off and change the cap in the console,
+  or with a user session: `ShardfluxAccount.billing.setSpendPolicy()` (see below).
+
 ## Feedback (0.9.0+)
 
 `cloud.sendFeedback()` sends a message straight to the Shardflux founder, who reads every one. If you or your coding

package/dist/account.d.ts

@@ -320,7 +320,7 @@ export declare class CheckoutTimeoutError extends Error {
 }
 /**
  * Billing with a user session: the catalog and subscription (as for API keys) plus Checkout, the Stripe portal,
- * invoices and usage alert thresholds (owner/billing members).
+ * invoices, usage alert thresholds and opt-in overage with its spend cap (owner/billing members).
  */
 export declare class AccountBillingApi extends BillingApi {
     #private;
@@ -342,12 +342,36 @@ export declare class AccountBillingApi extends BillingApi {
     /** A Stripe customer portal link (plan changes, payment methods, cancellation). */
     portal(organizationId: string): Promise<BillingPortalSession>;
     invoices(organizationId: string, params?: PageParams): Promise<BillingInvoicePage>;
-    /** Usage alert thresholds. */
+    /**
+     * Usage alert thresholds and opt-in overage: `overage_available`, `overage_enabled`, `overage_state` (`unavailable`,
+     * `off`, `on`, `paused`), `spend_cap_minor` with `spend_cap_min_minor` and `spend_cap_max_minor` (the plan price),
+     * `rates`, `currency` and `version` (send it as `ifMatch`).
+     */
     spendPolicy(organizationId: string): Promise<SpendPolicy>;
-    /** Sets the usage alert thresholds (percent of the allowance, 1..100, at most 5; [] turns alerts off). */
-    setSpendPolicy(organizationId: string, params: {
-        alertThresholdsPercent: number[];
-    }): Promise<SpendPolicy>;
+    /**
+     * Changes the spend policy (owner/billing members): alert thresholds and opt-in overage. Every field is optional;
+     * give at least one. The change takes effect at once, and every owner and billing member gets an email when overage
+     * is turned on or off or the cap changes. Refusals: 422 `validation_failed` with `reason` `overage_unavailable`,
+     * `spend_cap_required`, `spend_cap_below_minimum` (`details.min_minor`), `spend_cap_above_plan_price`
+     * (`details.max_minor`) or `spend_cap_below_charges` (`details.charges_minor`); with `ifMatch`, 409 `conflict`
+     * `version_mismatch` (`details.current_version`) when the policy changed since you read it. Nothing changes then.
+     */
+    setSpendPolicy(organizationId: string, params: SpendPolicyUpdate): Promise<SpendPolicy>;
+}
+/** A spend-policy change (`AccountBillingApi.setSpendPolicy`): every field is optional; give at least one. */
+export interface SpendPolicyUpdate {
+    /** Percent of each allowance that sends a usage email (1..100, at most 5); [] turns alerts off. */
+    alertThresholdsPercent?: number[];
+    /** Turns opt-in overage on (needs a spend cap, given here or set before) or off (always allowed; what it charged stays on the next invoice). */
+    overageEnabled?: boolean;
+    /**
+     * The spend cap per billing period in minor units of the plan currency (900 = $9.00): at least
+     * `spend_cap_min_minor`, at most `spend_cap_max_minor` (the plan price), and not below what overage charged this
+     * period.
+     */
+    spendCapMinor?: number;
+    /** The policy `version` you read (sent as If-Match), or '*' for any: a concurrent change answers 409 `version_mismatch`. */
+    ifMatch?: number | '*';
 }
 export declare class AccountExportsApi {
     #private;

package/dist/account.js

@@ -347,7 +347,7 @@ export class CheckoutTimeoutError extends Error {
 }
 /**
  * Billing with a user session: the catalog and subscription (as for API keys) plus Checkout, the Stripe portal,
- * invoices and usage alert thresholds (owner/billing members).
+ * invoices, usage alert thresholds and opt-in overage with its spend cap (owner/billing members).
  */
 export class AccountBillingApi extends BillingApi {
     #core;
@@ -394,13 +394,34 @@ export class AccountBillingApi extends BillingApi {
     invoices(organizationId, params) {
         return json(this.#core, 'GET', `/v1/organizations/${enc(organizationId)}/billing/invoices`, pageQuery(params));
     }
-    /** Usage alert thresholds. */
+    /**
+     * Usage alert thresholds and opt-in overage: `overage_available`, `overage_enabled`, `overage_state` (`unavailable`,
+     * `off`, `on`, `paused`), `spend_cap_minor` with `spend_cap_min_minor` and `spend_cap_max_minor` (the plan price),
+     * `rates`, `currency` and `version` (send it as `ifMatch`).
+     */
     spendPolicy(organizationId) {
         return json(this.#core, 'GET', `/v1/organizations/${enc(organizationId)}/spend-policy`);
     }
-    /** Sets the usage alert thresholds (percent of the allowance, 1..100, at most 5; [] turns alerts off). */
+    /**
+     * Changes the spend policy (owner/billing members): alert thresholds and opt-in overage. Every field is optional;
+     * give at least one. The change takes effect at once, and every owner and billing member gets an email when overage
+     * is turned on or off or the cap changes. Refusals: 422 `validation_failed` with `reason` `overage_unavailable`,
+     * `spend_cap_required`, `spend_cap_below_minimum` (`details.min_minor`), `spend_cap_above_plan_price`
+     * (`details.max_minor`) or `spend_cap_below_charges` (`details.charges_minor`); with `ifMatch`, 409 `conflict`
+     * `version_mismatch` (`details.current_version`) when the policy changed since you read it. Nothing changes then.
+     */
     setSpendPolicy(organizationId, params) {
-        return json(this.#core, 'PUT', `/v1/organizations/${enc(organizationId)}/spend-policy`, { json: { alert_thresholds_percent: params.alertThresholdsPercent } });
+        const body = {};
+        if (params.alertThresholdsPercent !== undefined)
+            body.alert_thresholds_percent = params.alertThresholdsPercent;
+        if (params.overageEnabled !== undefined)
+            body.overage_enabled = params.overageEnabled;
+        if (params.spendCapMinor !== undefined)
+            body.spend_cap_minor = params.spendCapMinor;
+        if (Object.keys(body).length === 0)
+            return Promise.reject(new Error('setSpendPolicy: give at least one of alertThresholdsPercent, overageEnabled, spendCapMinor'));
+        const headers = params.ifMatch === undefined ? {} : { 'if-match': params.ifMatch === '*' ? '*' : `"${params.ifMatch}"` };
+        return json(this.#core, 'PUT', `/v1/organizations/${enc(organizationId)}/spend-policy`, { json: body, headers });
     }
 }
 export class AccountExportsApi {

package/dist/cell.d.ts

@@ -223,6 +223,10 @@ export interface RunResult {
 }
 export interface RunOptions {
     sessionId?: string;
+    /**
+     * Absolute working directory (default the workspace's, /home/user). The API refuses a relative path with 422
+     * `validation_failed`, details.reason `invalid_cwd`; one that is not a directory rejects with ExecStartError.
+     */
     cwd?: string;
     env?: Record<string, string>;
     user?: string;
@@ -297,6 +301,8 @@ export declare class CellClient {
         /**
          * Starts (or re-attaches to) a session and collects its output until it exits, reconnecting
          * with offsets after dropped streams. Never issues a second start for the same session_id.
+         * A command that could not start (a cwd that is not a directory, a program not on PATH, an unknown user) rejects
+         * with ExecStartError (0.10.0+): nothing ran, so there is no exit code to return.
          * A file-first workspace has no sessions: use `executions.run()` (refused locally when the mode is known).
          */
         run: (argv: string[], opts?: RunOptions) => Promise<RunResult>;

package/dist/cell.js

@@ -1,4 +1,4 @@
-import { NotSupportedForModeError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
 import { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 import { HttpClient, defaultSleep, randomId, treeRevisionOf } from "./http.js";
 import { describeFailure, emitTo } from "./progress.js";
@@ -347,6 +347,8 @@ export class CellClient {
         /**
          * Starts (or re-attaches to) a session and collects its output until it exits, reconnecting
          * with offsets after dropped streams. Never issues a second start for the same session_id.
+         * A command that could not start (a cwd that is not a directory, a program not on PATH, an unknown user) rejects
+         * with ExecStartError (0.10.0+): nothing ran, so there is no exit code to return.
          * A file-first workspace has no sessions: use `executions.run()` (refused locally when the mode is known).
          */
         run: async (argv, opts = {}) => {
@@ -369,7 +371,9 @@ export class CellClient {
                 req.kill_grace_ms = opts.killGraceMs;
             if (opts.secretRefs !== undefined)
                 req.secret_refs = opts.secretRefs;
-            await this.exec.start(req, opts.signal);
+            const started = await this.exec.start(req, opts.signal);
+            if (started.state === 'failed_to_start')
+                throw new ExecStartError(started);
             try {
                 return await this.#collect(sessionId, opts);
             }
@@ -453,6 +457,9 @@ export class CellClient {
                 break;
             }
         }
+        // A start answered while the session was still starting can end without starting the command.
+        if (session.state === 'failed_to_start')
+            throw new ExecStartError(session);
         return {
             sessionId,
             exitCode: session.exit_code ?? null,

package/dist/client.d.ts

@@ -94,6 +94,28 @@ export type CheckoutSession = Ok<operations['postApiV1OrganizationsOrganizationI
 export type PortalSession = Ok<operations['postApiV1OrganizationsOrganizationIdBillingPortalSessions']>;
 export type InvoicePage = Ok<operations['getApiV1OrganizationsOrganizationIdBillingInvoices']>;
 export type Invoice = InvoicePage['data'][number];
+/**
+ * A pending suspend-when-idle request (0.10.0; contracts §20.6): once the workspace has been idle for `after_seconds`
+ * (counted from the later of its last work and `requested_at`), it is suspended; `not_before` = requested_at +
+ * after_seconds is the earliest.
+ */
+export type SuspendRequest = components['schemas']['SuspendRequest'];
+/** POST /v1/workspaces/{id}/suspend-when-idle (202). */
+export type SuspendWhenIdleResponse = Ok<operations['postV1WorkspacesWorkspaceIdSuspendWhenIdle']>;
+export interface SuspendWhenIdleOptions {
+    /** Seconds the workspace must stay idle before it is suspended: an integer from 30 to 3600 (the API refuses others with 422 validation_failed). */
+    afterSeconds: number;
+    /** Replays the stored response for a repeated request (default: a fresh key per call, so transport retries replay). */
+    idempotencyKey?: string;
+}
+export interface SuspendWhenIdleResult {
+    /** The recorded request; null when a suspend was already in progress (then `operation` is that suspend). */
+    suspendRequest: SuspendRequest | null;
+    /** The suspend already in progress (nothing was recorded), else null: the suspend itself happens later, from the cell's idle loop. */
+    operation: Operation | null;
+    /** The workspace after the call (on a handle: the handle itself, with its view updated). */
+    workspace: Workspace;
+}
 export interface ShardfluxOptions {
     /** Project API key: sfk_<key_id>_<secret>. */
     apiKey: string;
@@ -324,6 +346,28 @@ export declare class WorkspacesApi {
     snapshot(workspaceId: string, opts?: LifecycleOptions & {
         label?: string;
     }): Promise<Operation>;
+    /**
+     * Suspends the workspace once it has been idle for `afterSeconds` (0.9.0; contracts §20.6): meant for the end of an
+     * agent turn, so the workspace stops using RAM soon after instead of waiting out its idle policy. The idle time
+     * counts from the later of the workspace's last work and this request. A command still running, an attached exec or
+     * terminal stream, or a keepalive postpones the suspend until `afterSeconds` after it ends; a tool call after the
+     * request (the next turn) or a resume cancels it. Repeating replaces the pending request. It applies under every idle
+     * policy (`never` included) and never delays a suspend the policy would do sooner.
+     *
+     * Resolves with the recorded `suspendRequest`, or, when a suspend is already in progress, with that `operation` and
+     * nothing recorded. Tool-call capture writes recorded before the call land first (a later write would count as the
+     * next turn). Errors: ShardfluxApiError 409 with reason `not_running`, `operation_in_progress`, `session_lifetime` or
+     * `workspace_deleted`; 422 `validation_failed` for `afterSeconds` outside 30..3600.
+     *
+     *   await cloud.workspaces.suspendWhenIdle(workspace.id, { afterSeconds: 60 });
+     */
+    suspendWhenIdle(workspaceId: string, opts: SuspendWhenIdleOptions): Promise<SuspendWhenIdleResult>;
+    /**
+     * Cancels a pending suspend-when-idle request (0.10.0; DELETE /v1/workspaces/{id}/suspend-when-idle). Idempotent,
+     * in any workspace state; resolves with the workspace (`suspendRequest` null). A suspend the request already started
+     * is not undone: it is the workspace's `activeOperation` (resume or open the workspace instead).
+     */
+    cancelSuspendWhenIdle(workspaceId: string): Promise<Workspace>;
     /**
      * Ends a session workspace now (contracts §19.11): the workspace is deleted exactly like delete() (ended_reason
      * closed) and returns the `delete` operation (input.reason session_closed); the key then opens a NEW workspace.

package/dist/client.js

@@ -418,6 +418,34 @@ export class WorkspacesApi {
     snapshot(workspaceId, opts = {}) {
         return this.#op('snapshot', workspaceId, opts.label === undefined ? {} : { label: opts.label }, opts);
     }
+    /**
+     * Suspends the workspace once it has been idle for `afterSeconds` (0.9.0; contracts §20.6): meant for the end of an
+     * agent turn, so the workspace stops using RAM soon after instead of waiting out its idle policy. The idle time
+     * counts from the later of the workspace's last work and this request. A command still running, an attached exec or
+     * terminal stream, or a keepalive postpones the suspend until `afterSeconds` after it ends; a tool call after the
+     * request (the next turn) or a resume cancels it. Repeating replaces the pending request. It applies under every idle
+     * policy (`never` included) and never delays a suspend the policy would do sooner.
+     *
+     * Resolves with the recorded `suspendRequest`, or, when a suspend is already in progress, with that `operation` and
+     * nothing recorded. Tool-call capture writes recorded before the call land first (a later write would count as the
+     * next turn). Errors: ShardfluxApiError 409 with reason `not_running`, `operation_in_progress`, `session_lifetime` or
+     * `workspace_deleted`; 422 `validation_failed` for `afterSeconds` outside 30..3600.
+     *
+     *   await cloud.workspaces.suspendWhenIdle(workspace.id, { afterSeconds: 60 });
+     */
+    async suspendWhenIdle(workspaceId, opts) {
+        await this.#ctx().captures.settle(workspaceId);
+        const body = await this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend-when-idle`, { json: { after_seconds: opts.afterSeconds }, idempotencyKey: opts.idempotencyKey ?? randomId('op-') }, this.#auth);
+        return { suspendRequest: body.suspend_request, operation: body.operation, workspace: this.#wrap(body.workspace) };
+    }
+    /**
+     * Cancels a pending suspend-when-idle request (0.10.0; DELETE /v1/workspaces/{id}/suspend-when-idle). Idempotent,
+     * in any workspace state; resolves with the workspace (`suspendRequest` null). A suspend the request already started
+     * is not undone: it is the workspace's `activeOperation` (resume or open the workspace instead).
+     */
+    async cancelSuspendWhenIdle(workspaceId) {
+        return this.#wrap(await this.#http.json('DELETE', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend-when-idle`, {}, this.#auth));
+    }
     async close(workspaceId, opts = {}) {
         return (await this.closeWithView(workspaceId, opts)).operation;
     }

package/dist/errors.d.ts

@@ -38,8 +38,21 @@ export type ErrorCode = AppErrorCode | CellErrorCode;
  * service_unavailable no_execution_host (retryable, Retry-After). An execution that ended `failed` or `lost` names its
  * cause in `error.details.reason`: lease_expired, host_unreachable, host_restarted, tree_moved, blob_missing,
  * blob_corrupt, exec_failed_to_start, among others.
+ * Working directories (0.10.0): 422 validation_failed invalid_cwd (details.field `cwd`): an exec, execution or PTY start
+ * named a relative cwd, which is refused rather than resolved (the message names the absolute path it likely means);
+ * a processful command that could not start rejects `exec.run()` with ExecStartError (409 conflict
+ * exec_failed_to_start).
+ * Opt-in overage with a spend cap (0.10.0): 402 allowance_exhausted on opens, resumes and forks carries details.reason
+ * allowance_used (a CPU-hours or RAM GiB-hours allowance is used up and overage is off or not on the plan),
+ * overage_paused (overage is on but paused while a plan payment is past due) or spend_cap_reached (overage charges
+ * reached the spend cap), plus details.spend_cap {cap_minor, effective_cap_minor, charges_minor, currency}; an API
+ * older than overage sends no reason. Changing overage is for owners and billing members (the console, or a user
+ * session: ShardfluxAccount.billing.setSpendPolicy; an API key gets 403), whose 422 validation_failed reasons are
+ * overage_unavailable, spend_cap_required, spend_cap_below_minimum (details.min_minor), spend_cap_above_plan_price
+ * (details.max_minor) and spend_cap_below_charges (details.charges_minor); with `ifMatch`, 409 conflict
+ * version_mismatch (details.current_version), as egress puts with `ifMatch` answer too.
  */
-export type KnownErrorReason = 'invalid_recipe' | 'base_not_layered' | 'language_unavailable' | 'language_conflict' | 'invalid_package' | 'too_many_files' | 'platform_owned_path' | 'upload_required' | 'upload_missing' | 'upload_digest_mismatch' | 'upload_too_large' | 'extra_hosts_without_auto' | 'invalid_settings' | 'services_unsupported' | 'input_required' | 'input_unknown' | 'input_invalid' | 'egress_widening' | 'reserved_session_id' | 'env_collision' | 'reserved_template_slug' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'update_policy_not_available' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start';
+export type KnownErrorReason = 'invalid_recipe' | 'base_not_layered' | 'language_unavailable' | 'language_conflict' | 'invalid_package' | 'too_many_files' | 'platform_owned_path' | 'upload_required' | 'upload_missing' | 'upload_digest_mismatch' | 'upload_too_large' | 'extra_hosts_without_auto' | 'invalid_settings' | 'services_unsupported' | 'input_required' | 'input_unknown' | 'input_invalid' | 'egress_widening' | 'reserved_session_id' | 'env_collision' | 'reserved_template_slug' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'update_policy_not_available' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start' | 'invalid_cwd' | 'allowance_used' | 'overage_paused' | 'spend_cap_reached' | 'overage_unavailable' | 'spend_cap_required' | 'spend_cap_below_minimum' | 'spend_cap_above_plan_price' | 'spend_cap_below_charges' | 'version_mismatch';
 /** A known reason, or any other string the server sends (reasons are open-ended). */
 export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {
@@ -104,6 +117,21 @@ export declare class TreeRevisionMismatchError extends ShardfluxApiError {
     readonly currentTreeRevision: number | null;
     constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number);
 }
+type ExecSession = CellComponents['schemas']['ExecSession'];
+/**
+ * A command that could not start (0.10.0+): its working directory is not a directory, its program is not on PATH, or
+ * its user does not exist. Nothing ran, so there is no exit code and no output. `exec.run()` rejects with it when the
+ * session ends `failed_to_start` (before 0.10.0 it resolved with `exitCode: null` and empty output). It is a 409
+ * `conflict` with details.reason `exec_failed_to_start`, as a file-first execution that could not start reports it;
+ * the message carries the workspace's own words, e.g. `working directory "/home/user/app" is not a directory`.
+ */
+export declare class ExecStartError extends ShardfluxApiError {
+    /** The exec session that could not start. */
+    readonly sessionId: string;
+    /** The session as the cell reported it (state `failed_to_start`, `error`). */
+    readonly session: ExecSession;
+    constructor(session: ExecSession);
+}
 /**
  * Builds the error for an error body, typed by its reason: NotSupportedForModeError for `not_supported_for_mode`,
  * TreeRevisionMismatchError for `tree_revision_mismatch`, else ShardfluxApiError. Every SDK request builds its errors

package/dist/errors.js

@@ -83,6 +83,34 @@ export class TreeRevisionMismatchError extends ShardfluxApiError {
         this.currentTreeRevision = typeof cur === 'number' && Number.isSafeInteger(cur) ? cur : (treeRevision ?? null);
     }
 }
+/**
+ * A command that could not start (0.10.0+): its working directory is not a directory, its program is not on PATH, or
+ * its user does not exist. Nothing ran, so there is no exit code and no output. `exec.run()` rejects with it when the
+ * session ends `failed_to_start` (before 0.10.0 it resolved with `exitCode: null` and empty output). It is a 409
+ * `conflict` with details.reason `exec_failed_to_start`, as a file-first execution that could not start reports it;
+ * the message carries the workspace's own words, e.g. `working directory "/home/user/app" is not a directory`.
+ */
+export class ExecStartError extends ShardfluxApiError {
+    /** The exec session that could not start. */
+    sessionId;
+    /** The session as the cell reported it (state `failed_to_start`, `error`). */
+    session;
+    constructor(session) {
+        const why = session.error ?? 'the workspace gave no reason';
+        super(409, {
+            error: {
+                code: 'conflict',
+                message: `The command could not start: ${why}`,
+                request_id: '',
+                retryable: false,
+                details: { reason: 'exec_failed_to_start', session_id: session.session_id, ...(session.error ? { error: session.error } : {}) },
+            },
+        }, 'cell');
+        this.name = 'ExecStartError';
+        this.sessionId = session.session_id;
+        this.session = session;
+    }
+}
 /**
  * Builds the error for an error body, typed by its reason: NotSupportedForModeError for `not_supported_for_mode`,
  * TreeRevisionMismatchError for `tree_revision_mismatch`, else ShardfluxApiError. Every SDK request builds its errors