@shardflux/cli 0.8.0 → 0.9.0

package/dist/commands.js

@@ -16,7 +16,7 @@ import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, 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";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, resizeJson, resizeText, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, exposedPortText, portTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, time, 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;
@@ -67,6 +67,35 @@ function caps(values) {
     return Object.keys(c).length ? c : undefined;
 }
 const ALLOCATION_MODES = ['fixed', 'elastic'];
+/** `--resource-hint` of `workspaces exec` / `exec-start` (0.9.0): the exec's memory hint. */
+const RESOURCE_HINTS = ['auto', 'light', 'heavy'];
+/** The resources of `workspaces resize` (0.9.0): at least one, validated before any request. */
+function resizeParams(values) {
+    const p = {};
+    const memory = str(values.memory);
+    const held = str(values.held);
+    const cpu = str(values.cpu);
+    const disk = str(values.disk);
+    if (values.fixed === true && values.elastic === true)
+        throw new UsageError('--fixed and --elastic cannot be combined');
+    if (held !== undefined && values.fixed === true)
+        throw new UsageError('--held applies to elastic memory (a fixed workspace holds all of its memory)');
+    if (memory !== undefined)
+        p.memoryMib = parsePositiveInt(memory, 'memory', 16_777_216);
+    if (held !== undefined)
+        p.memoryMibHeld = parsePositiveInt(held, 'held', 16_777_216);
+    if (values.fixed === true)
+        p.allocationMode = 'fixed';
+    if (values.elastic === true)
+        p.allocationMode = 'elastic';
+    if (cpu !== undefined)
+        p.cpuMillis = parsePositiveInt(cpu, 'cpu', 1_000_000);
+    if (disk !== undefined)
+        p.diskGib = parsePositiveInt(disk, 'disk', 1_000_000);
+    if (Object.keys(p).length === 0)
+        throw new UsageError('nothing to resize: give --memory, --held, --fixed, --elastic, --cpu or --disk');
+    return p;
+}
 /**
  * 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.
@@ -75,8 +104,9 @@ 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)');
+    // Without --allocation-mode the API decides whether the workspace is elastic (requires_elastic when it is not).
+    if (held !== undefined && mode === 'fixed')
+        throw new UsageError('--memory-held applies to elastic memory (a fixed workspace holds all of --memory-mib)');
     if (mode !== undefined)
         c.allocation_mode = mode;
     if (held !== undefined)
@@ -566,6 +596,35 @@ function treeRevisionAfter(ws, cell) {
  * save-as-template), refused before any request as the SDK's workspace handle does: NotSupportedForModeError, printed
  * with its hint like the API's own refusal.
  */
+/** `<port>` of the port commands: a TCP port number, 1-65535. */
+export function portArg(text) {
+    if (!/^\d{1,5}$/.test(text) || Number(text) < 1 || Number(text) > 65_535)
+        throw new UsageError(`<port> must be a TCP port number between 1 and 65535 (got "${text}")`);
+    return Number(text);
+}
+const PORT_TOKEN_TTL = { option: 'ttl', min: 60, max: 86_400, range: '1m and 24h' };
+const PORT_LINK_TTL = { option: 'ttl', min: 60, max: 604_800, range: '1m and 7d' };
+/** `--ttl <duration>` of port tokens and links: whole seconds within the API's bounds (undefined: the API's default). */
+export function ttlSeconds(values, b) {
+    const text = str(values[b.option]);
+    if (text === undefined)
+        return undefined;
+    const ms = parseDuration(text, b.option);
+    if (ms % 1000 !== 0)
+        throw new UsageError(`--${b.option} must be a whole number of seconds (e.g. 15m, 2h)`);
+    const seconds = ms / 1000;
+    if (seconds < b.min || seconds > b.max)
+        throw new UsageError(`--${b.option} must be between ${b.range} (got "${text}")`);
+    return seconds;
+}
+/** The workspace of a port command; a file-first workspace has no ports (refused before any port request). */
+async function portWorkspace(ctx, ref) {
+    const ws = await resolveWorkspace(ctx, ref);
+    requireProcessful(ws, 'inbound_ports', 'Serving a port');
+    return ws;
+}
+/** A port as the API sends it (`--json`). */
+const portJson = (p) => ({ port: p.port, url: p.url, created_at: p.createdAt, callback: p.callback ? { created_at: p.callback.createdAt } : null });
 function requireProcessful(ws, operation, what) {
     if (ws.mode !== 'file_first')
         return;
@@ -683,6 +742,12 @@ export const KEY_HANDLERS = {
         out(ctx, JSON.stringify(ws.labels, null, 2) + '\n', ws.labels);
         return 0;
     },
+    async 'workspaces hint'(ctx, _values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const result = await ws.cell({ wake: null }).wakeHint(ctx.signal);
+        out(ctx, JSON.stringify(result, null, 2) + '\n', result);
+        return 0;
+    },
     async 'workspaces idle'(ctx, values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
         const policy = str(values.policy);
@@ -702,8 +767,10 @@ export const KEY_HANDLERS = {
     async 'workspaces exec-start'(ctx, values, [ref, ...argv]) {
         const timeout = str(values.timeout);
         const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
+        const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
         const ws = await resolveWorkspace(ctx, ref);
         const session = await cellOf(ctx, ws).exec.start({ argv, stdin_open: values['stdin-open'] === true,
+            ...(resourceHint !== undefined ? { resource_hint: resourceHint } : {}),
             ...(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);
@@ -878,6 +945,7 @@ export const KEY_HANDLERS = {
         const outputLimit = limitText === undefined ? undefined : parsePositiveInt(limitText, 'output-limit', MAX_OUTPUT_LIMIT);
         const stdinSource = str(values.stdin);
         const burst = burstOptions(values, stdinSource !== undefined);
+        const resourceHint = oneOf(values, 'resource-hint', RESOURCE_HINTS);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
         const ws = await resolveWorkspace(ctx, ref);
         const cell = cellOf(ctx, ws);
@@ -885,6 +953,8 @@ export const KEY_HANDLERS = {
         if (ws.mode === 'file_first') {
             if (burst)
                 throw new UsageError(`--burst applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)}`);
+            if (resourceHint)
+                throw new UsageError(`--resource-hint applies to processful workspaces only; ${ws.key} is ${modeText(ws.mode)} (each execution runs in a fresh VM)`);
             // An execution: answered when the command ended. The id is ours, so Ctrl-C can name it.
             const id = executionId ?? newExecutionId();
             let r;
@@ -920,6 +990,7 @@ export const KEY_HANDLERS = {
                 ...(Object.keys(env).length ? { env } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(stdin !== undefined ? { stdin } : {}),
+                ...(resourceHint !== undefined ? { resourceHint } : {}),
                 ...(burst ?? {}),
                 maxOutputBytes: ctx.json ? MAX_JSON_OUTPUT : 0,
                 ...(ctx.json ? {} : { onOutput: (stream, chunk) => void (stream === 'stderr' ? ctx.io.stderr : ctx.io.stdout).write(chunk) }),
@@ -1642,6 +1713,16 @@ export const KEY_HANDLERS = {
         out(ctx, lifecycleText(`Forking ${source.key} into`, res.workspace, op), { operation: op, workspace: res.workspace.data });
         return 0;
     },
+    // Resize (0.9.0+): PATCH /v1/workspaces/{id}/caps through the SDK, which waits until the resize has finished.
+    async 'workspaces resize'(ctx, values, [ref]) {
+        const params = resizeParams(values);
+        const timeoutMs = waitTimeout(values);
+        const ws = await resolveWorkspace(ctx, ref);
+        requireProcessful(ws, 'resize', 'Resize');
+        const r = await waited(ctx, 'the resize continues server side.', () => ws.resize({ ...params, timeoutMs, signal: ctx.signal }));
+        out(ctx, resizeText(ws, r), resizeJson(r));
+        return 0;
+    },
     async 'workspaces sessions'(ctx, _values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
         const sessions = [];
@@ -1654,6 +1735,66 @@ export const KEY_HANDLERS = {
         out(ctx, sessions.length ? sessionTable(sessions) : 'No agent sessions (no tool token was issued for this workspace yet).\n', { data: sessions });
         return 0;
     },
+    // ---- inbound ports (0.9.0; contracts §39.3) ----
+    async 'workspaces port expose'(ctx, _values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        const p = await ws.ports.expose(port);
+        out(ctx, exposedPortText(ws, p), portJson(p));
+        return 0;
+    },
+    async 'workspaces port ls'(ctx, _values, [ref]) {
+        const ws = await portWorkspace(ctx, ref);
+        const ports = await ws.ports.list();
+        out(ctx, portTable(ws, ports), { ports: ports.map(portJson) });
+        return 0;
+    },
+    async 'workspaces port close'(ctx, _values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        await ws.ports.close(port);
+        out(ctx, `Closed port ${port} of ${ws.key} (${ws.id}): its tokens, links and callback URL no longer work.\n`, { workspace_id: ws.id, port, closed: true });
+        return 0;
+    },
+    async 'workspaces port token'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ttl = ttlSeconds(values, PORT_TOKEN_TTL);
+        const ws = await portWorkspace(ctx, ref);
+        const t = await ws.ports.token(port, ttl !== undefined ? { ttlSeconds: ttl } : {});
+        out(ctx, `${t.token}\n`, { token: t.token, expires_at: t.expiresAt, url: t.url });
+        // The token alone on stdout (for $(...)); how to use it on stderr.
+        if (!ctx.json)
+            ctx.io.stderr.write(`Port token for ${t.url}, valid until ${time(t.expiresAt)}: send it as "Authorization: Bearer <token>".\n`);
+        return 0;
+    },
+    async 'workspaces port link'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ttl = ttlSeconds(values, PORT_LINK_TTL);
+        const path = str(values.path);
+        if (path !== undefined && !path.startsWith('/'))
+            throw new UsageError(`--path must start with / (got "${path}")`);
+        const ws = await portWorkspace(ctx, ref);
+        const l = await ws.ports.link(port, { ...(ttl !== undefined ? { ttlSeconds: ttl } : {}), ...(path !== undefined ? { path } : {}) });
+        out(ctx, `${l.url}\n`, { url: l.url, expires_at: l.expiresAt });
+        if (!ctx.json)
+            ctx.io.stderr.write(`Opens port ${port} of ${ws.key} in a browser until ${time(l.expiresAt)}; anyone with the link can open it until then.\n`);
+        return 0;
+    },
+    async 'workspaces port callback'(ctx, values, [ref, portText]) {
+        const port = portArg(portText);
+        const ws = await portWorkspace(ctx, ref);
+        if (values.revoke === true) {
+            await ws.ports.revokeCallbackUrl(port);
+            out(ctx, `Revoked the callback URL of port ${port} of ${ws.key} (${ws.id}).\n`, { workspace_id: ws.id, port, revoked: true });
+            return 0;
+        }
+        const c = await ws.ports.createCallbackUrl(port);
+        out(ctx, `${c.url}\n`, { url: c.url, created_at: c.createdAt });
+        if (!ctx.json) {
+            ctx.io.stderr.write(`Callback URL of port ${port} of ${ws.key}: register it plus your own path (e.g. ${c.url}webhooks/github) with your webhook or OAuth provider; a request to it reaches /<path> of the port without a token. It is shown only now; running this again replaces it, --revoke removes it.\n`);
+        }
+        return 0;
+    },
     async 'workspaces secrets'(ctx, values, [ref]) {
         const set = secretNames(strs(values.set), '--set');
         const clear = values.clear === true;

package/dist/errors.d.ts

@@ -98,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

@@ -147,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) {

package/dist/format.d.ts

@@ -1,5 +1,14 @@
-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 { 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, ResizeResult, ExposePortResult, ExposedPort } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
+/** A workspace as the port commands name it. */
+interface PortWorkspace {
+    key: string;
+    id: string;
+}
+/** `shard ws port expose` (0.9.0): the URL, and how a request gets in. */
+export declare function exposedPortText(w: PortWorkspace, p: ExposePortResult): string;
+/** `shard ws port ls` (0.9.0). */
+export declare function portTable(w: PortWorkspace, ports: readonly ExposedPort[]): string;
 /** 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;
@@ -35,6 +44,17 @@ export declare function suspendWhenIdleText(w: {
     suspend_request: SuspendRequest | null;
     operation: Operation | null;
 }): string;
+/**
+ * `shard ws resize` (0.9.0): per resource the change and when it applies, e.g.
+ * `memory  2048 → 6144 MiB  now` / `cpu     2000 → 4000 millis  next start (boot vCPUs)`, plus what was clamped or
+ * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
+ */
+export declare function resizeText(w: {
+    key: string;
+    id: string;
+}, r: ResizeResult): string;
+/** `shard ws resize --json`: the API's result (only the resources the request named), the stored caps, and the operation when one was waited for. */
+export declare function resizeJson(r: ResizeResult): Record<string, unknown>;
 /** `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`. */

package/dist/format.js

@@ -4,6 +4,18 @@
  * these functions only shape what people read.
  */
 import { durabilityOf, isDurable } from '@shardflux/sdk';
+/** `shard ws port expose` (0.9.0): the URL, and how a request gets in. */
+export function exposedPortText(w, p) {
+    return (`${p.created ? `Exposed port ${p.port} of ${w.key} (${w.id})` : `Port ${p.port} of ${w.key} (${w.id}) is exposed`}: ${p.url}\n` +
+        `Requests need a token (shard ws port token ${w.key} ${p.port}), a browser link (shard ws port link ${w.key} ${p.port}) or the callback URL (shard ws port callback ${w.key} ${p.port}).\n` +
+        `The server in the workspace listens on 0.0.0.0:${p.port}.\n`);
+}
+/** `shard ws port ls` (0.9.0). */
+export function portTable(w, ports) {
+    if (ports.length === 0)
+        return `No ports of ${w.key} (${w.id}) are exposed; expose one with: shard ws port expose ${w.key} <port>\n`;
+    return table(['PORT', 'URL', 'EXPOSED', 'CALLBACK URL'], ports.map((p) => [String(p.port), p.url, time(p.createdAt), p.callback ? `created ${time(p.callback.createdAt)}` : '-']));
+}
 /** 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`;
@@ -133,6 +145,55 @@ export function suspendWhenIdleText(w, r) {
     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`);
+const APPLIES_AT = { now: 'now', resume: 'on resume', next_start: 'next start' };
+const LIMIT_TEXT = { plan: 'plan limit', template: 'template limit', host_capacity: 'host capacity', shrink_stalled: 'the guest kept memory in use' };
+/** Why a resource applies later; `suspended` and `stopped` are what `on resume` / `next start` already say. */
+const deferText = (r) => (r === null || r === 'suspended' || r === 'stopped' ? '' : r === 'boot_vcpus' ? ' (boot vCPUs)' : ` (${r.replace(/_/g, ' ')})`);
+/**
+ * `shard ws resize` (0.9.0): per resource the change and when it applies, e.g.
+ * `memory  2048 → 6144 MiB  now` / `cpu     2000 → 4000 millis  next start (boot vCPUs)`, plus what was clamped or
+ * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
+ */
+export function resizeText(w, r) {
+    const rows = [];
+    const row = (name, unit, x, extra = '', converged = null) => {
+        const notes = [];
+        if (x.requested !== null && x.target !== null && x.requested !== x.target)
+            notes.push(`requested ${x.requested} ${unit}${x.limit === 'plan' || x.limit === 'template' ? `, ${LIMIT_TEXT[x.limit]}` : ''}`);
+        if (x.applies_at === 'now' && x.applied !== null && x.applied !== x.target)
+            notes.push(`${x.applied} ${unit} applied${x.limit === 'host_capacity' || x.limit === 'shrink_stalled' ? `: ${LIMIT_TEXT[x.limit]}` : ''}`);
+        else if (converged === false)
+            notes.push('not converged');
+        rows.push([name, `${x.previous ?? '-'} → ${x.target ?? '-'} ${unit}${extra}`, `${APPLIES_AT[x.applies_at]}${deferText(x.reason)}${notes.length ? `; ${notes.join('; ')}` : ''}`]);
+    };
+    const m = r.memory;
+    if (m) {
+        const extra = m.allocation_mode === 'elastic' ? ` elastic${m.held_mib !== null ? `, held ${m.held_mib} MiB` : ''}` : '';
+        row('memory', 'MiB', { applies_at: m.applies_at, requested: m.requested_mib, target: m.target_mib, previous: m.previous_mib, applied: m.applied_mib, limit: m.limit_reason, reason: m.reason }, extra, m.converged);
+    }
+    const c = r.cpu;
+    if (c)
+        row('cpu', 'millis', { applies_at: c.applies_at, requested: c.requested_millis, target: c.target_millis, previous: c.previous_millis, applied: c.applied_millis, limit: c.limit_reason, reason: c.reason });
+    const d = r.disk;
+    if (d)
+        row('disk', 'GiB', { applies_at: d.applies_at, requested: d.requested_gib, target: d.target_gib, previous: d.previous_gib, applied: d.applied_gib, limit: d.limit_reason, reason: d.reason });
+    const width = Math.max(0, ...rows.map(([, change]) => change.length));
+    const lines = rows.map(([name, change, when]) => `${name.padEnd(6)}  ${change.padEnd(width)}  ${when}`);
+    return `Resized ${w.key} (${w.id}), ${r.state}:\n${lines.map((l) => `${l}\n`).join('')}`;
+}
+/** `shard ws resize --json`: the API's result (only the resources the request named), the stored caps, and the operation when one was waited for. */
+export function resizeJson(r) {
+    return {
+        workspace_id: r.workspaceId,
+        operation_id: r.operationId,
+        state: r.state,
+        ...(r.memory ? { memory: r.memory } : {}),
+        ...(r.cpu ? { cpu: r.cpu } : {}),
+        ...(r.disk ? { disk: r.disk } : {}),
+        caps: r.caps,
+        ...(r.operation ? { operation: r.operation } : {}),
+    };
+}
 /** `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')
@@ -396,6 +457,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)]);

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";

package/dist/main.js

@@ -76,6 +76,11 @@ function hintFor(info, cred, file) {
         return 'this API has no billing configured: plans cannot be bought here';
     if (info.code === 'allowance_exhausted')
         return allowanceHint(info);
+    if (info.code === 'quota_exceeded') {
+        const quota = quotaHint(info);
+        if (quota)
+            return quota;
+    }
     const policyHint = spendPolicyHint(info);
     if (policyHint)
         return policyHint;
@@ -99,6 +104,11 @@ function hintFor(info, cred, file) {
         return 'the workspace cannot be woken right now and the call did not run; retry in a few seconds';
     if (reason === 'host_feature_unavailable')
         return hostFeatureHint(info.details?.feature);
+    // Inbound ports (0.9.0): the next step names the command.
+    if (reason === 'port_not_exposed')
+        return `expose it first: shard ws port expose <id|key> ${typeof info.details?.port === 'number' ? info.details.port : '<port>'}`;
+    if (reason === 'port_limit')
+        return 'close a port first (shard ws port ls <id|key>, then shard ws port close <id|key> <port>)';
     // A processful command that could not start (0.5.1): what to change, from the workspace's reason.
     if (info.code === 'conflict' && reason === 'exec_failed_to_start')
         return startFailureHint(typeof info.details?.error === 'string' ? info.details.error : info.message, false);
@@ -135,6 +145,21 @@ function allowanceHint(info) {
             return undefined;
     }
 }
+/**
+ * quota_exceeded (0.9.0): the cell gateway's 429 when every workspace the plan allows to work at once is busy (the SDK
+ * already retried it after Retry-After), and the API's 403 when the plan's Retained state is used up (new keys and
+ * forks are refused). Other limits keep the API's message alone.
+ */
+function quotaHint(info) {
+    const limit = info.details?.limit;
+    if (limit === 'concurrent_workspaces' && info.status === 429) {
+        const s = info.retry_after_seconds;
+        return `every workspace your plan allows to work at once is busy and the call did not run (it was already retried); retry ${typeof s === 'number' ? `in ${s} s` : 'in a few seconds'}, or upgrade: shard billing plans`;
+    }
+    if (limit === 'retained_state')
+        return 'delete workspaces you no longer need (shard ws delete <key> --yes), or upgrade: shard billing plans';
+    return undefined;
+}
 /** Dollars for a hint: `9` for 900 minor units, `9.50` for 950. */
 const dollars = (minor) => (typeof minor === 'number' ? (minor % 100 === 0 ? String(minor / 100) : (minor / 100).toFixed(2)) : undefined);
 /**
@@ -292,6 +317,9 @@ const NO_NUDGE_REASONS = new Set([
     'version_mismatch',
     // A write under an immutable path (0.8.0): the hint says where to change it.
     'read_only_path',
+    // Inbound ports (0.9.0): the hint names the command to expose or close a port.
+    'port_not_exposed',
+    'port_limit',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback
@@ -300,6 +328,9 @@ const NO_NUDGE_REASONS = new Set([
 function nudges(info, command) {
     if (command === undefined || command === 'feedback')
         return false;
+    // A plan limit whose hint names the next step (0.9.0): busy working slots, or Retained state used up.
+    if (info.code === 'quota_exceeded' && quotaHint(info) !== undefined)
+        return false;
     const reason = reasonOf(info);
     return !NO_NUDGE_CODES.has(info.code) && !(reason !== undefined && NO_NUDGE_REASONS.has(reason));
 }

package/dist/timing.d.ts

@@ -15,6 +15,12 @@ export declare class TimingRecorder {
      * --wait`, an `operations wait` of that resume, or a command's wake. `lostSuspendNotice()` says it.
      */
     lostSuspend: LifecycleTiming | null;
+    /**
+     * (0.8.1+) The last traced resume that restored the workspace's newest checkpoint after the machine it ran on failed
+     * (`host_lost.restored_from` `checkpoint`): a `ws resume --wait`, an `operations wait` of that resume, or a command's
+     * wake. `hostLostNotice()` says it. A restore from the disk is a cold boot (`coldBootNotice()`).
+     */
+    hostLost: LifecycleTiming | 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
@@ -24,15 +30,21 @@ export declare class TimingRecorder {
 }
 /**
  * The one-line stderr notice after a command whose resume booted the workspace's saved disk (0.6.0+), with or without
- * `--timing`: the workspace runs and its files are as of the suspend, but running processes were restarted.
+ * `--timing`: the workspace runs with its files kept, but running processes were restarted. The reason follows in
+ * parentheses: `runtime_changed`, or in words for `host_lost` (0.8.1+).
  */
 export declare function coldBootNotice(t: LifecycleTiming): string;
+/**
+ * The one-line stderr notice after a command whose resume restored the workspace's newest checkpoint after the machine
+ * it ran on failed (0.8.1+; `host_lost.restored_from` `checkpoint`): the state is as of `state_as_of`.
+ */
+export declare function hostLostNotice(t: LifecycleTiming): string;
 /**
  * The one-line stderr notice after a command whose resume restored an earlier checkpoint because the latest suspend
  * could not be kept (0.7.0+; `lost_suspend`): the state the workspace runs with is as of `state_as_of`.
  */
 export declare function lostSuspendNotice(t: LifecycleTiming): string;
-/** The notices a command's traced calls leave on stderr (cold boot, lost suspend), in that order. */
+/** The notices a command's traced calls leave on stderr (cold boot, lost suspend, host loss), in that order. */
 export declare function notices(r: TimingRecorder): string;
 /** The human form (stderr): formatTiming() of the SDK, one block. */
 export declare function timingText(t: LifecycleTiming): string;

package/dist/timing.js

@@ -23,6 +23,12 @@ export class TimingRecorder {
      * --wait`, an `operations wait` of that resume, or a command's wake. `lostSuspendNotice()` says it.
      */
     lostSuspend = null;
+    /**
+     * (0.8.1+) The last traced resume that restored the workspace's newest checkpoint after the machine it ran on failed
+     * (`host_lost.restored_from` `checkpoint`): a `ws resume --wait`, an `operations wait` of that resume, or a command's
+     * wake. `hostLostNotice()` says it. A restore from the disk is a cold boot (`coldBootNotice()`).
+     */
+    hostLost = null;
     listener = (e) => {
         if (e.action === 'token' || e.action === 'tool')
             return;
@@ -35,6 +41,8 @@ export class TimingRecorder {
             this.coldBoot = e.timing;
         if (e.timing.server?.lostSuspend)
             this.lostSuspend = e.timing;
+        if (e.timing.server?.hostLost?.restoredFrom === 'checkpoint')
+            this.hostLost = e.timing;
     };
     /**
      * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
@@ -49,13 +57,29 @@ export class TimingRecorder {
 function restartedProcesses(t) {
     return t.server?.resumePath === 'cold_boot' && t.server.memoryRestored === false;
 }
+/** Cold boot reasons the notice says in words (0.8.1+); any other reason is printed as the API sent it. */
+const COLD_BOOT_WORDS = {
+    host_lost: 'the machine it ran on failed',
+};
 /**
  * The one-line stderr notice after a command whose resume booted the workspace's saved disk (0.6.0+), with or without
- * `--timing`: the workspace runs and its files are as of the suspend, but running processes were restarted.
+ * `--timing`: the workspace runs with its files kept, but running processes were restarted. The reason follows in
+ * parentheses: `runtime_changed`, or in words for `host_lost` (0.8.1+).
  */
 export function coldBootNotice(t) {
     const reason = t.server?.coldBootReason;
-    return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from its saved disk; running processes were restarted${reason ? ` (${reason})` : ''}\n`;
+    const why = reason ? (COLD_BOOT_WORDS[reason] ?? reason) : null;
+    return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from its saved disk; running processes were restarted${why ? ` (${why})` : ''}\n`;
+}
+/**
+ * The one-line stderr notice after a command whose resume restored the workspace's newest checkpoint after the machine
+ * it ran on failed (0.8.1+; `host_lost.restored_from` `checkpoint`): the state is as of `state_as_of`.
+ */
+export function hostLostNotice(t) {
+    const h = t.server?.hostLost;
+    if (h?.restoredFrom !== 'checkpoint')
+        return '';
+    return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from checkpoint ${h.restoredCheckpointId ?? '-'}${h.stateAsOf ? ` (state as of ${h.stateAsOf})` : ''} after the machine it ran on failed; changes after that time are not in it\n`;
 }
 /**
  * The one-line stderr notice after a command whose resume restored an earlier checkpoint because the latest suspend
@@ -67,9 +91,9 @@ export function lostSuspendNotice(t) {
         return '';
     return `note: ${t.workspaceId ? `workspace ${t.workspaceId} ` : ''}resumed from checkpoint ${l.restoredCheckpointId ?? '-'}${l.stateAsOf ? ` (state as of ${l.stateAsOf})` : ''}; the suspend of ${l.suspendedAt ?? l.checkpointId} was not kept${l.reason ? ` (${l.reason})` : ''}\n`;
 }
-/** The notices a command's traced calls leave on stderr (cold boot, lost suspend), in that order. */
+/** The notices a command's traced calls leave on stderr (cold boot, lost suspend, host loss), in that order. */
 export function notices(r) {
-    return `${r.coldBoot ? coldBootNotice(r.coldBoot) : ''}${r.lostSuspend ? lostSuspendNotice(r.lostSuspend) : ''}`;
+    return `${r.coldBoot ? coldBootNotice(r.coldBoot) : ''}${r.lostSuspend ? lostSuspendNotice(r.lostSuspend) : ''}${r.hostLost ? hostLostNotice(r.hostLost) : ''}`;
 }
 /** The human form (stderr): formatTiming() of the SDK, one block. */
 export function timingText(t) {
@@ -126,6 +150,15 @@ export function timingJson(t) {
                         state_as_of: s.lostSuspend.stateAsOf,
                     }
                     : null,
+                // 0.8.1+: the machine the workspace ran on failed (resume: what it restored; suspend: detected_at only).
+                host_lost: s.hostLost
+                    ? {
+                        detected_at: s.hostLost.detectedAt,
+                        restored_from: s.hostLost.restoredFrom,
+                        restored_checkpoint_id: s.hostLost.restoredCheckpointId,
+                        state_as_of: s.hostLost.stateAsOf,
+                    }
+                    : null,
                 boot_to_ready_ms: s.bootToReadyMs,
                 host_timings_ms: s.hostTimingsMs,
             }

package/package.json

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