@shardflux/cli 0.7.0 → 0.8.1

package/dist/commands.js

@@ -8,15 +8,15 @@
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
-import { EXECUTION_ID, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, newExecutionId } from '@shardflux/sdk';
+import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId } from '@shardflux/sdk';
 import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
-import { ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
+import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
 import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -66,6 +66,47 @@ function caps(values) {
         c.disk_gib = parsePositiveInt(disk, 'disk-gib', 1_000_000);
     return Object.keys(c).length ? c : undefined;
 }
+const ALLOCATION_MODES = ['fixed', 'elastic'];
+/**
+ * The caps of `workspaces open` and `workspaces fork` (0.8.0): the resource caps plus the memory allocation. Given caps
+ * replace the stored ones, so they are sent only when a flag was given.
+ */
+function workspaceCaps(values) {
+    const c = caps(values) ?? {};
+    const mode = oneOf(values, 'allocation-mode', ALLOCATION_MODES);
+    const held = str(values['memory-held']);
+    if (held !== undefined && mode !== 'elastic')
+        throw new UsageError('--memory-held needs --allocation-mode elastic (a fixed workspace holds all of --memory-mib)');
+    if (mode !== undefined)
+        c.allocation_mode = mode;
+    if (held !== undefined)
+        c.memory_mib_held = parsePositiveInt(held, 'memory-held', 16_777_216);
+    return Object.keys(c).length ? c : undefined;
+}
+/**
+ * `--burst [--burst-vcpus N] [--burst-memory MIB]` of `workspaces exec` (0.8.0): the exec.run options,
+ * or undefined without --burst.
+ */
+function burstOptions(values, withStdin) {
+    const vcpus = str(values['burst-vcpus']);
+    const mem = str(values['burst-memory']);
+    if (values.burst !== true) {
+        if (vcpus !== undefined || mem !== undefined)
+            throw new UsageError('--burst-vcpus and --burst-memory need --burst');
+        return undefined;
+    }
+    if (withStdin)
+        throw new UsageError('--burst runs the command to completion without stdin; drop --stdin');
+    const o = { burst: 'always' };
+    if (vcpus !== undefined)
+        o.burstVcpus = parsePositiveInt(vcpus, 'burst-vcpus', 32);
+    if (mem !== undefined) {
+        o.burstMemoryMib = parsePositiveInt(mem, 'burst-memory', 65_536);
+        if (o.burstMemoryMib < 512)
+            throw new UsageError('--burst-memory must be between 512 and 65536');
+    }
+    return o;
+}
 /** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds). */
 export function whenIdleSeconds(text) {
     if (/^0+(?:\.0+)?(?:ms|s|m|h)?$/.test(text.trim()))
@@ -414,6 +455,75 @@ export function execExitCode(r) {
         return 128 + r.termSignal;
     return 1;
 }
+/** The longest cancel grace the workspace applies (it waits 5 s without one). */
+const MAX_CANCEL_GRACE_MS = 60_000;
+/** Error codes of a burst's own failure (an output stream's final error event; the session carries it too). */
+const BURST_FAILURES = new Set(['burst_unavailable', 'burst_apply_failed']);
+/**
+ * `shard ws exec-read` (0.8.0): an exec session's output from offset 0, and the session. Without `follow`, the output
+ * that exists now; with it, until the session ends, resuming from the byte offsets read after a dropped stream.
+ * `maxBytes` of each stream are kept for the result (the rest is counted); `onOutput` gets every new chunk.
+ */
+async function readSession(cell, sessionId, opts) {
+    let session = await cell.exec.get(sessionId);
+    const kept = { stdout: [], stderr: [] };
+    const size = { stdout: 0, stderr: 0 };
+    let total = { stdout: 0, stderr: 0 };
+    let reconnects = 0;
+    const live = (s) => s.state === 'starting' || s.state === 'running';
+    for (;;) {
+        let ended;
+        try {
+            const events = await cell.exec.output(sessionId, { stdoutOffset: total.stdout, stderrOffset: total.stderr, follow: opts.follow && live(session), signal: opts.signal });
+            for await (const ev of events) {
+                if (ev.type === 'output' && ev.data !== undefined) {
+                    const stream = ev.stream === 'stderr' ? 'stderr' : 'stdout';
+                    const bytes = Buffer.from(ev.data, 'base64');
+                    const start = ev.offset ?? total[stream];
+                    // A reconnect may resend bytes already printed.
+                    const fresh = start < total[stream] ? bytes.subarray(Math.min(total[stream] - start, bytes.length)) : bytes;
+                    if (fresh.length === 0)
+                        continue;
+                    total = { ...total, [stream]: Math.max(total[stream], start + bytes.length) };
+                    const room = opts.maxBytes - size[stream];
+                    if (room > 0) {
+                        kept[stream].push(fresh.subarray(0, room));
+                        size[stream] += Math.min(room, fresh.length);
+                    }
+                    opts.onOutput?.(stream, fresh);
+                }
+                else if (ev.type === 'exit') {
+                    ended = ev.session ?? (await cell.exec.get(sessionId));
+                    break;
+                }
+                else if (ev.type === 'error' && ev.error && !BURST_FAILURES.has(ev.error.error.code)) {
+                    throw new ShardfluxApiError(502, ev.error, 'cell');
+                }
+            }
+        }
+        catch (err) {
+            if (opts.signal.aborted)
+                throw err;
+            const transient = !(err instanceof ShardfluxApiError) || err.retryable;
+            if (!opts.follow || !transient || reconnects >= 10)
+                throw err;
+        }
+        if (ended)
+            session = ended;
+        else if (opts.follow) {
+            // The stream ended without the exit (a dropped connection, a restarted gateway): continue from the offsets.
+            reconnects += 1;
+            if (reconnects > 10)
+                throw new ShardfluxProtocolError(`exec ${sessionId}: output stream kept dropping`, 0, 'cell');
+            await new Promise((r) => setTimeout(r, Math.min(2_000, 100 * 2 ** reconnects)).unref());
+            session = await cell.exec.get(sessionId);
+            if (live(session) || total.stdout < session.stdout_size || total.stderr < session.stderr_size)
+                continue;
+        }
+        const text = (b) => new TextDecoder().decode(Buffer.concat(b));
+        return { session, stdout: text(kept.stdout), stderr: text(kept.stderr), truncated: total.stdout > size.stdout || total.stderr > size.stderr, reconnects };
+    }
+}
 async function bestEffortCancel(cell, sessionId) {
     await Promise.race([cell.exec.cancel(sessionId).catch(() => undefined), new Promise((r) => setTimeout(r, 3_000).unref())]);
 }
@@ -496,7 +606,7 @@ function reportExecution(ctx, ref, r, opts) {
 }
 function lifecycleText(verb, w, op) {
     const finished = op.state === 'succeeded' || op.state === 'failed' || op.state === 'canceled';
-    return `${verb} ${w.key} (${w.id}): operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
+    return `${verb} ${w.key !== undefined ? `${w.key} (${w.id})` : w.id}: operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
 }
 /** The project-key commands; handlers.ts adds the account plane's. */
 export const KEY_HANDLERS = {
@@ -590,10 +700,78 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'workspaces exec-start'(ctx, values, [ref, ...argv]) {
+        const timeout = str(values.timeout);
+        const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
         const ws = await resolveWorkspace(ctx, ref);
         const session = await cellOf(ctx, ws).exec.start({ argv, stdin_open: values['stdin-open'] === true,
-            ...(str(values['session-id']) ? { session_id: str(values['session-id']) } : {}), ...(str(values.cwd) ? { cwd: str(values.cwd) } : {}) }, ctx.signal);
+            ...(str(values['session-id']) ? { session_id: str(values['session-id']) } : {}), ...(str(values.cwd) ? { cwd: str(values.cwd) } : {}),
+            ...(timeoutMs !== undefined ? { timeout_ms: timeoutMs } : {}) }, ctx.signal);
         out(ctx, JSON.stringify(session, null, 2) + '\n', session);
+        // 0.8.0: what to do next (stderr, so stdout stays the session's JSON).
+        if (!ctx.json && session.state !== 'failed_to_start')
+            ctx.io.stderr.write(`read it with: shard ws exec-read ${ref} ${session.session_id} --follow; stop it with: shard ws exec-cancel ${ref} ${session.session_id}\n`);
+        return 0;
+    },
+    async 'workspaces exec-read'(ctx, values, [ref, sessionId]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const cell = cellOf(ctx, ws);
+        const follow = values.follow === true;
+        let r;
+        try {
+            r = await readSession(cell, sessionId, {
+                follow,
+                signal: ctx.signal,
+                maxBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
+                ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
+            });
+        }
+        catch (err) {
+            if (ctx.signal.aborted && follow) {
+                throw new InterruptedError(`Stopped following exec session ${sessionId}; the command keeps running.`, undefined, { hint: `stop it with: shard ws exec-cancel ${ref} ${sessionId}` });
+            }
+            throw err;
+        }
+        const s = r.session;
+        // Nothing ran (a cwd that is not a directory, a program not on PATH): exit 6 with the workspace's reason, as ws exec.
+        if (s.burst?.error)
+            throw new ShardfluxApiError(409, { error: { code: s.burst.error.code, message: s.burst.error.message, request_id: '', retryable: s.burst.error.retryable, ...(s.burst.error.details ? { details: s.burst.error.details } : {}) } }, 'cell');
+        if (s.state === 'failed_to_start')
+            throw new ExecStartError(s);
+        if (ctx.json) {
+            ctx.io.stdout.write(json(withTiming(ctx, {
+                session_id: s.session_id,
+                state: s.state,
+                exit_code: s.exit_code ?? null,
+                term_signal: s.term_signal ?? null,
+                timed_out: s.timed_out ?? false,
+                canceled: s.canceled ?? false,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                truncated: r.truncated,
+                reconnects: r.reconnects,
+                ...(s.error ? { error: s.error } : {}),
+                ...(s.burst ? { burst: s.burst } : {}),
+            })));
+        }
+        if (s.state === 'starting' || s.state === 'running') {
+            throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
+        }
+        const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false };
+        if (!ctx.json && result.exitCode === null && !result.timedOut && !(result.termSignal !== null && result.termSignal > 0)) {
+            ctx.io.stderr.write(`exec session ${s.session_id} ended ${s.state} without an exit code${s.error ? `: ${s.error}` : ''}\n`);
+        }
+        return execExitCode(result);
+    },
+    async 'workspaces exec-cancel'(ctx, values, [ref, sessionId]) {
+        const grace = str(values.grace);
+        const graceMs = grace === undefined ? undefined : parseDuration(grace, 'grace');
+        if (graceMs !== undefined && graceMs > MAX_CANCEL_GRACE_MS)
+            throw new UsageError(`--grace must be at most 60s (got "${grace}")`);
+        const ws = await resolveWorkspace(ctx, ref);
+        const s = await cellOf(ctx, ws).exec.cancel(sessionId, graceMs);
+        const ended = s.state !== 'starting' && s.state !== 'running';
+        const status = !ended ? `${s.state} (cancel sent)` : s.canceled ? `canceled${s.term_signal ? ` (signal ${s.term_signal})` : ''}` : `already ${s.state}${typeof s.exit_code === 'number' ? ` (exit code ${s.exit_code})` : ''}`;
+        out(ctx, `exec session ${s.session_id}: ${status}\n`, s);
         return 0;
     },
     async 'workspaces exec-input'(ctx, values, [ref, sessionId, data]) {
@@ -609,7 +787,7 @@ export const KEY_HANDLERS = {
         const template = str(values.template);
         if (!template)
             throw new UsageError('--template <slug> is required for "shard workspaces open"');
-        const c = caps(values);
+        const c = workspaceCaps(values);
         const bind = secretNames(strs(values.secret), '--secret');
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
         const mode = modeFlag(values);
@@ -699,11 +877,14 @@ export const KEY_HANDLERS = {
         const limitText = str(values['output-limit']);
         const outputLimit = limitText === undefined ? undefined : parsePositiveInt(limitText, 'output-limit', MAX_OUTPUT_LIMIT);
         const stdinSource = str(values.stdin);
+        const burst = burstOptions(values, stdinSource !== undefined);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
         const ws = await resolveWorkspace(ctx, ref);
         const cell = cellOf(ctx, ws);
         const cwd = str(values.cwd);
         if (ws.mode === 'file_first') {
+            if (burst)
+                throw new UsageError(`--burst applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)}`);
             // An execution: answered when the command ended. The id is ours, so Ctrl-C can name it.
             const id = executionId ?? newExecutionId();
             let r;
@@ -739,6 +920,7 @@ export const KEY_HANDLERS = {
                 ...(Object.keys(env).length ? { env } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(stdin !== undefined ? { stdin } : {}),
+                ...(burst ?? {}),
                 maxOutputBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
                 ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
                 signal: ctx.signal,
@@ -746,9 +928,14 @@ export const KEY_HANDLERS = {
         }
         catch (err) {
             if (ctx.signal.aborted) {
+                if (burst)
+                    throw new InterruptedError(`Interrupted; burst exec session ${sessionId} keeps running server side (a burst cannot be canceled).`);
                 await bestEffortCancel(cell, sessionId);
                 throw new InterruptedError(`Interrupted; sent cancel to exec session ${sessionId}.`);
             }
+            // A burst's apply that did not complete is finished by a retry of the same session (SDK exec.run / the API).
+            if (burst && err instanceof ShardfluxApiError && err.code === 'burst_apply_failed')
+                ctx.io.stderr.write(`burst exec session ${sessionId}\n`);
             throw err;
         }
         const code = execExitCode(r);
@@ -757,7 +944,14 @@ export const KEY_HANDLERS = {
         const unexplained = r.exitCode === null && !r.timedOut && !(r.termSignal !== null && r.termSignal > 0);
         if (values.verbose === true && !ctx.json) {
             const status = r.timedOut ? 'timed out' : r.canceled ? 'canceled' : r.termSignal ? `killed by signal ${r.termSignal}` : unexplained ? r.session.state : `exit code ${r.exitCode ?? '-'}`;
-            ctx.io.stderr.write(kv([['session', r.sessionId], ['status', status], ['output', `${r.stdoutBytes} bytes stdout, ${r.stderrBytes} bytes stderr`], ['reconnects', String(r.reconnects)]]));
+            ctx.io.stderr.write(kv([
+                ['session', r.sessionId],
+                ['status', status],
+                ['output', `${r.stdoutBytes} bytes stdout, ${r.stderrBytes} bytes stderr`],
+                ['reconnects', String(r.reconnects)],
+                ...(r.memoryGrow ? [['memory grow', memoryGrowText(r.memoryGrow)]] : []),
+                ...(r.burst ? [['burst', burstText(r.burst)]] : []),
+            ]));
         }
         if (ctx.json) {
             ctx.io.stdout.write(json(withTiming(ctx, {
@@ -772,6 +966,8 @@ export const KEY_HANDLERS = {
                 truncated: r.truncated,
                 reconnects: r.reconnects,
                 ...(r.session.error ? { error: r.session.error } : {}),
+                ...(r.memoryGrow ? { memory_grow: r.memoryGrow } : {}),
+                ...(r.burst ? { burst: r.burst } : {}),
             })));
         }
         else if (unexplained) {
@@ -899,7 +1095,21 @@ export const KEY_HANDLERS = {
         const cancel = values['cancel-when-idle'] === true;
         const durable = values.durable === true;
         if (whenIdle === undefined && !cancel) {
-            return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, durable ? { ...o, durable: true, wait: o.wait ?? { timeoutMs: waitTimeout(values), signal: ctx.signal } } : o), ['suspend', 'Suspend']);
+            const suspend = (id, o) => ctx.cloud().workspaces.suspend(id, durable ? { ...o, durable: true, wait: o.wait ?? { timeoutMs: waitTimeout(values), signal: ctx.signal } } : o);
+            if (UUID.test(ref)) {
+                // An id needs no resolve request: the suspend goes straight to it (the API refuses a file-first workspace
+                // itself). Only a UUID that is no workspace id here (404, nothing started) is looked up as a key.
+                try {
+                    const op = await waited(ctx, 'the operation continues server side.', () => suspend(ref, lifecycleOptions(ctx, values, waitTimeout(values))));
+                    out(ctx, lifecycleText('Suspending', { id: ref }, op), op);
+                    return 0;
+                }
+                catch (err) {
+                    if (!(err instanceof ShardfluxApiError && err.status === 404 && err.operationId === undefined))
+                        throw err;
+                }
+            }
+            return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => suspend(ws.id, o), ['suspend', 'Suspend']);
         }
         if (durable)
             throw new UsageError(`${whenIdle !== undefined ? '--when-idle' : '--cancel-when-idle'} cannot be combined with --durable (nothing is suspended now)`);
@@ -1423,7 +1633,7 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'workspaces fork'(ctx, values, [ref, newKey]) {
-        const c = caps(values);
+        const c = workspaceCaps(values);
         const timeoutMs = waitTimeout(values);
         const source = await resolveWorkspace(ctx, ref);
         requireProcessful(source, 'fork', 'A fork');

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { CheckoutStatus, ExecutionResult } from '@shardflux/sdk';
+import type { CheckoutStatus, ExecSession, ExecutionResult } from '@shardflux/sdk';
 export declare const EXIT: {
     readonly ok: 0;
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -76,6 +76,15 @@ export declare class ExecutionPendingError extends Error {
     readonly hint: string;
     constructor(message: string, result: ExecutionResult, hint: string);
 }
+/**
+ * `shard ws exec-read` without --follow (0.8.0): the background command still runs (exit 5, as a file-first execution
+ * that still runs); `hint` names the command that follows it to its end.
+ */
+export declare class ExecSessionRunningError extends HintedError {
+    name: string;
+    readonly session: ExecSession;
+    constructor(message: string, session: ExecSession, hint: string);
+}
 export interface ErrorInfo {
     code: string;
     message: string;
@@ -89,6 +98,8 @@ export interface ErrorInfo {
     operation?: unknown;
     /** A file-first execution the error is about (failed, lost, still running, or left running by Ctrl-C). */
     execution_id?: string;
+    /** The refusal's Retry-After in seconds (0.9.0+), e.g. 429 quota_exceeded from the cell gateway. */
+    retry_after_seconds?: number;
 }
 /**
  * Removes anything shaped like a Shardflux API key or user session token from text, and each of the given secrets

package/dist/errors.js

@@ -97,6 +97,18 @@ export class ExecutionPendingError extends Error {
         this.hint = hint;
     }
 }
+/**
+ * `shard ws exec-read` without --follow (0.8.0): the background command still runs (exit 5, as a file-first execution
+ * that still runs); `hint` names the command that follows it to its end.
+ */
+export class ExecSessionRunningError extends HintedError {
+    name = 'ExecSessionRunningError';
+    session;
+    constructor(message, session, hint) {
+        super(message, hint);
+        this.session = session;
+    }
+}
 const AUTH_CODES = new Set(['unauthenticated', 'invalid_credentials', 'token_invalid', 'forbidden', 'mfa_required', 'email_unverified', 'step_up_required', 'csrf_failed']);
 const KEY_PATTERN = /sfk_[A-Za-z0-9]{8,}_[A-Za-z0-9]+/g;
 /** User session tokens (`sfu_` + 43 base64url characters), also cut short. */
@@ -135,6 +147,7 @@ export function describeError(err) {
             ...(err.operationId ? { operation_id: err.operationId } : {}),
             ...(err.details ? { details: err.details } : {}),
             source: err.source,
+            ...(err.retryAfterSeconds !== undefined ? { retry_after_seconds: err.retryAfterSeconds } : {}),
         };
     }
     if (err instanceof OperationTimeoutError) {
@@ -163,6 +176,8 @@ export function describeError(err) {
     }
     if (err instanceof ExecutionPendingError)
         return { code: 'timeout', message: err.message, execution_id: err.result.executionId, last_state: err.result.state };
+    if (err instanceof ExecSessionRunningError)
+        return { code: 'timeout', message: err.message, last_state: err.session.state, details: { session_id: err.session.session_id } };
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
     if (err instanceof CheckoutTimeoutError) {
@@ -214,7 +229,7 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.timeout;
     if (err instanceof OperationFailedError || err instanceof DurabilityLostError || err instanceof ExecutionFailedError || err instanceof CheckoutEndedError)
         return EXIT.operationFailed;
-    if (err instanceof ExecutionPendingError)
+    if (err instanceof ExecutionPendingError || err instanceof ExecSessionRunningError)
         return EXIT.timeout;
     // A command that could not start exits 6 in both modes, as a failed execution does (0.5.1).
     if (err instanceof ExecStartError)

package/dist/format.d.ts

@@ -1,5 +1,7 @@
-import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, WorkspaceChange, WorkspaceSecretBindings, WorkspaceView } from '@shardflux/sdk';
+import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
+/** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
+export declare function byteSize(n: number): string;
 export declare function json(value: unknown): string;
 export declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): string;
 export declare function kv(pairs: readonly (readonly [string, string])[]): string;
@@ -33,6 +35,12 @@ export declare function suspendWhenIdleText(w: {
     suspend_request: SuspendRequest | null;
     operation: Operation | null;
 }): string;
+/** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
+export declare function memoryText(m: WorkspaceMemory): string;
+/** The grow an exec's start waited for: `delivered 1024 -> 4096 MiB in 175 ms`, `partial 1024 -> 3072 of 4096 MiB in 175 ms`. */
+/** The burst line of `ws exec -v` (0.8.0). */
+export declare function burstText(b: BurstSummary): string;
+export declare function memoryGrowText(g: MemoryGrow): string;
 export declare function workspaceDetail(w: WorkspaceView): string;
 export declare const OPERATION_HEADERS: readonly ["ID", "KIND", "STATE", "REASON", "CREATED", "COMPLETED"];
 export declare function operationTable(ops: readonly Operation[]): string;
@@ -90,6 +98,8 @@ export declare function languageTable(l: TemplateLanguages): string;
 export declare function packageTable(page: TemplatePackagePage): string;
 /** A template: identity, what open resolves to, its versions, and the open version's settings. */
 export declare function templateDetailText(t: TemplateDetail): string;
+/** A version's immutable paths and the size of their image: `/opt/acme, /srv/tools (128.0 MiB)`, or `-`. */
+export declare function immutablePathsText(i: TemplateVersion['immutable'] | undefined): string;
 /** A version's settings, one line per part. */
 export declare function settingsText(s: TemplateSettings): string;
 /** How many changed paths the human output lists before "... N more" (--json lists every one the result has). */

package/dist/format.js

@@ -4,6 +4,10 @@
  * these functions only shape what people read.
  */
 import { durabilityOf, isDurable } from '@shardflux/sdk';
+/** A size for people: `512 B`, `10.0 KiB`, `128.0 MiB`, `1.50 GiB`. */
+export function byteSize(n) {
+    return n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MiB` : `${(n / 1024 ** 3).toFixed(2)} GiB`;
+}
 export function json(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -128,6 +132,32 @@ export function suspendWhenIdleText(w, r) {
     const op = r.operation;
     return `A suspend of ${w.key} (${w.id}) is already in progress (operation ${op.id} ${op.kind} ${op.state}); nothing was scheduled.\nwait with: shard operations wait ${op.id}\n`;
 }
+const mib = (n) => (n === null ? '-' : `${n} MiB`);
+/** `fixed 4096 MiB`, or `elastic: promised 8192 MiB, held 1024 MiB, plugged +2048 MiB` (plugged: above the held floor now). */
+export function memoryText(m) {
+    if (m.allocation_mode !== 'elastic')
+        return `fixed ${mib(m.promised_mib)}`;
+    return `elastic: promised ${mib(m.promised_mib)}, held ${mib(m.held_mib)}, plugged ${m.plugged_mib === null ? '- (not running)' : `+${m.plugged_mib} MiB`}`;
+}
+/** The grow an exec's start waited for: `delivered 1024 -> 4096 MiB in 175 ms`, `partial 1024 -> 3072 of 4096 MiB in 175 ms`. */
+/** The burst line of `ws exec -v` (0.8.0). */
+export function burstText(b) {
+    const size = [b.vcpus !== undefined ? `${b.vcpus} vCPU` : null, b.memory_mib !== undefined ? `${b.memory_mib} MiB` : null].filter(Boolean).join(' / ');
+    const head = `${b.host}${size ? ` ${size}` : ''}${b.method ? ` (${b.method})` : ''}`;
+    const changes = b.applied
+        ? `applied ${b.written_files ?? 0} files, ${b.written_dirs ?? 0} dirs, ${b.removed ?? 0} removed, ${b.written_bytes ?? 0} bytes`
+        : 'changes not applied';
+    const extra = [
+        b.leftover_killed ? `${b.leftover_killed} leftover processes killed` : null,
+        b.overhead_ms !== undefined ? `overhead ${b.overhead_ms} ms` : null,
+        b.replayed ? 'replayed' : null,
+    ].filter(Boolean);
+    return [head, changes, ...extra].join('; ');
+}
+export function memoryGrowText(g) {
+    const to = g.got_mib === g.want_mib ? `${g.got_mib} MiB` : `${g.got_mib} of ${g.want_mib} MiB`;
+    return `${g.outcome} ${g.from_mib} -> ${to} in ${g.deliver_ms} ms`;
+}
 export function workspaceDetail(w) {
     const c = w.ceilings;
     const startup = startupText(w.startup);
@@ -138,6 +168,8 @@ export function workspaceDetail(w) {
         ['state', `${w.observed_state} (desired ${w.desired_state})`],
         ['ready', isReady(w) ? 'yes' : 'no'],
         ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
+        // Immutable paths (0.8.0): the template version whose immutable paths the workspace has mounted, when it has one.
+        ...(typeof w.template.immutable_version === 'number' ? [['immutable paths', `v${w.template.immutable_version} (mounted read-only)`]] : []),
         // The mode (0.5.0) when the API reports it; a file-first workspace's state is its tree revision.
         ...(w.mode !== undefined ? [['mode', modeText(w.mode)]] : []),
         ...(w.mode === 'file_first' ? [['tree revision', String(w.tree_revision)]] : []),
@@ -145,6 +177,8 @@ export function workspaceDetail(w) {
         ['ceilings', c ? `cpu ${c.cpu_millis}m (${c.sources.cpu_millis}), memory ${c.memory_mib} MiB (${c.sources.memory_mib}), disk ${c.disk_gib} GiB (${c.sources.disk_gib})` : '-'],
         ['grants', pairs(w.grants)],
         ['caps', pairs(w.caps)],
+        // Elastic memory (0.8.0) when the API reports it.
+        ...(w.memory ? [['memory', memoryText(w.memory)]] : []),
         ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
         ['pending', w.pending_reason ?? '-'],
         ...(suspendRequest ? [['suspend when idle', suspendRequestText(suspendRequest)]] : []),
@@ -362,6 +396,10 @@ export function usageText(summary) {
         const trialEnded = isObject(s.plan) && s.plan.plan_key === 'trial';
         head.push(['allowance exhausted', s.allowance_exhausted ? (trialEnded ? `yes (${reason}the trial ends; the organization is back on free)` : `yes (${reason}new opens/resumes are refused)`) : 'no']);
     }
+    // cap_state storage_blocked (0.9.0): the Retained state allowance is used up; existing workspaces keep working.
+    if (Array.isArray(s.allowances) && s.allowances.some((a) => isObject(a) && a.cap_state === 'storage_blocked')) {
+        head.push(['retained state', 'used up: new workspaces and forks are refused (delete workspaces you no longer need, or upgrade)']);
+    }
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
             head.push([k.replace(/_/g, ' '), scalar(v)]);
@@ -509,15 +547,30 @@ function buildSource(b) {
     const v2 = b.provenance.recipe_schema === 'shardflux.template-recipe.v2';
     return `recipe${v2 ? ' v2' : ''}${b.provenance.recipe_sha256 ? ` (sha256 ${b.provenance.recipe_sha256.slice(0, 12)})` : ''}`;
 }
+/** What to do about a build that failed on its immutable paths (0.8.0; contracts §34.2), from failure.code and details. */
+function immutableFailureFix(f) {
+    if (f.code === 'immutable_path_missing') {
+        const path = typeof f.details?.path === 'string' ? f.details.path : 'the path';
+        return `make ${path} a directory in the build (a step: mkdir -p ${path}), then build again`;
+    }
+    if (f.code === 'immutable_image_too_large')
+        return 'keep large data outside the immutable paths, then build again';
+    return null;
+}
 export function buildText(b) {
     const settled = b.state === 'published' || b.state === 'failed' || b.state === 'canceled' || b.state === 'succeeded';
     const denied = b.denied_hosts ?? [];
+    const immutable = b.immutable_paths ?? [];
+    const fix = b.failure ? immutableFailureFix(b.failure) : null;
     return (kv([
         ['build', b.id],
         ['template', `${b.template.slug} v${b.target_version ?? '?'}`],
         ['state', `${b.state}${b.failure ? ` (${b.failure.code}: ${b.failure.message})` : ''}`],
+        ...(fix ? [['fix', fix]] : []),
         ['registration', `${b.registration.state}${b.registration.error ? ` (${b.registration.error.code}: ${b.registration.error.message})` : ''}`],
         ['source', buildSource(b)],
+        // Immutable paths (0.8.0): the list the produced version declares.
+        ...(immutable.length ? [['immutable paths', immutable.join(', ')]] : []),
         ['network', b.network.mode === 'none' ? 'none' : `allowlist ${b.network.allow_hosts.join(', ') || '(empty)'}`],
         ...(denied.length ? [['denied hosts', `${denied.join(', ')} (allow one: add it to build.network.extra_hosts and build again)`]] : []),
         ['version', b.template_version ? `${b.template_version.id}${b.template_version.published ? ' (published)' : ' (unpublished)'}` : '-'],
@@ -543,11 +596,25 @@ export function templateDetailText(t) {
         ['draft', t.draft ? `${t.draft.workspace_key} (${t.draft.observed_state})` : '-'],
         ['archived', time(t.archived_at)],
     ]);
+    // Immutable paths (0.8.0): the column appears when a version declares any.
+    const immutable = t.versions.some((v) => v.immutable);
     const versions = t.versions.length
-        ? table(['VERSION', 'STATE', 'SOURCE', 'LAYOUTS', 'CREATED', 'DESCRIPTION'], t.versions.map((v) => [`v${v.version}${v.is_open_version ? ' *' : ''}`, v.state, v.source?.kind ?? '-', v.disk_layouts.join(',') || '-', time(v.created_at), v.description ?? '-']))
+        ? table(['VERSION', 'STATE', 'SOURCE', 'LAYOUTS', ...(immutable ? ['IMMUTABLE PATHS'] : []), 'CREATED', 'DESCRIPTION'], t.versions.map((v) => [
+            `v${v.version}${v.is_open_version ? ' *' : ''}`,
+            v.state,
+            v.source?.kind ?? '-',
+            v.disk_layouts.join(',') || '-',
+            ...(immutable ? [immutablePathsText(v.immutable)] : []),
+            time(v.created_at),
+            v.description ?? '-',
+        ]))
         : 'No versions.\n';
     return `${head}\n${versions}${open?.settings ? `\nsettings of v${open.version}:\n${settingsText(open.settings)}` : ''}`;
 }
+/** A version's immutable paths and the size of their image: `/opt/acme, /srv/tools (128.0 MiB)`, or `-`. */
+export function immutablePathsText(i) {
+    return i ? `${i.paths.join(', ')} (${byteSize(i.bytes)})` : '-';
+}
 /** A version's settings, one line per part. */
 export function settingsText(s) {
     const inputs = Object.entries(s.inputs).map(([n, i]) => `${n} (${i.kind}${i.required ? ', required' : ''}${i.default !== null ? `, default ${JSON.stringify(i.default)}` : ''})`);

package/dist/index.d.ts

@@ -22,4 +22,4 @@ export { openUrl, openerFor } from './browser.js';
 export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, ExecutionPendingError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from './errors.js';
 export type { ErrorInfo } from './errors.js';
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
-export { TimingRecorder, coldBootNotice, lostSuspendNotice, notices, timingJson, timingText } from './timing.js';
+export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from './timing.js';

package/dist/index.js

@@ -14,4 +14,4 @@ export { CHECK_INTERVAL_MS, CLI_DISTRIBUTION, NOTICE_WAIT_MS, UPDATE_CHECK_FILE,
 export { openUrl, openerFor } from "./browser.js";
 export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, ExecutionPendingError, InterruptedError, MfaPendingError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
-export { TimingRecorder, coldBootNotice, lostSuspendNotice, notices, timingJson, timingText } from "./timing.js";
+export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from "./timing.js";