@shardflux/cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+Every command and option the README shows is available from the version named here. Below 1.0, a minor release may
+break compatibility; breaking changes are marked **Breaking**.
+
+## 0.3.0 (unreleased)
+
+Needs `@shardflux/sdk` 0.6.0 or later.
+
+### Where the time went: `--timing`
+
+- `--timing` on `workspaces open`, `workspaces suspend|resume|fork|delete|close|reset` (with `--wait`, the whole wait),
+  `operations wait` and `templates draft open|test|state|discard` prints the SDK's lifecycle timing on stderr after
+  the call: the client phases (the request, each operation state seen while waiting with the server's reason, such as
+  `capacity_pending (no_ready_host)`), the operation's own server timing (queued, ran, total; start or resume path),
+  the time spent outside the server, and retries. It is printed when the call fails, times out or is interrupted
+  too, before the error, and the exit code is unchanged.
+- `workspaces exec`, `files read|write|ls` and `workspaces changes` take `--timing` too: it times the wake, when the
+  command had to wake a suspended workspace.
+- With `--json`, the timing is a `timing` field of the JSON on stdout instead (snake_case; `null` when the command
+  made no lifecycle call), and of the error document on stderr (`{"error": {...}, "timing": {...}}`). Existing fields
+  are unchanged.
+
+### Waits are the SDK's
+
+- `workspaces open` waits with the SDK's waited open: the API holds the request until the workspace is ready
+  (`Prefer: wait`, up to 20 s at a time) instead of the CLI polling and then reading the workspace. The ready
+  workspace comes with its first tool token, so the open is listed as an agent session under the CLI's label (as a
+  reopen of a running workspace already was). Output, `--timeout` and exit codes are unchanged.
+- Lifecycle commands with `--wait` use the SDK's `wait`. Output and exit codes are unchanged, except that
+  `workspaces fork --wait` prints the new workspace as it is after the fork, not as it was requested.
+- Ctrl-C ends a held open at once (exit 130); the open continues server side, and opening the key again keeps
+  waiting.
+
+## 0.2.0 (2026-09-28)
+
+Secrets (`secrets ...`, `workspaces open --secret`, `workspaces secrets`), session workspaces (`--lifetime session`,
+`workspaces close`), layered workspaces (`workspaces reset|save-as-template|changes`), templates
+(`templates list|files|diff|draft ...`), and waking suspended workspaces on use (`--no-wake`, `--wake-timeout`).
+
+## 0.1.0 (2026-09-26)
+
+First release: `login`, `whoami`, `usage`, `workspaces open|list|get|exec|suspend|resume|fork|delete|sessions`,
+`files read|write|ls`, `operations list|get|wait`, `--json`, and documented exit codes.

package/README.md

@@ -56,14 +56,14 @@ every run.
 | `login`, `whoami` | Show the principal behind the key. |
 | `version` | Print the CLI and SDK versions. |
 | `usage [--org <id>]` | Usage summary for the current period: plan, meters and allowances. |
-| `workspaces open <key> --template <slug> [--secret NAME]... [--lifetime persistent\|session] [--cpu-millis N --memory-mib N --disk-gib N] [--no-wait] [--timeout 5m]` | Open by key. Creates the workspace on first use and reconnects or resumes it afterwards, never resetting it. Waits until it is ready unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. |
+| `workspaces open <key> --template <slug> [--secret NAME]... [--lifetime persistent\|session] [--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 unless you pass `--no-wait`. `--secret` binds secret names (replacing the binding of an existing workspace). `--lifetime session`: the workspace is discarded when the session ends (`workspaces close` or the idle timeout), and the key then opens a new workspace. |
 | `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. |
 | `workspaces get <id\|key>` | One workspace (deleted ones included). |
 | `workspaces exec <id\|key> [--cwd D] [--env K=V]... [--timeout T] [--stdin F\|-] -- <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. |
 | `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]` | Atomic write. The default source is stdin. |
 | `files ls <id\|key> <path> [--limit N]` | Directory listing. |
-| `workspaces suspend\|resume <id\|key> [--wait] [--timeout T]` | Lifecycle operation. Returns immediately unless you pass `--wait`. |
+| `workspaces suspend\|resume <id\|key> [--wait] [--timeout T] [--timing]` | Lifecycle operation. Returns immediately unless you pass `--wait`. |
 | `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`). |
@@ -77,7 +77,7 @@ every run.
 | `secrets update <id\|NAME> [--description T] [--tool T]... [--allow-workspace ID]... [--any-workspace] [--allow-project ID]... [--all-projects] [--clear-projects]` | Change the description or usage permissions. |
 | `secrets rotate <id\|NAME> [--from-file F]` | Store a new value (standard input or file); older values are erased. |
 | `secrets versions <id\|NAME>`, `secrets delete <id\|NAME> --yes`, `secrets access-log <id\|NAME>` | Versions, deletion (also removes the name from every workspace binding), and the access log. |
-| `operations list <id\|key> [--state S] [--kind K]`, `operations get <op>`, `operations wait <op> [--timeout T]` | Operations. |
+| `operations list <id\|key> [--state S] [--kind K]`, `operations get <op>`, `operations wait <op> [--timeout T] [--timing]` | Operations. |
 | `templates list [--owner platform\|organization] [--include-archived] [--all]` | Templates the project can open, with their open version, layouts, file list state and draft. |
 | `templates files <slug> <version> [path] [--stat] [--owner O] [--all] [--limit N]` | One directory of a version's file tree, or one entry with `--stat`. |
 | `templates diff <slug> --from <version\|base> --to <version> [--prefix P] [--change K] [--all]` | Diff two versions: added, removed, changed, type_changed, metadata. The totals come first. |
@@ -109,6 +109,51 @@ never runs twice, because the workspace refused it before doing anything.
 - `--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`).
 
+## Timing
+
+`--timing` (0.3.0+) says where the time of an open or a wait went. After the call, `shard` prints the lifecycle
+timing that [`@shardflux/sdk`](https://www.npmjs.com/package/@shardflux/sdk) measured (its `formatTiming()`) on
+stderr. It is printed when the call fails, times out or is interrupted too, before the error, and the exit code does
+not change. A slow open reads, for example:
+
+```text
+$ shard ws open acme/demo --template python-node-browser --timing
+Workspace acme/demo (01a0e5a8-3edd-74ba-b489-d62b8925e342) is ready.
+...
+open 34.18 s, succeeded (workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342, operation 01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33)
+  client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 0.59 s → view 42 ms ∥ token 61 ms
+  server: queued 33.40 s, ran 0.62 s, total 34.02 s; start warm, boot to ready 79 ms
+  outside the server: 0.16 s
+```
+
+Here the time went to waiting for a host with capacity; the network and the VM start were fast.
+
+- **client**: phases on your clock. `request` is the API call; `(held)` means the API held it until the workspace
+  was ready, up to 20 s at a time. Then come the operation states seen while waiting, with the server's reason, and
+  reading the workspace.
+- **server**: the operation's own timing. `queued` runs until the operation began running, including any wait for
+  capacity; `ran` is the cell's work. Then the start or resume path the cell reported.
+- **outside the server**: your total minus the operation's, so network, polling and the final reads. A large value
+  with a small server total points at the connection, not at the workspace.
+- **retries**: transient failures that were retried.
+
+Which call is timed:
+
+- `workspaces open` and `templates draft open|test`: the open, including the wait unless `--no-wait`.
+- `workspaces suspend|resume|fork|delete|close|reset` and `templates draft state|discard`: with `--wait`, the request
+  and the whole wait; without it, the request.
+- `operations wait`: the wait.
+- `workspaces exec`, `files read|write|ls` and `workspaces changes`: the wake, when the command had to wake a
+  suspended workspace. Without a wake nothing is printed.
+
+With `--json`, stdout carries the timing as a `timing` field of the command's JSON instead: `action`, `outcome`,
+`workspace_id`, `operation_id`, `total_ms`, `phases` (`phase`, `reason`, `operation_id`, `start_ms`, `duration_ms`),
+`retries`, `server` (`queued_ms`, `run_ms`, `total_ms`, `start_path`, `resume_path`, `boot_to_ready_ms`, ...) and
+`outside_server_ms`. It is `null` when the command made no lifecycle call. On a failure the error document on stderr
+carries it: `{"error": {...}, "timing": {...}}`.
+
+`shard` does not stream progress while it waits. For live events, use the SDK's `onProgress`.
+
 ## Secrets
 
 ```sh
@@ -146,6 +191,8 @@ printf %s "$NEW_KEY" | shard secrets rotate OPENAI_API_KEY
     `{deleted, id, name, scope}`; `workspaces secrets` prints `{workspace_id, names, secrets}`.
 
   Errors go to stderr as `{"error": {code, message, status, request_id, ...}}`.
+- **`--timing`:** the timing goes to stderr after the output. With `--json` it is a `timing` field instead
+  (see "Timing").
 
 ## Exit codes
 

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.2.0";
+export declare const CLI_VERSION = "0.3.0";
 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.2.0';
+export const CLI_VERSION = '0.3.0';
 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).' },
@@ -25,9 +25,21 @@ const CAPS = {
     'memory-mib': { type: 'string', value: '<n>', description: 'Memory cap in MiB.' },
     'disk-gib': { type: 'string', value: '<n>', description: 'Disk cap in GiB.' },
 };
+/** `--timing` (0.3.0+): the SDK's lifecycle timing of the command's open, wait or wake (README "Timing"). */
+const TIMING = {
+    timing: {
+        type: 'boolean',
+        description: 'Print where the time went on stderr after the call, also when it fails: client phases, the operation’s server timing, retries (with --json: a "timing" field instead).',
+    },
+};
+/** `--timing` of the commands that can wake a suspended workspace: the wake's timing, when there was one. */
+const WAKE_TIMING = {
+    timing: { type: 'boolean', description: 'Print where the time went when the command had to wake the workspace (stderr; with --json a "timing" field, null without a wake).' },
+};
 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.' },
+    ...TIMING,
 };
 const REF = { name: 'id|key', required: true };
 const SLUG = { name: 'slug', required: true };
@@ -100,12 +112,14 @@ 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.' },
+            ...TIMING,
         },
         examples: [
             'shard workspaces open acme/demo --template python-node-browser',
             'shard ws open job-42 --template python-node-browser --lifetime session',
             'shard ws open acme/demo --template python-node-browser --secret OPENAI_API_KEY --secret DATABASE_URL',
             'shard ws open acme/demo --template python-node-browser --no-wait --json',
+            'shard ws open acme/demo --template python-node-browser --timing',
         ],
     },
     {
@@ -133,6 +147,7 @@ export const COMMANDS = [
             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).' },
+            ...WAKE_TIMING,
         },
         examples: ['shard ws exec acme/demo -- python3 -V', 'shard ws exec acme/demo --cwd /home/user/app --env CI=1 -- bash -lc "npm test"'],
     },
@@ -188,6 +203,7 @@ export const COMMANDS = [
             summary: { type: 'boolean', description: 'Also print totals over everything under --path.' },
             ...PAGE,
             limit: { type: 'string', value: '<n>', description: 'Page size, 1-1000 (default 1000).' },
+            ...WAKE_TIMING,
         },
     },
     { path: ['workspaces', 'sessions'], summary: 'List the attributed agent sessions (tool-token principals and labels) of a workspace', positionals: [REF], options: {} },
@@ -206,7 +222,7 @@ export const COMMANDS = [
         path: ['files', 'read'],
         summary: 'Print (or save) a file from a workspace',
         positionals: [REF, { name: 'path', required: true }],
-        options: { out: { type: 'string', value: '<file>', description: 'Write to this local file instead of stdout.' } },
+        options: { out: { type: 'string', value: '<file>', description: 'Write to this local file instead of stdout.' }, ...WAKE_TIMING },
     },
     {
         path: ['files', 'write'],
@@ -216,13 +232,14 @@ export const COMMANDS = [
             from: { type: 'string', value: '<file|->', description: 'Local file to upload, or - for standard input (default -).' },
             append: { type: 'boolean', description: 'Append instead of replacing.' },
             parents: { type: 'boolean', description: 'Create missing parent directories (default; --no-parents to refuse).' },
+            ...WAKE_TIMING,
         },
     },
     {
         path: ['files', 'ls'],
         summary: 'List a directory in a workspace',
         positionals: [REF, { name: 'path', required: true }],
-        options: { limit: { type: 'string', value: '<n>', description: 'Maximum entries (default 1000).' } },
+        options: { limit: { type: 'string', value: '<n>', description: 'Maximum entries (default 1000).' }, ...WAKE_TIMING },
     },
     {
         path: ['operations', 'list'],
@@ -347,6 +364,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).' },
+            ...TIMING,
         },
         examples: ['shard templates draft open acme-dev --base python-node-browser@5'],
     },
@@ -374,6 +392,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).' },
+            ...TIMING,
         },
     },
     {
@@ -393,7 +412,7 @@ export const COMMANDS = [
         path: ['operations', 'wait'],
         summary: 'Wait for an operation to finish (exit 0 succeeded, 6 failed/canceled, 5 timeout)',
         positionals: [{ name: 'operation-id', required: true }],
-        options: { timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' } },
+        options: { timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' }, ...TIMING },
     },
 ];
 const GROUPS = {

package/dist/commands.d.ts

@@ -1,5 +1,6 @@
 import type { RunResult, Shardflux, Workspace } from '@shardflux/sdk';
 import type { Values } from './args.js';
+import type { TimingRecorder } from './timing.js';
 export interface Writer {
     write(chunk: string | Uint8Array): boolean;
 }
@@ -21,6 +22,10 @@ export interface Ctx {
     /** Bound on lifecycle waits per cell call, wakes included (--wake-timeout / SHARDFLUX_WAKE_TIMEOUT_MS). */
     wakeTimeoutMs: number;
     signal: AbortSignal;
+    /** --timing: print the SDK's timing of the command's open, wait or wake (stderr; a `timing` field with --json). */
+    timing: boolean;
+    /** Timings and the last observed operation of the traced SDK calls this command made (the client's onProgress). */
+    traces: TimingRecorder;
     cloud(): Shardflux;
 }
 export type Handler = (ctx: Ctx, values: Values, positionals: string[]) => Promise<number>;

package/dist/commands.js

@@ -9,6 +9,7 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { SDK_VERSION, ShardfluxApiError } from '@shardflux/sdk';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { InterruptedError, NotFoundError, UsageError } from "./errors.js";
+import { timingJson } from "./timing.js";
 import { bindingsText, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, fileTable, json, kv, operationDetail, operationTable, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, templateEntryText, templateFileTable, templateTable, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
@@ -30,8 +31,14 @@ function secretNames(names, option) {
         throw new UsageError(`${option} names a secret twice`);
     return [...names];
 }
+/** With --json --timing the JSON gains a `timing` field (null when the command made no traced lifecycle call). */
+function withTiming(ctx, machine) {
+    if (!ctx.timing || typeof machine !== 'object' || machine === null || Array.isArray(machine))
+        return machine;
+    return { ...machine, timing: timingJson(ctx.traces.last) };
+}
 function out(ctx, human, machine) {
-    ctx.io.stdout.write(ctx.json ? json(machine) : human);
+    ctx.io.stdout.write(ctx.json ? json(withTiming(ctx, machine)) : human);
 }
 function caps(values) {
     const c = {};
@@ -158,6 +165,21 @@ async function waitOperation(ctx, operationId, timeoutMs) {
         throw err;
     }
 }
+/**
+ * Runs an SDK call that waits itself (a waited open or lifecycle call). Ctrl-C reports the operation it was waiting
+ * for, as the SDK observed it; a held open interrupted before the server answered has none yet (`unnamed`).
+ */
+async function waited(ctx, unnamed, call) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        if (!ctx.signal.aborted)
+            throw err;
+        const id = ctx.traces.operationId;
+        throw id ? new InterruptedError(`Interrupted; operation ${id} continues server side.`, id) : new InterruptedError(`Interrupted; ${unnamed}`);
+    }
+}
 async function getOperation(ctx, operationId) {
     if (!UUID.test(operationId))
         throw new UsageError(`<operation-id> must be a UUID (got "${operationId}")`);
@@ -259,20 +281,18 @@ export const HANDLERS = {
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
         const timeoutMs = waitTimeout(values);
         const cloud = ctx.cloud();
-        let ws = await cloud.workspaces.open({
+        // The SDK's waited open: the server holds the request until the workspace is ready (Prefer: wait), then the SDK
+        // polls for what is left of --timeout; one trace (ws.lastTiming) covers all of it.
+        const ws = await waited(ctx, 'the open continues server side (open the key again to keep waiting).', () => cloud.workspaces.open({
             key: key,
             template,
             ...(c ? { caps: c } : {}),
             ...(bind.length ? { secrets: bind } : {}),
             ...(lifetime ? { lifetime } : {}),
             agentLabel: ctx.agentLabel,
-            wait: false,
-        });
+            wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
+        }));
         const op = ws.activeOperation;
-        if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
-            ws = await cloud.workspaces.get(ws.id);
-        }
         const view = ws.data;
         const human = ws.ready
             ? `Workspace ${ws.key} (${ws.id}) is ready.\n${workspaceDetail(view)}`
@@ -351,7 +371,7 @@ export const HANDLERS = {
         }
         const code = execExitCode(r);
         if (ctx.json) {
-            ctx.io.stdout.write(json({ 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, 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 })));
         }
         return code;
     },
@@ -364,7 +384,7 @@ export const HANDLERS = {
             out(ctx, `wrote ${bytes.length} bytes to ${dest}\n`, { path, bytes: bytes.length, out: dest });
         }
         else if (ctx.json) {
-            ctx.io.stdout.write(json({ path, bytes: bytes.length, content_base64: Buffer.from(bytes).toString('base64') }));
+            ctx.io.stdout.write(json(withTiming(ctx, { path, bytes: bytes.length, content_base64: Buffer.from(bytes).toString('base64') })));
         }
         else {
             ctx.io.stdout.write(bytes);
@@ -386,23 +406,23 @@ export const HANDLERS = {
         return 0;
     },
     async 'workspaces suspend'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Suspending', (ws) => ctx.cloud().workspaces.suspend(ws.id));
+        return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, o));
     },
     async 'workspaces resume'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Resuming', (ws) => ctx.cloud().workspaces.resume(ws.id));
+        return lifecycle(ctx, values, ref, 'Resuming', (ws, o) => ctx.cloud().workspaces.resume(ws.id, o));
     },
     async 'workspaces delete'(ctx, values, [ref]) {
         if (values.yes !== true)
             throw new UsageError('refusing to delete without --yes (deletion revokes tool access immediately and cannot be undone)');
-        return lifecycle(ctx, values, ref, 'Deleting', (ws) => ctx.cloud().workspaces.delete(ws.id));
+        return lifecycle(ctx, values, ref, 'Deleting', (ws, o) => ctx.cloud().workspaces.delete(ws.id, o));
     },
     async 'workspaces close'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Closing', (ws) => ctx.cloud().workspaces.close(ws.id));
+        return lifecycle(ctx, values, ref, 'Closing', (ws, o) => ctx.cloud().workspaces.close(ws.id, o));
     },
     async 'workspaces reset'(ctx, values, [ref]) {
         if (values.yes !== true)
             throw new UsageError('refusing to reset without --yes (reset wipes every change in the workspace and restarts it on its template)');
-        return lifecycle(ctx, values, ref, 'Resetting', (ws) => ctx.cloud().workspaces.reset(ws.id));
+        return lifecycle(ctx, values, ref, 'Resetting', (ws, o) => ctx.cloud().workspaces.reset(ws.id, o));
     },
     async 'workspaces save-as-template'(ctx, values, [ref]) {
         const template = str(values.template);
@@ -656,10 +676,8 @@ export const HANDLERS = {
         const c = caps(values);
         const timeoutMs = waitTimeout(values);
         const source = await resolveWorkspace(ctx, ref);
-        const res = await ctx.cloud().workspaces.fork(source.id, { key: newKey, ...(c ? { caps: c } : {}) });
-        let op = res.operation;
-        if (values.wait === true)
-            op = await waitOperation(ctx, op.id, timeoutMs);
+        const res = await waited(ctx, 'the fork continues server side.', () => ctx.cloud().workspaces.fork(source.id, { key: newKey, ...(c ? { caps: c } : {}) }, lifecycleOptions(ctx, values, timeoutMs)));
+        const op = res.operation;
         out(ctx, lifecycleText(`Forking ${source.key} into`, res.workspace, op), { operation: op, workspace: res.workspace.data });
         return 0;
     },
@@ -912,12 +930,14 @@ async function resolveSecret(ctx, values, ref) {
     } while (cursor);
     throw new NotFoundError(project !== null ? `No secret named "${ref}" in this project (organization-wide secrets: add --org <organization-id>).` : `No organization secret named "${ref}".`);
 }
+/** `--wait`: the SDK's own wait (the call resolves once the operation finished; one trace covers request and wait). */
+function lifecycleOptions(ctx, values, timeoutMs) {
+    return values.wait === true ? { wait: { timeoutMs, signal: ctx.signal } } : {};
+}
 async function lifecycle(ctx, values, ref, verb, start) {
     const timeoutMs = waitTimeout(values);
     const ws = await resolveWorkspace(ctx, ref);
-    let op = await start(ws);
-    if (values.wait === true)
-        op = await waitOperation(ctx, op.id, timeoutMs);
+    const op = await waited(ctx, 'the operation continues server side.', () => start(ws, lifecycleOptions(ctx, values, timeoutMs)));
     out(ctx, lifecycleText(verb, ws, op), op);
     return 0;
 }

package/dist/http.d.ts

@@ -9,5 +9,10 @@
  * 6.28) and `Connection: close` do not stall. A fresh connection per request
  * costs one TCP/TLS handshake, which is negligible for these call rates.
  * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ *
+ * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
+ * held by the server for up to 20 s). The SDK passes the caller's signal to its
+ * held polls itself, but not to the held open (`workspaces.open()` with `wait`
+ * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
  */
-export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch): typeof fetch;
+export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch, signal?: AbortSignal): typeof fetch;

package/dist/http.js

@@ -9,13 +9,22 @@
  * 6.28) and `Connection: close` do not stall. A fresh connection per request
  * costs one TCP/TLS handshake, which is negligible for these call rates.
  * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ *
+ * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
+ * held by the server for up to 20 s). The SDK passes the caller's signal to its
+ * held polls itself, but not to the held open (`workspaces.open()` with `wait`
+ * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
  */
-export function makeFetch(env, base = fetch) {
-    if (env.SHARDFLUX_HTTP_KEEPALIVE === '1')
-        return base;
+export function makeFetch(env, base = fetch, signal) {
+    const keepAlive = env.SHARDFLUX_HTTP_KEEPALIVE === '1';
     return (input, init) => {
         const headers = new Headers(init?.headers);
-        headers.set('connection', 'close');
-        return base(input, { ...init, headers });
+        const held = signal !== undefined && /\bwait\s*=/i.test(headers.get('prefer') ?? '');
+        if (keepAlive && !held)
+            return base(input, init);
+        if (!keepAlive)
+            headers.set('connection', 'close');
+        const s = held && signal ? (init?.signal ? AbortSignal.any([init.signal, signal]) : signal) : init?.signal;
+        return base(input, { ...init, headers, ...(s ? { signal: s } : {}) });
     };
 }

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export type { Ctx, Handler, Io, Writer } from './commands.js';
 export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from './errors.js';
 export type { ErrorInfo } from './errors.js';
 export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
+export { TimingRecorder, timingJson, timingText } from './timing.js';

package/dist/index.js

@@ -7,3 +7,4 @@ export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normal
 export { HANDLERS, execExitCode, resolveWorkspace } from "./commands.js";
 export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
 export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
+export { TimingRecorder, timingJson, timingText } from "./timing.js";

package/dist/main.js

@@ -10,6 +10,7 @@ import { HANDLERS } from "./commands.js";
 import { AuthConfigError, EXIT, InterruptedError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
 import { errorText, json } from "./format.js";
 import { makeFetch } from "./http.js";
+import { TimingRecorder, timingJson, timingText } from "./timing.js";
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
 const isLabel = (s) => s.length >= 1 && s.length <= 100 && ![...s].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
@@ -44,6 +45,9 @@ export async function run(argv, io, opts = {}) {
     const signal = opts.signal ?? new AbortController().signal;
     const rawKey = io.env.SHARDFLUX_API_KEY;
     const wantsJson = argv.slice(0, argv.includes('--') ? argv.indexOf('--') : argv.length).includes('--json');
+    // Every traced SDK call of the command (open, waited lifecycle calls, waits, wakes) reports here; --timing prints it.
+    const traces = new TimingRecorder();
+    let showTiming = false;
     const report = (err) => {
         const code = exitCodeFor(err, signal.aborted);
         const info = describeError(err);
@@ -52,7 +56,11 @@ export async function run(argv, io, opts = {}) {
             info.message = 'Interrupted.';
         }
         info.message = redact(info.message, rawKey);
-        io.stderr.write(redact(wantsJson ? json({ error: info }) : errorText(info, hintFor(info)), rawKey));
+        // --timing on a failure: the failed call's timing (err.timing, else the last recorded), before the error; with
+        // --json a `timing` field next to `error`.
+        const timing = showTiming ? traces.forError(err) : null;
+        const text = wantsJson ? json(showTiming ? { error: info, timing: timingJson(timing) } : { error: info }) : `${timing ? timingText(timing) : ''}${errorText(info, hintFor(info))}`;
+        io.stderr.write(redact(text, rawKey));
         return code;
     };
     let parsed;
@@ -78,6 +86,7 @@ export async function run(argv, io, opts = {}) {
             throw new UsageError('--agent-label must be 1-100 printable characters');
         const wake = resolveWake(parsed.global.wake, io.env.SHARDFLUX_NO_WAKE);
         const wakeTimeoutMs = resolveWakeTimeout(parsed.global.wakeTimeout, io.env.SHARDFLUX_WAKE_TIMEOUT_MS);
+        showTiming = parsed.values.timing === true;
         let cloud;
         ctx = {
             io,
@@ -87,6 +96,8 @@ export async function run(argv, io, opts = {}) {
             wake,
             wakeTimeoutMs,
             signal,
+            timing: showTiming,
+            traces,
             cloud() {
                 if (cloud)
                     return cloud;
@@ -95,7 +106,14 @@ export async function run(argv, io, opts = {}) {
                     throw new AuthConfigError('SHARDFLUX_API_KEY is not set.');
                 if (!KEY_SHAPE.test(key))
                     throw new AuthConfigError('SHARDFLUX_API_KEY is not a Shardflux project key (expected sfk_<key id>_<secret>).');
-                cloud = new Shardflux({ apiKey: key, baseUrl: apiUrl, userAgent: `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}`, fetch: makeFetch(io.env), sleep: abortableSleep(signal) });
+                cloud = new Shardflux({
+                    apiKey: key,
+                    baseUrl: apiUrl,
+                    userAgent: `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}`,
+                    fetch: makeFetch(io.env, fetch, signal),
+                    sleep: abortableSleep(signal),
+                    onProgress: traces.listener,
+                });
                 return cloud;
             },
         };
@@ -120,5 +138,8 @@ export async function run(argv, io, opts = {}) {
         return report(new InterruptedError('Interrupted.'));
     if ('err' in outcome)
         return report(outcome.err);
+    // With --json the handler put the timing into its output; otherwise it follows the output, on stderr.
+    if (showTiming && !ctx.json && traces.last)
+        io.stderr.write(timingText(traces.last));
     return outcome.code;
 }

package/dist/timing.d.ts

@@ -0,0 +1,17 @@
+import type { LifecycleTiming, ProgressListener } from '@shardflux/sdk';
+export declare class TimingRecorder {
+    /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
+    last: LifecycleTiming | null;
+    /** The operation the command's traced calls last observed: named when Ctrl-C interrupts a wait. */
+    operationId: string | null;
+    readonly listener: ProgressListener;
+    /**
+     * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
+     * carries the token fetch's timing, which is not a lifecycle call: then only a wake (if any) counts.
+     */
+    forError(err: unknown): LifecycleTiming | null;
+}
+/** The human form (stderr): formatTiming() of the SDK, one block. */
+export declare function timingText(t: LifecycleTiming): string;
+/** The `--json` form: the SDK's LifecycleTiming with the CLI's snake_case keys (the rest of its JSON is the API's). */
+export declare function timingJson(t: LifecycleTiming | null): Record<string, unknown> | null;

package/dist/timing.js

@@ -0,0 +1,65 @@
+/**
+ * `--timing`: where the time of a command's lifecycle call went, as @shardflux/sdk measures it (0.6.0+). The CLI
+ * does no timing of its own: the SDK traces open(), waited lifecycle calls, waitForOperation() and wakes, and emits
+ * each trace's LifecycleTiming in a `done` progress event (also on `err.timing` when the call fails). The recorder
+ * listens on the client (every traced call of the command), so a timing exists for failures too, including ones that
+ * carry no `timing` (network errors, Ctrl-C).
+ */
+import { formatTiming } from '@shardflux/sdk';
+export class TimingRecorder {
+    /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
+    last = null;
+    /** The operation the command's traced calls last observed: named when Ctrl-C interrupts a wait. */
+    operationId = null;
+    listener = (e) => {
+        if (e.action === 'token' || e.action === 'tool')
+            return;
+        if (e.operationId)
+            this.operationId = e.operationId;
+        if (e.type === 'done')
+            this.last = e.timing;
+    };
+    /**
+     * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
+     * carries the token fetch's timing, which is not a lifecycle call: then only a wake (if any) counts.
+     */
+    forError(err) {
+        const own = typeof err === 'object' && err !== null ? err.timing : undefined;
+        return own && own.action !== 'token' ? own : this.last;
+    }
+}
+/** The human form (stderr): formatTiming() of the SDK, one block. */
+export function timingText(t) {
+    return `${formatTiming(t)}\n`;
+}
+/** The `--json` form: the SDK's LifecycleTiming with the CLI's snake_case keys (the rest of its JSON is the API's). */
+export function timingJson(t) {
+    if (!t)
+        return null;
+    const s = t.server;
+    return {
+        action: t.action,
+        outcome: t.outcome,
+        workspace_id: t.workspaceId,
+        operation_id: t.operationId,
+        total_ms: t.totalMs,
+        phases: t.phases.map((p) => ({ phase: p.phase, reason: p.reason, operation_id: p.operationId, start_ms: p.startMs, duration_ms: p.durationMs })),
+        retries: t.retries.map((r) => ({ at_ms: r.atMs, request: r.request, attempt: r.attempt, cause: r.cause, delay_ms: r.delayMs })),
+        server: s
+            ? {
+                operation_id: s.operationId,
+                kind: s.kind,
+                state: s.state,
+                queued_ms: s.queuedMs,
+                run_ms: s.runMs,
+                total_ms: s.totalMs,
+                start_path: s.startPath,
+                warm_fallback: s.warmFallback,
+                resume_path: s.resumePath,
+                boot_to_ready_ms: s.bootToReadyMs,
+                host_timings_ms: s.hostTimingsMs,
+            }
+            : null,
+        outside_server_ms: t.outsideServerMs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",
@@ -32,13 +32,14 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@shardflux/sdk": "^0.6.0"
+    "@shardflux/sdk": "^0.6.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",