@shardflux/cli 0.6.1 → 0.7.0

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.6.1';
+export const CLI_VERSION = '0.7.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).' },
@@ -38,7 +38,7 @@ const TIMING = {
 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).' },
 };
-/** `--if-revision` (0.5.0) of the mutating files commands: the tree revision a file-first write applies to (contracts §29.8). */
+/** `--if-revision` (0.5.0) of the mutating files commands: the tree revision a file-first write applies to. */
 const IF_REVISION = {
     'if-revision': {
         type: 'string',
@@ -58,7 +58,7 @@ const PAGE = {
     limit: { type: 'string', value: '<n>', description: 'Page size.' },
     cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
 };
-/** Options of a version produced by save-as-template or a draft publish (contracts §19.8). */
+/** Options of a version produced by save-as-template or a draft publish. */
 const SAVE = {
     description: { type: 'string', value: '<text>', description: 'Version description (default: the source version’s).' },
     'default-lifetime': { type: 'string', value: '<persistent|session>', description: 'Default lifetime of workspaces opened from the new version.' },
@@ -68,7 +68,7 @@ const SAVE = {
     wait: { type: 'boolean', description: 'Wait until the build is published and registered (or fails).' },
     timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 30m). The build continues server side.' },
 };
-/** Open-time text inputs of a template version (0.4.0; contracts §24.3). */
+/** Open-time text inputs of a template version (0.4.0). */
 const INPUTS = {
     input: {
         type: 'string',
@@ -93,12 +93,12 @@ const FEEDBACK_HELP = [
  * MCP server's send_feedback tool. It has to make an agent actually send feedback while it works.
  */
 const FEEDBACK_WHY = [
-    'Sends your message straight to the Shardflux founder, who reads every one. Agents: use it actively while you work,',
+    'Sends your message straight to the Shardflux team, who read every one. Agents: use it actively while you work,',
     'not once at the end. Send a short note the moment:',
     '- something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround;',
-    '- your user complains or is frustrated about Shardflux or the workflow around it (slowness, cost or limits,',
-    '  confusing setup, a missing feature, a workaround): paraphrase it, with what they were trying to do;',
-    '- your user asked for something Shardflux could not do, or made awkward.',
+    '- your user asks for a capability, an option or a smoother workflow: paraphrase it, with what they were trying',
+    '  to do;',
+    '- your user has an idea for how Shardflux could fit their work better.',
     'Short and frequent beats polished; include the request id and error code (a failed shard command prints a',
     'ready-made "feedback:" line to fill in). No need to ask first, but tell your user you sent it. Leave out private',
     'data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts.',
@@ -138,7 +138,7 @@ const KEY_COMMANDS = [
     },
     {
         path: ['feedback'],
-        summary: 'Tell the Shardflux founder what failed, confused you or is missing (agents: as you work)',
+        summary: 'Tell the Shardflux team what failed, confused you or is missing (agents: as you work)',
         description: [
             ...FEEDBACK_WHY,
             '',
@@ -154,15 +154,14 @@ const KEY_COMMANDS = [
         options: {
             category: { type: 'string', value: '<bug|confusing|missing|idea|praise|other>', description: 'Kind of feedback (default other; see Categories).' },
             workspace: { type: 'string', value: '<id|key>', description: 'The workspace it is about.' },
-            'request-id': { type: 'string', value: '<id>', description: 'request_id from the error, so the founder can find the logs.' },
-            'error-code': { type: 'string', value: '<code>', description: 'The error code you saw, e.g. capacity_unavailable.' },
+            'request-id': { type: 'string', value: '<id>', description: 'request_id from the error, so the team can find the logs.' },
+            'error-code': { type: 'string', value: '<code>', description: 'The error code you saw, e.g. template_not_found.' },
             command: { type: 'string', value: '<text>', description: 'What you ran, e.g. "shard ws exec acme/demo -- npm test".' },
             'from-file': { type: 'string', value: '<file|->', description: 'Read the message from this file, or - for standard input (long reports, logs); instead of <message...>.' },
         },
         examples: [
-            'shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code capacity_unavailable "ws open failed twice in 10 min; expected a start within a minute"',
-            'shard feedback --category confusing --command "shard ws exec acme/demo -- npm test" exit 137 with no message, took a while to see it was the memory cap',
-            'shard feedback --category missing no way to copy a file between two workspaces, piped files read into files write instead',
+            'shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code template_not_found "ws open --template python-node failed; expected a suggestion of the closest slug"',
+            'shard feedback --category idea "user would like shard ws open to remember the last template they used"',
             'npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo --from-file -',
         ],
     },
@@ -190,6 +189,8 @@ const KEY_COMMANDS = [
         positionals: [{ name: 'key', required: true }],
         options: {
             template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
+            labels: { type: 'string', value: '<json>', description: 'Replace workspace labels with a JSON object of strings.' },
+            'idle-policy': { type: 'string', value: '<policy>', description: 'adaptive, never or fixed:<seconds>.' },
             secret: {
                 type: 'string',
                 multiple: true,
@@ -229,6 +230,7 @@ const KEY_COMMANDS = [
         options: {
             state: { type: 'string', value: '<state>', description: 'Observed state filter (running, suspended, creating, ...).' },
             prefix: { type: 'string', value: '<key-prefix>', description: 'Only keys starting with this prefix.' },
+            labels: { type: 'string', value: '<json>', description: 'Exact label matches (JSON object; all pairs must match).' },
             ...LIFETIME_FILTER,
             'include-deleted': { type: 'boolean', description: 'Include deleted workspaces and ended sessions (tombstones).' },
             all: { type: 'boolean', description: 'Fetch every page.' },
@@ -236,12 +238,28 @@ const KEY_COMMANDS = [
             cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
         },
     },
+    { path: ['workspaces', 'labels'], summary: 'Read or replace workspace labels', positionals: [REF], options: {
+            set: { type: 'string', value: '<json>', description: 'Replace all labels; {} clears them.' },
+        } },
+    { path: ['workspaces', 'idle'], summary: 'Inspect idle status, set policy or declare a keepalive', positionals: [REF], options: {
+            policy: { type: 'string', value: '<policy>', description: 'adaptive, never, fixed:<seconds>, or default to clear the override.' },
+            keepalive: { type: 'string', value: '<seconds>', description: 'Declare ongoing work for this many seconds.' },
+        } },
+    { path: ['workspaces', 'exec-start'], summary: 'Start a background exec session with optional pipe stdin', positionals: [REF, { name: 'command', required: true, variadic: true }], options: {
+            'stdin-open': { type: 'boolean', description: 'Keep pipe stdin open for exec-input.' },
+            'session-id': { type: 'string', value: '<id>', description: 'Caller-chosen id to deduplicate starts.' },
+            cwd: { type: 'string', value: '<dir>', description: 'Absolute working directory.' },
+        } },
+    { path: ['workspaces', 'exec-input'], summary: 'Write pipe stdin at its acknowledged byte offset', positionals: [REF, { name: 'session-id', required: true }, { name: 'data' }], options: {
+            offset: { type: 'string', value: '<bytes>', description: 'Required acknowledged offset (0 initially).' },
+            close: { type: 'boolean', description: 'Send EOF after these bytes are accepted.' },
+        } },
     { path: ['workspaces', 'get'], summary: 'Show one workspace (state, template, startup)', positionals: [REF], options: {} },
     { path: ['workspaces', 'inputs'], summary: 'Show the text inputs of a workspace (secret inputs are bound secrets: shard ws secrets)', positionals: [REF], options: {} },
     {
         path: ['workspaces', 'exec'],
         summary: 'Run a command in a workspace; prints its output and exits with its exit code',
-        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution cannot be canceled: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
+        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution runs to completion: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
             cwd: { type: 'string', value: '<dir>', description: 'Working directory, an absolute path (default /home/user; under /home/user on a file-first workspace). A relative path is refused (invalid_cwd).' },
@@ -270,15 +288,16 @@ const KEY_COMMANDS = [
     },
     {
         path: ['workspaces', 'suspend'],
-        summary: 'Suspend a running workspace (durable checkpoint), now or once it has been idle',
-        description: 'Without options the suspend is requested now. --when-idle (0.5.1+) defers it instead: the workspace is suspended once it has been idle for that long, counted from the later of its last work and the request, so call it when an agent turn ends. A command still running, an attached exec or terminal stream, or a keepalive postpones it; the next tool call (the next turn) or a resume cancels it. Repeating replaces the pending request. --cancel-when-idle cancels it.',
+        summary: 'Suspend a running workspace (memory and processes checkpointed), now or once it has been idle',
+        description: 'Without options the suspend is requested now. With --wait it returns as soon as the workspace is sealed on its host, typically in a few hundred ms; the result\'s durable turns true when the copy lands in durable storage, typically within a second. --durable (0.7.0+) waits for that too. --when-idle (0.5.1+) defers it instead: the workspace is suspended once it has been idle for that long, counted from the later of its last work and the request, so call it when an agent turn ends. A command still running, an attached exec or terminal stream, or a keepalive postpones it; the next tool call (the next turn) or a resume cancels it. Repeating replaces the pending request. --cancel-when-idle cancels it.',
         positionals: [REF],
         options: {
             'when-idle': { type: 'string', value: '<duration>', description: 'Suspend once the workspace has been idle this long (0.5.1+; 0 to 1h, e.g. 0, 30s, 2m; 0 = as soon as it is idle, 0.6.1+). Cannot be combined with --wait.' },
             'cancel-when-idle': { type: 'boolean', description: 'Cancel a pending --when-idle request (0.5.1+; idempotent).' },
+            durable: { type: 'boolean', description: 'Wait until the suspend is in durable storage (result durable: true; 0.7.0+). Implies --wait and shares its --timeout.' },
             ...WAIT,
         },
-        examples: ['shard ws suspend acme/demo --wait', 'shard ws suspend acme/demo --when-idle 2m', 'shard ws suspend acme/demo --cancel-when-idle'],
+        examples: ['shard ws suspend acme/demo --wait', 'shard ws suspend acme/demo --durable', 'shard ws suspend acme/demo --when-idle 2m', 'shard ws suspend acme/demo --cancel-when-idle'],
     },
     { path: ['workspaces', 'resume'], summary: 'Resume a suspended workspace', positionals: [REF], options: { ...WAIT } },
     {
@@ -519,7 +538,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'init'],
         summary: 'Write a template.yaml that starts from a base template',
-        description: 'The file is the recipe v2 document (contracts §24.1): languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
+        description: 'The file is the recipe v2 document: languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
         positionals: [],
         options: {
             base: { type: 'string', value: '<slug[@version]>', description: 'Base template (required), e.g. ubuntu-24.04; without @version, the version open resolves to now.' },
@@ -696,7 +715,11 @@ const KEY_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).' }, ...TIMING },
+        options: {
+            timeout: { type: 'string', value: '<duration>', description: 'Give up after this long (default 5m).' },
+            durable: { type: 'boolean', description: 'A suspend or fork: also wait until its copy is in durable storage (result durable: true; 0.7.0+).' },
+            ...TIMING,
+        },
     },
 ];
 /** Every command: the account plane first (sign in, set up), then the project-key commands. */
@@ -1058,8 +1081,8 @@ export function topHelp() {
         '',
         'Feedback: shard feedback [options] <message...>',
         ...FEEDBACK_WHY.map((l) => `  ${l}`),
-        '  shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 "ws open waited 40 s in capacity_pending; expected under 5 s"',
-        '  shard feedback --category confusing "user was frustrated that ws open needs a template slug they had to look up; they expected a default"',
+        '  shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code template_not_found "ws open --template python-node failed; expected a suggestion of the closest slug"',
+        '  shard feedback --category idea "user would like shard ws open to remember the last template they used"',
         '',
         'Start here (everything the web app does, from a terminal; a person only opens the emailed link and pays in Checkout):',
         `  printf '%s\\n' "$PASSWORD" | shard auth register --email you@example.com`,

package/dist/browser.js

@@ -1,5 +1,5 @@
 /**
- * `--open` (0.5.0+): opens a URL in the default browser, best effort. The URL is always printed as well, so a
+ * `--open` (0.5.0+): opens a URL in the default browser when it can. The URL is always printed as well, so a
  * failure to open changes nothing: no error, no exit code. $BROWSER (a program run with the URL as its only argument)
  * wins; otherwise `open` (macOS), `rundll32 url.dll,FileProtocolHandler` (Windows) or `xdg-open` (elsewhere).
  */

package/dist/commands.d.ts

@@ -70,13 +70,13 @@ export type Handler = (ctx: Ctx, values: Values, positionals: string[]) => Promi
 export declare const str: (v: Values[string]) => string | undefined;
 export declare const strs: (v: Values[string]) => string[];
 export declare function out(ctx: Ctx, human: string, machine: unknown): void;
-/** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds, contracts §20.6). */
+/** `--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 declare function whenIdleSeconds(text: string): number;
 export declare function waitTimeout(values: Values): number;
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
  * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live
- * workspace over tombstones of ended sessions that had the same key (contracts §19.11).
+ * workspace over tombstones of ended sessions that had the same key.
  */
 export declare function resolveWorkspace(ctx: Ctx, ref: string): Promise<Workspace>;
 export declare function oneOf<T extends string>(values: Values, option: string, allowed: readonly T[]): T | undefined;

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, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, 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, 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;
@@ -30,10 +30,10 @@ export const str = (v) => (typeof v === 'string' ? v : undefined);
 const cellOf = (ctx, ws) => ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs, ...(ctx.wake ? {} : { wake: null }) });
 export const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
 const MAX_SECRET_VALUE_BYTES = 65_536;
-/** `files patch --content-file`: a patch request is at most 7 MiB (contracts §26.2); larger files go through `files write`. */
+/** `files patch --content-file`: a patch request is at most 7 MiB; larger files go through `files write`. */
 const MAX_PATCH_CONTENT = 7 * 1024 * 1024;
 const STOPPED_AT = { max_matches: '--max matches', budget: 'its 10 s budget', max_bytes: '4 MiB of results' };
-/** A file revision (SHA-256 of the content) or `absent` (contracts §26.2). */
+/** A file revision (SHA-256 of the content) or `absent`. */
 const REVISION = /^([0-9a-f]{64}|absent)$/;
 const TOOLS = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
 function secretNames(names, option) {
@@ -66,7 +66,7 @@ function caps(values) {
         c.disk_gib = parsePositiveInt(disk, 'disk-gib', 1_000_000);
     return Object.keys(c).length ? c : undefined;
 }
-/** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds, contracts §20.6). */
+/** `--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()))
         return 0;
@@ -85,7 +85,7 @@ export function waitTimeout(values) {
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
  * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live
- * workspace over tombstones of ended sessions that had the same key (contracts §19.11).
+ * workspace over tombstones of ended sessions that had the same key.
  */
 export async function resolveWorkspace(ctx, ref) {
     const cloud = ctx.cloud();
@@ -192,7 +192,7 @@ export function parseSlugVersion(text, what) {
 }
 const INPUT_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 /**
- * Open-time text inputs (contracts §24.3) from --input-file (NAME=value lines with # comments, or a JSON object of
+ * Open-time text inputs from --input-file (NAME=value lines with # comments, or a JSON object of
  * strings), then each --input NAME=value (a later one wins). Undefined when neither option is given.
  */
 async function inputsFrom(ctx, values) {
@@ -417,7 +417,7 @@ export function execExitCode(r) {
 async function bestEffortCancel(cell, sessionId) {
     await Promise.race([cell.exec.cancel(sessionId).catch(() => undefined), new Promise((r) => setTimeout(r, 3_000).unref())]);
 }
-// ---- File-first workspaces (0.5.0; contracts §29) ----------------------------------------------------------------------
+// ---- File-first workspaces (0.5.0) ----------------------------------------------------------------------
 const MODES = { processful: 'processful', 'file-first': 'file_first', file_first: 'file_first' };
 /** `--mode processful|file-first` (`file_first` too). */
 function modeFlag(values) {
@@ -452,7 +452,7 @@ function treeRevisionAfter(ws, cell) {
     return cell.treeRevision ?? ws.treeRevision;
 }
 /**
- * A lifecycle call a file-first workspace does not have (contracts §29.7: suspend, resume, fork, reset,
+ * A lifecycle call a file-first workspace does not have (suspend, resume, fork, reset,
  * 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.
  */
@@ -496,7 +496,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 ? '' : `wait with: shard operations wait ${op.id}\n`}`;
+    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`}`;
 }
 /** The project-key commands; handlers.ts adds the account plane's. */
 export const KEY_HANDLERS = {
@@ -519,7 +519,7 @@ export const KEY_HANDLERS = {
         out(ctx, `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n${line}`, { cli: CLI_VERSION, sdk: SDK_VERSION, update });
         return 0;
     },
-    // Feedback (0.5.0+): POST /v1/feedback, emailed to the founder. Validated here first so a bad call costs no request.
+    // Feedback (0.5.0+): POST /v1/feedback, emailed to the Shardflux team. Validated here first so a bad call costs no request.
     async feedback(ctx, values, words) {
         const category = oneOf(values, 'category', FEEDBACK_CATEGORIES);
         const context = feedbackContext(ctx, values);
@@ -527,7 +527,7 @@ export const KEY_HANDLERS = {
         const r = await feedbackSender(ctx).sendFeedback({ message, ...(category ? { category } : {}), context });
         const human = r.duplicate
             ? `Already received: the same message was sent in the last 24 hours (feedback ${r.id}); not emailed again.\n`
-            : `Sent to the Shardflux founder (feedback ${r.id}). Thank you.\n`;
+            : `Sent to the Shardflux team (feedback ${r.id}). Thank you.\n`;
         out(ctx, human, { id: r.id, received_at: r.receivedAt, duplicate: r.duplicate });
         return 0;
     },
@@ -565,6 +565,46 @@ export const KEY_HANDLERS = {
         out(ctx, usageText(summary), summary);
         return 0;
     },
+    async 'workspaces labels'(ctx, values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const labels = labelMap(str(values.set));
+        if (labels !== undefined)
+            await ws.setLabels(labels);
+        out(ctx, JSON.stringify(ws.labels, null, 2) + '\n', ws.labels);
+        return 0;
+    },
+    async 'workspaces idle'(ctx, values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const policy = str(values.policy);
+        const keepalive = str(values.keepalive);
+        if (policy !== undefined && keepalive !== undefined)
+            throw new UsageError('--policy and --keepalive cannot be combined');
+        let result;
+        if (policy !== undefined)
+            result = (await ws.setIdlePolicy(policy === 'default' ? null : policy)).data;
+        else if (keepalive !== undefined)
+            result = await ws.keepalive(parsePositiveInt(keepalive, 'keepalive', 86400));
+        else
+            result = await ws.idle(ctx.signal);
+        out(ctx, JSON.stringify(result, null, 2) + '\n', result);
+        return 0;
+    },
+    async 'workspaces exec-start'(ctx, values, [ref, ...argv]) {
+        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);
+        out(ctx, JSON.stringify(session, null, 2) + '\n', session);
+        return 0;
+    },
+    async 'workspaces exec-input'(ctx, values, [ref, sessionId, data]) {
+        const offset = Number(str(values.offset));
+        if (str(values.offset) === undefined || !Number.isSafeInteger(offset) || offset < 0)
+            throw new UsageError('--offset must be a non-negative integer');
+        const ws = await resolveWorkspace(ctx, ref);
+        const ack = await cellOf(ctx, ws).exec.input(sessionId, data ?? '', { offset, close: values.close === true, signal: ctx.signal });
+        out(ctx, JSON.stringify(ack) + '\n', ack);
+        return 0;
+    },
     async 'workspaces open'(ctx, values, [key]) {
         const template = str(values.template);
         if (!template)
@@ -583,6 +623,8 @@ export const KEY_HANDLERS = {
         const ws = await waited(ctx, 'the open continues server side (open the key again to keep waiting).', () => cloud.workspaces.open({
             key: key,
             template,
+            ...(str(values.labels) !== undefined ? { labels: labelMap(str(values.labels)) } : {}),
+            ...(str(values['idle-policy']) ? { idlePolicy: str(values['idle-policy']) } : {}),
             ...(c ? { caps: c } : {}),
             ...(bind.length ? { secrets: bind } : {}),
             ...(inputs ? { inputs } : {}),
@@ -609,6 +651,7 @@ export const KEY_HANDLERS = {
         const params = {
             ...(state ? { state: state } : {}),
             ...(prefix ? { keyPrefix: prefix } : {}),
+            ...(str(values.labels) !== undefined ? { labels: labelMap(str(values.labels)) } : {}),
             ...(lifetime ? { lifetime } : {}),
             ...(purpose ? { purpose } : {}),
             ...(values['include-deleted'] === true ? { includeDeleted: true } : {}),
@@ -661,7 +704,7 @@ export const KEY_HANDLERS = {
         const cell = cellOf(ctx, ws);
         const cwd = str(values.cwd);
         if (ws.mode === 'file_first') {
-            // An execution (contracts §29.8): answered when the command ended. The id is ours, so Ctrl-C can name it.
+            // An execution: answered when the command ended. The id is ours, so Ctrl-C can name it.
             const id = executionId ?? newExecutionId();
             let r;
             try {
@@ -677,7 +720,7 @@ export const KEY_HANDLERS = {
             }
             catch (err) {
                 if (ctx.signal.aborted) {
-                    throw new InterruptedError(`Interrupted; execution ${id} keeps running server side if it started (an execution cannot be canceled).`, undefined, {
+                    throw new InterruptedError(`Interrupted; execution ${id} keeps running server side if it started (an execution runs to completion).`, undefined, {
                         executionId: id,
                         hint: `fetch its result later with: shard executions get ${ref} ${id}`,
                     });
@@ -854,8 +897,12 @@ export const KEY_HANDLERS = {
     async 'workspaces suspend'(ctx, values, [ref]) {
         const whenIdle = str(values['when-idle']);
         const cancel = values['cancel-when-idle'] === true;
-        if (whenIdle === undefined && !cancel)
-            return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, o), ['suspend', 'Suspend']);
+        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']);
+        }
+        if (durable)
+            throw new UsageError(`${whenIdle !== undefined ? '--when-idle' : '--cancel-when-idle'} cannot be combined with --durable (nothing is suspended now)`);
         if (whenIdle !== undefined && cancel)
             throw new UsageError('--when-idle and --cancel-when-idle cannot be combined');
         const flag = cancel ? '--cancel-when-idle' : '--when-idle';
@@ -876,7 +923,7 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'workspaces resume'(ctx, values, [ref]) {
-        // With --wait the resume is held until the workspace runs (contracts §22.6); its tool token is the CLI's label.
+        // With --wait the resume is held until the workspace runs; its tool token is the CLI's label.
         return lifecycle(ctx, values, ref, 'Resuming', (ws, o) => ctx.cloud().workspaces.resume(ws.id, { ...o, agentLabel: ctx.agentLabel }), ['resume', 'Resume']);
     },
     async 'workspaces delete'(ctx, values, [ref]) {
@@ -1526,7 +1573,10 @@ export const KEY_HANDLERS = {
     async 'operations wait'(ctx, values, [id]) {
         if (!UUID.test(id))
             throw new UsageError(`<operation-id> must be a UUID (got "${id}")`);
-        const op = await waitOperation(ctx, id, waitTimeout(values));
+        const timeoutMs = waitTimeout(values);
+        const op = values.durable === true
+            ? await waited(ctx, `operation ${id} continues server side.`, () => ctx.cloud().workspaces.waitForDurable(id, { timeoutMs, signal: ctx.signal }))
+            : await waitOperation(ctx, id, timeoutMs);
         out(ctx, operationDetail(op), op);
         return 0;
     },
@@ -1681,3 +1731,17 @@ async function lifecycle(ctx, values, ref, verb, start, processfulOnly) {
     out(ctx, lifecycleText(verb, ws, op), op);
     return 0;
 }
+function labelMap(value) {
+    if (value === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new UsageError('labels must be a JSON object of strings');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || Object.values(parsed).some((v) => typeof v !== 'string'))
+        throw new UsageError('labels must be a JSON object of strings');
+    return parsed;
+}

package/dist/errors.d.ts

@@ -48,7 +48,7 @@ export declare class CheckoutEndedError extends Error {
 }
 /**
  * The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running, `executionId` when a
- * file-first execution does (it cannot be canceled), with `hint` naming the command that fetches its result.
+ * file-first execution does (an execution runs to completion), with `hint` naming the command that fetches its result.
  */
 export declare class InterruptedError extends Error {
     name: string;
@@ -60,7 +60,7 @@ export declare class InterruptedError extends Error {
         hint?: string;
     });
 }
-/** A file-first execution that ended `failed` or `lost` (contracts §29.8): nothing was published. */
+/** A file-first execution that ended `failed` or `lost`: nothing was published. */
 export declare class ExecutionFailedError extends Error {
     name: string;
     readonly result: ExecutionResult;
@@ -84,7 +84,7 @@ export interface ErrorInfo {
     retryable?: boolean;
     operation_id?: string;
     details?: Record<string, unknown>;
-    source?: 'api' | 'cell';
+    source?: 'api' | 'cell' | 'unknown';
     last_state?: string;
     operation?: unknown;
     /** A file-first execution the error is about (failed, lost, still running, or left running by Ctrl-C). */

package/dist/errors.js

@@ -3,7 +3,7 @@
  * stderr with the API's error code, message and request id; the process exit
  * code tells scripts what kind of failure it was (README "Exit codes").
  */
-import { CheckoutTimeoutError, ExecStartError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
+import { CheckoutTimeoutError, DurabilityLostError, ExecStartError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
 export const EXIT = {
     ok: 0,
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -59,7 +59,7 @@ export class CheckoutEndedError extends Error {
 }
 /**
  * The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running, `executionId` when a
- * file-first execution does (it cannot be canceled), with `hint` naming the command that fetches its result.
+ * file-first execution does (an execution runs to completion), with `hint` naming the command that fetches its result.
  */
 export class InterruptedError extends Error {
     name = 'InterruptedError';
@@ -73,7 +73,7 @@ export class InterruptedError extends Error {
         this.hint = more.hint;
     }
 }
-/** A file-first execution that ended `failed` or `lost` (contracts §29.8): nothing was published. */
+/** A file-first execution that ended `failed` or `lost`: nothing was published. */
 export class ExecutionFailedError extends Error {
     name = 'ExecutionFailedError';
     result;
@@ -137,17 +137,24 @@ export function describeError(err) {
             source: err.source,
         };
     }
-    if (err instanceof OperationTimeoutError)
-        return { code: 'timeout', message: err.message, operation_id: err.operationId, last_state: err.lastState };
+    if (err instanceof OperationTimeoutError) {
+        return { code: 'timeout', message: err.message, operation_id: err.operationId, last_state: err.lastState, ...(err.durable ? { details: { durable: false, state: 'pending' } } : {}) };
+    }
+    // --durable (0.7.0+): the suspend succeeded; its durable copy could not be made (see the lifecycle reference).
+    if (err instanceof DurabilityLostError) {
+        return { code: 'durability_lost', message: err.message, operation_id: err.operationId, retryable: false, details: { state: 'lost', ...(err.durability.reason ? { reason: err.durability.reason } : {}), checkpoint_id: err.durability.checkpointId }, operation: err.operation };
+    }
     if (err instanceof OperationFailedError) {
         // retryable: the operation error's own flag (true for capacity_unavailable: nothing was started, retry later).
         // details.reason: the operation error's reason (e.g. the scheduler's no_ready_hosts), printed after the message.
         const opDetails = err.operation.error?.details;
         const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
         const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
-        return { code: 'operation_failed', message: err.message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };
+        // A suspend-when-idle canceled workspace_active (0.7.0+): the workspace was in use and keeps running.
+        const message = err.workspaceActive ? `${err.message}: the workspace was in use, so the suspend-when-idle was canceled; it keeps running` : err.message;
+        return { code: 'operation_failed', message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };
     }
-    // File-first executions (0.5.0; contracts §29.8): failed or lost like a failed operation (details.reason says why;
+    // File-first executions (0.5.0): failed or lost like a failed operation (details.reason says why;
     // retryable: a new execution id may succeed), still running like a wait that gave up.
     if (err instanceof ExecutionFailedError) {
         const e = err.result.error;
@@ -180,7 +187,7 @@ export function describeError(err) {
         return { code: 'interrupted', message: err.message, ...(err.operationId ? { operation_id: err.operationId } : {}), ...(err.executionId ? { execution_id: err.executionId } : {}) };
     }
     if (err instanceof ShardfluxProtocolError)
-        return { code: 'protocol_error', message: err.message, status: err.status };
+        return { code: 'protocol_error', message: err.message, status: err.status, source: err.source };
     if (isNamed(err, 'TimeoutError'))
         return { code: 'timeout', message: 'The request timed out.' };
     if (isNamed(err, 'AbortError'))
@@ -205,7 +212,7 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.notFound;
     if (err instanceof OperationTimeoutError || err instanceof CheckoutTimeoutError || isNamed(err, 'TimeoutError'))
         return EXIT.timeout;
-    if (err instanceof OperationFailedError || err instanceof ExecutionFailedError || err instanceof CheckoutEndedError)
+    if (err instanceof OperationFailedError || err instanceof DurabilityLostError || err instanceof ExecutionFailedError || err instanceof CheckoutEndedError)
         return EXIT.operationFailed;
     if (err instanceof ExecutionPendingError)
         return EXIT.timeout;

package/dist/format.d.ts

@@ -1,8 +1,3 @@
-/**
- * Human-readable output (aligned tables, key/value blocks) and the error line.
- * `--json` output is the API's own objects (see README "JSON output"), so
- * these functions only shape what people read.
- */
 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 { ErrorInfo } from './errors.js';
 export declare function json(value: unknown): string;
@@ -22,13 +17,13 @@ export declare function workspaceRow(w: WorkspaceView): string[];
 export declare function workspaceTable(ws: readonly WorkspaceView[]): string;
 export declare function isReady(w: WorkspaceView): boolean;
 /**
- * The startup of a workspace's template version (contracts §24.4) in one line: state, trigger, and for a failure the
+ * The startup of a workspace's template version in one line: state, trigger, and for a failure the
  * step or service, exit code and reason. Null when the version has no start commands or services.
  */
 export declare function startupText(s: WorkspaceView['startup'] | undefined): string | null;
 /** The failed step's output tail, indented, after the detail block (empty otherwise). */
 export declare function startupTail(s: WorkspaceView['startup'] | undefined): string;
-/** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
+/** A pending suspend-when-idle request in one line (0.5.1). */
 export declare function suspendRequestText(r: SuspendRequest): string;
 /** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
 export declare function suspendWhenIdleText(w: {
@@ -41,6 +36,11 @@ export declare function suspendWhenIdleText(w: {
 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;
+/**
+ * A finished suspend or fork (0.7.0+): whether its copy is in durable storage, when the result says (`durable`,
+ * `durability`). Empty when the result has no durability block (stored durably before the operation completed).
+ */
+export declare function durableText(op: Operation): string;
 export declare function operationDetail(op: Operation): string;
 export declare function sessionTable(sessions: readonly AgentSession[]): string;
 /** `files stat`: one path's metadata; the revision only when requested and returned. */
@@ -63,8 +63,8 @@ export declare function capMoney(minor: unknown, currency: string): string;
  */
 export declare function usageText(summary: unknown): string;
 /**
- * The `shard feedback` command a failed command suggests (0.5.0+), with the error's request id and code so the founder
- * can find the logs (a failed operation's or execution's own error code, e.g. capacity_unavailable); the agent fills in
+ * The `shard feedback` command a failed command suggests (0.5.0+), with the error's request id and code so the team
+ * can find the logs (a failed operation's or execution's own error code, e.g. template_not_found); the agent fills in
  * the text.
  */
 export declare function feedbackCommand(e: ErrorInfo): string;
@@ -90,7 +90,7 @@ 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 settings (contracts §24.3), one line per part. */
+/** 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). */
 export declare const MAX_CHANGED_SHOWN = 100;
@@ -133,6 +133,17 @@ export declare function usageSeriesText(series: unknown): string;
 /** The period estimate (GET .../usage/estimate): the bill so far and where each allowance is heading. */
 export declare function usageEstimateText(estimate: unknown): string;
 export declare function money(amountMinor: number, currency: string): string;
+export declare function isGrantPlan(plan: {
+    plan_key: string;
+    grant_days?: unknown;
+}): boolean;
+/** The plan in force with the grant's end (`ends_at`, 0.6.2+), which the SDK's generated types add with the API change. */
+type PlanInForce = NonNullable<BillingSubscription['plan']> & {
+    ends_at?: string | null;
+};
+/** "trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog live-v7)"; a plan without an end as before. */
+export declare function planInForceText(plan: PlanInForce | null): string;
+/** The public plans: granted plans (the trial, design partners) are never listed or offered. */
 export declare function planTable(catalog: BillingCatalog): string;
 export declare function billingStatusText(s: BillingSubscription, org: Pick<Organization, 'name' | 'slug'>): string;
 export declare function invoiceTable(rows: readonly BillingInvoicePage['data'][number][]): string;
@@ -149,3 +160,4 @@ export declare function egressVersionTable(rows: readonly EgressPolicyVersion[])
  * cap and its bounds, the rates, and the next step. `saved` adds the version the change was saved as.
  */
 export declare function overagePolicyText(p: SpendPolicy, orgName: string, saved?: boolean): string;
+export {};