@shardflux/cli 0.6.2 → 0.8.0

package/dist/format.js

@@ -1,3 +1,13 @@
+/**
+ * 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 { 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`;
 }
@@ -122,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);
@@ -132,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)]] : []),
@@ -139,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)]] : []),
@@ -161,6 +201,28 @@ export const OPERATION_HEADERS = ['ID', 'KIND', 'STATE', 'REASON', 'CREATED', 'C
 export function operationTable(ops) {
     return table(OPERATION_HEADERS, ops.map((o) => [o.id, o.kind, o.state, o.state_reason ?? '-', time(o.created_at), time(o.completed_at)]));
 }
+/**
+ * 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 function durableText(op) {
+    const d = durabilityOf(op);
+    if (op.state !== 'succeeded' || !d)
+        return '';
+    if (d.state === 'durable')
+        return `durable: yes${d.localCommitToDurableMs !== null ? ` (${d.localCommitToDurableMs} ms after the suspend)` : ''}\n`;
+    if (d.state === 'pending')
+        return `durable: in progress, typically within a second (wait with: shard operations wait ${op.id} --durable)\n`;
+    return `durable: no (${d.reason ?? 'lost'}); see docs.shardflux.dev/concepts/lifecycle\n`;
+}
+/** `durable` of a finished suspend or fork for `operations get`/`wait`: yes, in progress, no, or '-' for other kinds. */
+function durableField(op) {
+    const d = durabilityOf(op);
+    if (d)
+        return d.state === 'durable' ? 'yes' : d.state === 'pending' ? 'in progress' : `no (${d.reason ?? 'lost'})`;
+    const v = isDurable(op);
+    return v === null ? '-' : v ? 'yes' : 'no';
+}
 export function operationDetail(op) {
     const err = op.error;
     return kv([
@@ -168,6 +230,7 @@ export function operationDetail(op) {
         ['kind', op.kind],
         ['state', op.state],
         ['reason', op.state_reason ?? '-'],
+        ...(op.kind === 'suspend' || op.kind === 'fork' ? [['durable', durableField(op)]] : []),
         ['workspace', op.workspace_id ?? '-'],
         ['created', time(op.created_at)],
         ['updated', time(op.updated_at)],
@@ -480,15 +543,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)'}` : '-'],
@@ -514,11 +592,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/http.d.ts

@@ -1,11 +1,2 @@
-/**
- * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
- * default every request uses a fresh connection (`Connection: close`);
- * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
- *
- * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
- * held by the server for up to 20 s). The SDK passes the caller's signal to its
- * held polls itself, but not to the held open (`workspaces.open()` with `wait`
- * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
- */
+/** Share the SDK pool and attach Ctrl-C to held API requests. */
 export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch, signal?: AbortSignal): typeof fetch;

package/dist/http.js

@@ -1,24 +1,12 @@
-/**
- * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
- * default every request uses a fresh connection (`Connection: close`);
- * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
- *
- * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
- * held by the server for up to 20 s). The SDK passes the caller's signal to its
- * held polls itself, but not to the held open (`workspaces.open()` with `wait`
- * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
- */
-export function makeFetch(env, base = fetch, signal) {
-    // Why a fresh connection by default (Node 26 keep-alive measurements): docs/progress/startup-latency.md.
-    const keepAlive = env.SHARDFLUX_HTTP_KEEPALIVE === '1';
+import { defaultFetch } from '@shardflux/sdk';
+/** Share the SDK pool and attach Ctrl-C to held API requests. */
+export function makeFetch(env, base = defaultFetch(env), signal) {
     return (input, init) => {
         const headers = new Headers(init?.headers);
         const held = signal !== undefined && /\bwait\s*=/i.test(headers.get('prefer') ?? '');
-        if (keepAlive && !held)
+        if (!held)
             return base(input, init);
-        if (!keepAlive)
-            headers.set('connection', 'close');
-        const s = held && signal ? (init?.signal ? AbortSignal.any([init.signal, signal]) : signal) : init?.signal;
-        return base(input, { ...init, headers, ...(s ? { signal: s } : {}) });
+        const s = init?.signal && signal ? AbortSignal.any([init.signal, signal]) : signal;
+        return base(input, { ...init, ...(s ? { signal: s } : {}) });
     };
 }

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, timingJson, timingText } from './timing.js';
+export { TimingRecorder, coldBootNotice, 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, timingJson, timingText } from "./timing.js";
+export { TimingRecorder, coldBootNotice, lostSuspendNotice, notices, timingJson, timingText } from "./timing.js";

package/dist/main.js

@@ -19,7 +19,7 @@ import { errorText, feedbackCommand, json, time } from "./format.js";
 import { HANDLERS } from "./handlers.js";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
-import { TimingRecorder, coldBootNotice, timingJson, timingText } from "./timing.js";
+import { TimingRecorder, notices, timingJson, timingText } from "./timing.js";
 import { CLI_DISTRIBUTION, NOTICE_WAIT_MS, UpdateCheck, noticeOf, updateCheckDisabled, updateView } from "./update-check.js";
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
@@ -79,6 +79,9 @@ function hintFor(info, cred, file) {
     const policyHint = spendPolicyHint(info);
     if (policyHint)
         return policyHint;
+    const immutable = immutableHint(info);
+    if (immutable)
+        return immutable;
     // File patches: what to do about each refusal. details.index is the 0-based edit (--old) index.
     const reason = info.details?.reason;
     const index = typeof info.details?.index === 'number' ? ` #${info.details.index + 1}` : '';
@@ -166,6 +169,35 @@ function spendPolicyHint(info) {
             return undefined;
     }
 }
+/**
+ * Immutable paths (0.8.0; contracts §34): the build refusals (422 validation_failed per details.reason, with the paths
+ * and base the API names) and a files write under an immutable path (409 conflict read_only_path from the cell).
+ */
+function immutableHint(info) {
+    const d = info.details ?? {};
+    const reason = reasonOf(info);
+    const list = (v) => (Array.isArray(v) ? v.filter((p) => typeof p === 'string').join(', ') : '');
+    if (info.code === 'conflict' && reason === 'read_only_path') {
+        return 'this path is an immutable path of the workspace’s template: read-only, it follows the template’s newest version. Write elsewhere, or change it in the template and build a new version (shard templates get <slug> lists the immutable paths)';
+    }
+    if (info.code !== 'validation_failed')
+        return undefined;
+    if (reason === 'immutable_path_removed') {
+        const removed = list(d.removed);
+        const open = typeof d.open_version === 'number' ? `v${d.open_version}` : 'the open version';
+        return `a new version keeps every immutable path of ${open}: add ${removed || 'them'} back to immutable in template.yaml (adding paths is fine)`;
+    }
+    if (reason === 'immutable_paths_unsupported_base') {
+        if (d.field === 'recipe')
+            return 'this template has immutable paths: build it from a template.yaml (shard templates export <slug>@<version> writes the current one, shard templates build builds it)';
+        const base = typeof d.base === 'object' && d.base !== null ? d.base.name : undefined;
+        return typeof base === 'string' ? `build on a newer version of ${base} (shard templates get ${base} lists its versions)` : 'build on a newer version of the base';
+    }
+    if (reason === 'invalid_path' && typeof d.field === 'string' && d.field.startsWith('recipe.immutable[')) {
+        return `fix ${d.field.slice('recipe.'.length)} in template.yaml (the list counts from 0)`;
+    }
+    return undefined;
+}
 /**
  * 409 conflict host_feature_unavailable (0.5.0): the call is not available for this workspace. Not retryable, so the
  * hint names the fallback that works now.
@@ -258,6 +290,8 @@ const NO_NUDGE_REASONS = new Set([
     'subscription_exists',
     // A stale spend policy (If-Match): the hint names the version to retry with (0.5.1).
     'version_mismatch',
+    // A write under an immutable path (0.8.0): the hint says where to change it.
+    'read_only_path',
 ]);
 /**
  * Whether a failure ends with the `feedback:` line (0.5.0+): every failure except the expected flow above (feedback
@@ -327,7 +361,7 @@ export async function run(argv, io, opts = {}) {
         const feedback = nudges(info, command) ? feedbackCommand(info) : undefined;
         const text = wantsJson
             ? json({ error: info, ...(showTiming ? { timing: timingJson(timing) } : {}), ...(feedback ? { feedback } : {}) })
-            : `${timing ? timingText(timing) : ''}${traces.coldBoot ? coldBootNotice(traces.coldBoot) : ''}${errorText(info, hint, feedback)}`;
+            : `${timing ? timingText(timing) : ''}${notices(traces)}${errorText(info, hint, feedback)}`;
         io.stderr.write(redact(text, ...secrets));
         return code;
     };
@@ -359,7 +393,7 @@ export async function run(argv, io, opts = {}) {
         const wakeTimeoutMs = resolveWakeTimeout(parsed.global.wakeTimeout, io.env.SHARDFLUX_WAKE_TIMEOUT_MS);
         showTiming = parsed.values.timing === true;
         const userAgent = `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}${distribution.package === CLI_DISTRIBUTION.package ? '' : ` ${distribution.package}/${distribution.version}`}`;
-        const base = makeFetch(io.env, fetch, signal);
+        const base = makeFetch(io.env, undefined, signal);
         // Notes which credential a 401 unauthenticated answered (the hint, and removing a dead saved session).
         const watchedFetch = async (input, init) => {
             const res = await base(input, init);
@@ -560,9 +594,11 @@ export async function run(argv, io, opts = {}) {
         // With --json the handler put the timing into its output; otherwise it follows the output, on stderr.
         if (showTiming && !ctx.json && traces.last)
             io.stderr.write(timingText(traces.last));
-        // A resume that booted the saved disk (0.6.0+): said on stderr with or without --timing, also with --json.
-        if (traces.coldBoot)
-            io.stderr.write(coldBootNotice(traces.coldBoot));
+        // A resume that booted the saved disk (0.6.0+), or restored an earlier checkpoint (0.7.0+): said on stderr with or
+        // without --timing, also with --json.
+        const notice = notices(traces);
+        if (notice)
+            io.stderr.write(notice);
         code = outcome.code;
     }
     // The update notice: after the output, never after Ctrl-C or a --json failure (stderr then holds only the error).

package/dist/template-yaml.js

@@ -20,6 +20,9 @@ export function initTemplateYaml(base) {
 # build: what goes into the template (languages, packages, files, steps). settings: what a workspace gets when it opens.
 schema: shardflux.template-recipe.v2
 base: ${base}
+# Immutable paths: directories every workspace of this template mounts read-only from its newest published version
+# (workspaces pick up a new version at their next cold boot or resume), e.g. tools or data you ship with each version.
+# immutable: [/opt/acme]
 build:
   # Languages from the platform's table: python, node, go, rust, java (version omitted: the base's default).
   languages: []

package/dist/timing.d.ts

@@ -10,6 +10,11 @@ export declare class TimingRecorder {
      * the wake of a command that found the workspace suspended. `coldBootNotice()` says it.
      */
     coldBoot: LifecycleTiming | null;
+    /**
+     * (0.7.0+) The last traced resume whose result names a suspend it could not restore (`lost_suspend`): a `ws resume
+     * --wait`, an `operations wait` of that resume, or a command's wake. `lostSuspendNotice()` says it.
+     */
+    lostSuspend: 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
@@ -22,6 +27,13 @@ export declare class TimingRecorder {
  * `--timing`: the workspace runs and its files are as of the suspend, but running processes were restarted.
  */
 export declare function coldBootNotice(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. */
+export declare function notices(r: TimingRecorder): string;
 /** The human form (stderr): formatTiming() of the SDK, one block. */
 export declare function timingText(t: LifecycleTiming): string;
 /** The `--json` form: the SDK's LifecycleTiming with the CLI's snake_case keys (the rest of its JSON is the API's). */

package/dist/timing.js

@@ -6,6 +6,7 @@
  * carry no `timing` (network errors, Ctrl-C).
  */
 import { formatTiming } from '@shardflux/sdk';
+import { byteSize } from "./format.js";
 export class TimingRecorder {
     /** The timing of the last traced call that ended (token fetches are not lifecycle calls and are skipped). */
     last = null;
@@ -17,6 +18,11 @@ export class TimingRecorder {
      * the wake of a command that found the workspace suspended. `coldBootNotice()` says it.
      */
     coldBoot = null;
+    /**
+     * (0.7.0+) The last traced resume whose result names a suspend it could not restore (`lost_suspend`): a `ws resume
+     * --wait`, an `operations wait` of that resume, or a command's wake. `lostSuspendNotice()` says it.
+     */
+    lostSuspend = null;
     listener = (e) => {
         if (e.action === 'token' || e.action === 'tool')
             return;
@@ -27,6 +33,8 @@ export class TimingRecorder {
         this.last = e.timing;
         if (restartedProcesses(e.timing))
             this.coldBoot = e.timing;
+        if (e.timing.server?.lostSuspend)
+            this.lostSuspend = e.timing;
     };
     /**
      * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
@@ -49,6 +57,20 @@ 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`;
 }
+/**
+ * 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 function lostSuspendNotice(t) {
+    const l = t.server?.lostSuspend;
+    if (!l)
+        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. */
+export function notices(r) {
+    return `${r.coldBoot ? coldBootNotice(r.coldBoot) : ''}${r.lostSuspend ? lostSuspendNotice(r.lostSuspend) : ''}`;
+}
 /** The human form (stderr): formatTiming() of the SDK, one block. */
 export function timingText(t) {
     return `${formatTiming(t)}\n`;
@@ -79,6 +101,31 @@ export function timingJson(t) {
                 resume_path: s.resumePath,
                 memory_restored: s.memoryRestored ?? null,
                 cold_boot_reason: s.coldBootReason ?? null,
+                durable: s.durable ?? null,
+                suspend_path: s.suspendPath ?? null,
+                durability: s.durability
+                    ? {
+                        state: s.durability.state,
+                        checkpoint_id: s.durability.checkpointId,
+                        generation_id: s.durability.generationId,
+                        local_commit_at: s.durability.localCommitAt,
+                        durable_by: s.durability.durableBy,
+                        durable_at: s.durability.durableAt,
+                        local_commit_to_durable_ms: s.durability.localCommitToDurableMs,
+                        overdue_at: s.durability.overdueAt,
+                        reason: s.durability.reason,
+                    }
+                    : null,
+                lost_suspend: s.lostSuspend
+                    ? {
+                        checkpoint_id: s.lostSuspend.checkpointId,
+                        generation_id: s.lostSuspend.generationId,
+                        reason: s.lostSuspend.reason,
+                        suspended_at: s.lostSuspend.suspendedAt,
+                        restored_checkpoint_id: s.lostSuspend.restoredCheckpointId,
+                        state_as_of: s.lostSuspend.stateAsOf,
+                    }
+                    : null,
                 boot_to_ready_ms: s.bootToReadyMs,
                 host_timings_ms: s.hostTimingsMs,
             }
@@ -150,7 +197,7 @@ export class BuildTimer {
 }
 const fmtMs = (ms) => (ms === null ? '-' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
 const short = (sha) => sha.slice(0, 12);
-const bytes = (n) => (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`);
+const bytes = byteSize;
 /** One stderr line per build-from-file progress event. */
 export function progressLine(e) {
     if (e.type === 'pack')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.6.2",
+  "version": "0.8.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.11.1"
+    "@shardflux/sdk": "^0.13.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",