@shardflux/cli 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -3,7 +3,25 @@
 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.3.0 (unreleased)
+## 0.3.1 (not yet published; npm `latest` is 0.3.0)
+
+Needs `@shardflux/sdk` 0.6.2 or later.
+
+The API no longer lets a start (open, resume, fork) wait in `capacity_pending` forever: one that no host could admit
+15 minutes after it began fails with `capacity_unavailable` (retryable; nothing was started, a suspended workspace
+stays suspended).
+
+- A failed operation's error has `retryable` (the operation error's own flag): `retryable=true|false` in the error line,
+  `"retryable"` in the `--json` error document, next to `details.error_code`. `details.reason` carries the operation
+  error's reason (for `capacity_unavailable`, why no host fit, e.g. `no_ready_hosts`), printed after the message.
+- A retryable failure gets a hint to retry later. Exit codes are unchanged (6 for any failed operation); `shard` does
+  not retry.
+- A `--timeout` that ends while the start waits for capacity names the time it gives up (the SDK's message).
+- Help and README: `--timeout` and exit codes 5 and 6 describe the 15-minute limit.
+- `shard workspaces get` names the origin of a template version test instance (`template <id> version <n>`, contracts
+  §24.6) instead of reading it as a draft state.
+
+## 0.3.0 (2026-09-28)
 
 Needs `@shardflux/sdk` 0.6.0 or later.
 

package/README.md

@@ -106,6 +106,21 @@ never runs twice, because the workspace refused it before doing anything.
   is still queued after 120000 ms`). The operation continues server side:
   `shard operations wait <id>` keeps waiting.
 - A resume or open that fails exits 6.
+
+## Starts that wait for capacity
+
+An open, resume or fork that no host can admit yet waits in `capacity_pending` for at most 15
+minutes. If `--timeout` ends first, the timeout error names the time it gives up. A start still
+pending then fails with `capacity_unavailable`: nothing was started, and a suspended
+workspace stays suspended. `shard` exits 6 as for any failed operation, and the error says
+`retryable=true` (with `--json`, `"retryable": true`) with a hint to retry later:
+
+```text
+error: Operation 01a0df37-b3a9-7a14-a3e7-11395c349c39 (open) failed: capacity_unavailable (no_ready_hosts) [code=operation_failed operation_id=01a0df37-b3a9-7a14-a3e7-11395c349c39 retryable=true]
+hint: no host could admit it before its deadline; nothing was started. Retry later.
+```
+
+`shard` does not retry it for you. A definitive failure has `retryable=false`.
 - `--no-wake` (or `SHARDFLUX_NO_WAKE=1`) turns this off. A workspace that is not running is then
   refused at once (exit 1, `workspace_not_running`).
 
@@ -179,7 +194,7 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 
 - **Human (default):** aligned tables and key/value blocks on stdout. Errors go to stderr as
   `error: <message> (<reason>) [code=... status=... request_id=... operation_id=...]`, with a
-  hint when there is one.
+  hint when there is one. A failed operation adds `retryable=true|false` (0.3.1+).
 - **`--json`:** stdout carries the API's own objects:
   - `workspaces open`/`get` print the workspace view; `list` prints `{data, next_cursor}`.
   - Lifecycle commands print the operation; `fork` prints `{operation, workspace}`.
@@ -190,7 +205,9 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
     print `{data, next_cursor}`; `rotate` prints `{secret, version}`; `delete` prints
     `{deleted, id, name, scope}`; `workspaces secrets` prints `{workspace_id, names, secrets}`.
 
-  Errors go to stderr as `{"error": {code, message, status, request_id, ...}}`.
+  Errors go to stderr as `{"error": {code, message, status, request_id, ...}}`. A failed operation is
+  `{"error": {"code": "operation_failed", "message", "operation_id", "retryable", "details": {"error_code",
+  "reason"}, "operation"}}`; `retryable` (0.3.1+) is the operation error's own flag.
 - **`--timing`:** the timing goes to stderr after the output. With `--json` it is a `timing` field instead
   (see "Timing").
 
@@ -203,8 +220,8 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
 | 2 | usage error: bad arguments, or input the API rejected as `validation_failed` |
 | 3 | not found: workspace, operation or route |
 | 4 | authentication or authorization: missing, malformed, revoked or insufficient key |
-| 5 | timeout: waiting gave up (`--timeout`, or `--wake-timeout` while waking a workspace); the operation continues server side (`shard operations wait <id>`) |
-| 6 | the awaited operation ended `failed` or `canceled` (also a resume or open that failed while waking a workspace) |
+| 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 |
+| 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`) |
 | 130 | interrupted (Ctrl-C). Waits stop at once, and exec sends a cancel to the session. |
 | exec | 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/args.d.ts

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

package/dist/args.js

@@ -10,7 +10,7 @@
  */
 import { parseArgs } from 'node:util';
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.3.0';
+export const CLI_VERSION = '0.3.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).' },
@@ -38,7 +38,7 @@ const WAKE_TIMING = {
 };
 const WAIT = {
     wait: { type: 'boolean', description: 'Wait until the operation finishes.' },
-    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side.' },
+    timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (e.g. 90s, 5m; default 5m). The operation continues server side (a start waiting for capacity until its deadline, 15 minutes after it began; then it fails with capacity_unavailable).' },
     ...TIMING,
 };
 const REF = { name: 'id|key', required: true };
@@ -111,7 +111,7 @@ export const COMMANDS = [
             },
             ...CAPS,
             wait: { type: 'boolean', description: 'Wait until ready (default; --no-wait returns at once).' },
-            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side.' },
+            timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m). The start continues server side; one waiting for capacity gives up 15 minutes after it began (capacity_unavailable, retryable).' },
             ...TIMING,
         },
         examples: [
@@ -691,7 +691,7 @@ export const EXIT_CODE_HELP = [
     '  3    not found (workspace, operation or route)',
     '  4    authentication/authorization (missing, malformed, revoked or insufficient key)',
     '  5    timeout (waiting gave up; the operation continues server side)',
-    '  6    operation failed or canceled',
+    '  6    operation failed or canceled (retryable=true in the error: it may succeed later, e.g. capacity_unavailable)',
     '  130  interrupted (Ctrl-C)',
     '  exec: the command’s own exit code (124 if it timed out, 128+N if killed by signal N)',
 ];

package/dist/errors.d.ts

@@ -10,7 +10,7 @@ export declare const EXIT: {
     readonly auth: 4;
     /** Waiting ran out of time (the operation continues server side), or a request timed out. */
     readonly timeout: 5;
-    /** The awaited operation ended `failed` or `canceled`. */
+    /** The awaited operation ended `failed` or `canceled` (the error's `retryable` says whether a retry may succeed). */
     readonly operationFailed: 6;
     /** SIGINT (Ctrl-C). */
     readonly interrupted: 130;

package/dist/errors.js

@@ -16,7 +16,7 @@ export const EXIT = {
     auth: 4,
     /** Waiting ran out of time (the operation continues server side), or a request timed out. */
     timeout: 5,
-    /** The awaited operation ended `failed` or `canceled`. */
+    /** The awaited operation ended `failed` or `canceled` (the error's `retryable` says whether a retry may succeed). */
     operationFailed: 6,
     /** SIGINT (Ctrl-C). */
     interrupted: 130,
@@ -69,7 +69,12 @@ export function describeError(err) {
     if (err instanceof OperationTimeoutError)
         return { code: 'timeout', message: err.message, operation_id: err.operationId, last_state: err.lastState };
     if (err instanceof OperationFailedError) {
-        return { code: 'operation_failed', message: err.message, operation_id: err.operationId, ...(err.errorCode ? { details: { error_code: err.errorCode } } : {}), operation: err.operation };
+        // retryable: the operation error's own flag (true for capacity_unavailable: nothing was started, retry later).
+        // details.reason: the operation error's reason (e.g. the scheduler's no_ready_hosts), printed after the message.
+        const opDetails = err.operation.error?.details;
+        const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
+        const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
+        return { code: 'operation_failed', message: err.message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };
     }
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };

package/dist/format.d.ts

@@ -36,7 +36,10 @@ export declare function bindingsText(b: WorkspaceSecretBindings): string;
  * freshness, then meters and allowances as tables. Columns absent from the response are omitted.
  */
 export declare function usageText(summary: unknown): string;
-/** One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. */
+/**
+ * One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. A failed
+ * operation also shows `retryable=true|false`.
+ */
 export declare function errorText(e: ErrorInfo, hint?: string): string;
 export declare function templateTable(rows: readonly TemplateSummary[]): string;
 /** Permission bits as the four-digit octal `ls -l` users read (e.g. 0755). */

package/dist/format.js

@@ -67,6 +67,17 @@ export function workspaceTable(ws) {
 export function isReady(w) {
     return w.observed_state === 'running' && w.desired_state === 'running' && w.deleted_at === null;
 }
+/** A workspace's origin: a fork, a draft state (draft test instance) or a template version (version test instance). */
+function originText(o) {
+    switch (o.kind) {
+        case 'fork':
+            return `fork of ${o.workspace_id}`;
+        case 'draft_state':
+            return `draft state ${o.checkpoint_id ?? '(capturing)'} of ${o.draft_workspace_id}`;
+        default:
+            return `template ${o.template_id} version ${o.version}`;
+    }
+}
 export function workspaceDetail(w) {
     const c = w.ceilings;
     return kv([
@@ -87,7 +98,7 @@ export function workspaceDetail(w) {
                 ['lifetime', w.lifetime === 'session' ? `session (ends after ${w.idle_timeout_seconds ?? '-'} s idle, or on close)` : 'persistent'],
                 ['purpose', w.purpose],
                 ['disk layout', w.disk_layout],
-                ...(w.origin ? [['origin', w.origin.kind === 'fork' ? `fork of ${w.origin.workspace_id}` : `draft state ${w.origin.checkpoint_id ?? '(capturing)'} of ${w.origin.draft_workspace_id}`]] : []),
+                ...(w.origin ? [['origin', originText(w.origin)]] : []),
                 ...(w.ended_reason ? [['ended', w.ended_reason]] : []),
             ]
             : []),
@@ -212,7 +223,10 @@ export function usageText(summary) {
         out += `\n${allowances}`;
     return out || json(summary);
 }
-/** One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. */
+/**
+ * One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. A failed
+ * operation also shows `retryable=true|false`.
+ */
 export function errorText(e, hint) {
     const meta = [`code=${e.code}`];
     if (e.status !== undefined)
@@ -223,6 +237,8 @@ export function errorText(e, hint) {
         meta.push(`operation_id=${e.operation_id}`);
     if (e.source === 'cell')
         meta.push('source=cell');
+    if (e.code === 'operation_failed' && e.retryable !== undefined)
+        meta.push(`retryable=${e.retryable}`);
     const reason = e.details && typeof e.details.reason === 'string' ? ` (${e.details.reason})` : '';
     const issues = Array.isArray(e.details?.issues)
         ? e.details.issues.filter(isObject).map((i) => `  ${scalar(i.path)}: ${scalar(i.message)}\n`).join('')

package/dist/main.js

@@ -31,6 +31,9 @@ export function abortableSleep(signal) {
 function hintFor(info) {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
+    if (info.code === 'operation_failed' && info.retryable) {
+        return info.details?.error_code === 'capacity_unavailable' ? 'no host could admit it before its deadline; nothing was started. Retry later.' : 'the operation may succeed if you retry it later.';
+    }
     if (info.code === 'interrupted' && info.operation_id)
         return `keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'unauthenticated' && info.status === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
   "license": "Apache-2.0",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@shardflux/sdk": "^0.6.1"
+    "@shardflux/sdk": "^0.6.2"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",