@shardflux/cli 0.6.1 → 0.7.0

package/dist/format.js

@@ -1,3 +1,9 @@
+/**
+ * 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';
 export function json(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -85,7 +91,7 @@ function originText(o) {
     }
 }
 /**
- * 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 function startupText(s) {
@@ -107,7 +113,7 @@ export function startupTail(s) {
     const lines = s.output_tail.replace(/\n$/, '').split('\n');
     return `startup output (last ${Buffer.byteLength(s.output_tail)} bytes):\n${lines.map((l) => `  | ${l}`).join('\n')}\n`;
 }
-/** 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 function suspendRequestText(r) {
     return `${r.after_seconds === 0 ? 'as soon as idle' : `after ${r.after_seconds} s idle`}, not before ${time(r.not_before)} (requested ${time(r.requested_at)})`;
 }
@@ -132,7 +138,7 @@ 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})`],
-        // The mode (0.5.0; contracts §29) when the API reports it; a file-first workspace's state is its tree revision.
+        // 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)]] : []),
         ['cell', w.cell_id ? `${w.cell_id} ${w.cell_endpoint ?? '(endpoint unresolved)'}` : '-'],
@@ -161,6 +167,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 +196,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)],
@@ -317,8 +346,12 @@ export function usageText(summary) {
     const head = [];
     if (isObject(s.plan))
         head.push(['plan', `${scalar(s.plan.plan_key)}${s.plan.catalog_version !== undefined ? ` (catalog ${scalar(s.plan.catalog_version)})` : ''}`]);
-    if (isObject(s.period))
-        head.push(['period', `${time(scalar(s.period.start))} .. ${time(scalar(s.period.end))}`]);
+    if (isObject(s.period)) {
+        // A plan grant's own window (source `grant`, 0.6.2+): the trial's 60 days rather than the calendar month.
+        const trial = isObject(s.plan) && s.plan.plan_key === 'trial';
+        const grant = s.period.source === 'grant' ? (trial ? ' (the trial; then free)' : ' (the plan grant; it ends then)') : '';
+        head.push(['period', `${time(scalar(s.period.start))} .. ${time(scalar(s.period.end))}${grant}`]);
+    }
     const m = isObject(s.measurement) ? s.measurement : s;
     if (m.measured_through !== undefined)
         head.push(['measured through', time(m.measured_through)]);
@@ -326,7 +359,8 @@ export function usageText(summary) {
         head.push(['estimate', scalar(s.measurement.estimate_status)]);
     if (typeof s.allowance_exhausted === 'boolean') {
         const reason = typeof s.exhausted_reason === 'string' ? `${s.exhausted_reason}: ` : '';
-        head.push(['allowance exhausted', s.allowance_exhausted ? `yes (${reason}new opens/resumes are refused)` : 'no']);
+        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']);
     }
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
@@ -363,8 +397,8 @@ export function usageText(summary) {
 /** Request ids and error codes pasted unquoted into the suggested command must be shell-inert. */
 const SHELL_SAFE = /^[A-Za-z0-9._:-]{1,200}$/;
 /**
- * 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 function feedbackCommand(e) {
@@ -402,7 +436,7 @@ export function errorText(e, hint, feedback) {
         : '';
     return `error: ${e.message}${reason} [${meta.join(' ')}]\n${issues}${hint ? `hint: ${hint}\n` : ''}${feedback ? `feedback: ${feedback}\n` : ''}`;
 }
-// ---- Templates v2 (contracts §19) ---------------------------------------------------------------
+// ---- Templates v2 ---------------------------------------------------------------
 export function templateTable(rows) {
     return table(['SLUG', 'OWNER', 'OPEN VERSION', 'LAYOUTS', 'FILES', 'DRAFT', 'ARCHIVED'], rows.map((t) => {
         const v = t.open_version;
@@ -514,7 +548,7 @@ export function templateDetailText(t) {
         : 'No versions.\n';
     return `${head}\n${versions}${open?.settings ? `\nsettings of v${open.version}:\n${settingsText(open.settings)}` : ''}`;
 }
-/** A version's settings (contracts §24.3), one line per part. */
+/** 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)}` : ''})`);
     const d = s.defaults;
@@ -528,7 +562,7 @@ export function settingsText(s) {
         ['egress', egress],
     ]).replace(/^/gm, '  ');
 }
-// ---- File-first executions (0.5.0; contracts §29.8) ----------------------------------------------------------------------
+// ---- File-first executions (0.5.0) ----------------------------------------------------------------------
 const CHANGE_LETTER = { added: 'A', modified: 'M', deleted: 'D' };
 /** How many changed paths the human output lists before "... N more" (--json lists every one the result has). */
 export const MAX_CHANGED_SHOWN = 100;
@@ -730,8 +764,25 @@ export function money(amountMinor, currency) {
     const c = currency.toLowerCase();
     return `${zeroDecimal.has(c) ? String(amountMinor) : (amountMinor / 100).toFixed(2)} ${c.toUpperCase()}`;
 }
+/**
+ * Plans that are only ever granted, never bought: the signup trial and the design-partner plan (0.6.2+). The API's
+ * catalog marks them with `grant_days`; the keys cover an API that lists them without it.
+ */
+const GRANT_PLANS = new Set(['trial', 'partner']);
+export function isGrantPlan(plan) {
+    return GRANT_PLANS.has(plan.plan_key) || (typeof plan.grant_days === 'number' && plan.grant_days > 0);
+}
+/** "trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog live-v7)"; a plan without an end as before. */
+export function planInForceText(plan) {
+    if (!plan)
+        return '-';
+    const endsAt = typeof plan.ends_at === 'string' && plan.ends_at !== '' ? plan.ends_at : null;
+    const ends = endsAt ? `, ends ${time(endsAt)}${plan.plan_key === 'trial' ? ', then free' : ''}` : '';
+    return `${plan.plan_key}${ends} (${plan.source}, catalog ${plan.catalog_version})`;
+}
+/** The public plans: granted plans (the trial, design partners) are never listed or offered. */
 export function planTable(catalog) {
-    const rows = catalog.plans.map((p) => {
+    const rows = catalog.plans.filter((p) => !isGrantPlan(p)).map((p) => {
         const prices = p.prices.length ? p.prices.map((x) => `${money(x.amount_minor, x.currency)}/${x.interval}`).join(', ') : 'free';
         const buy = p.prices.some((x) => x.purchasable) ? 'yes' : '-';
         return [p.plan_key, p.name, prices, buy];
@@ -743,7 +794,7 @@ export function billingStatusText(s, org) {
     const pending = s.pending_checkout;
     return kv([
         ['organization', `${org.name} (${org.slug})`],
-        ['plan', s.plan ? `${s.plan.plan_key} (${s.plan.source}, catalog ${s.plan.catalog_version})` : '-'],
+        ['plan', planInForceText(s.plan)],
         ['billing state', s.billing_state],
         ['subscription', sub ? `${sub.status}${sub.plan_key ? ` ${sub.plan_key}` : ''}${sub.cancel_at_period_end ? ', cancels at period end' : ''}` : 'none'],
         ['period end', sub ? time(sub.current_period_end) : '-'],

package/dist/http.d.ts

@@ -1,18 +1,2 @@
-/**
- * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
- * every request (API and cell gateway).
- *
- * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
- * sent on a reused keep-alive connection until an unrelated timer fires (up to
- * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
- * with bare fetch against both node:http and Fastify servers; Node 22 (undici
- * 6.28) and `Connection: close` do not stall. A fresh connection per request
- * costs one TCP/TLS handshake, which is negligible for these call rates.
- * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
- *
- * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
- * held by the server for up to 20 s). The SDK passes the caller's signal to its
- * held polls itself, but not to the held open (`workspaces.open()` with `wait`
- * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
- */
+/** 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,30 +1,12 @@
-/**
- * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
- * every request (API and cell gateway).
- *
- * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
- * sent on a reused keep-alive connection until an unrelated timer fires (up to
- * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
- * with bare fetch against both node:http and Fastify servers; Node 22 (undici
- * 6.28) and `Connection: close` do not stall. A fresh connection per request
- * costs one TCP/TLS handshake, which is negligible for these call rates.
- * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
- *
- * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
- * held by the server for up to 20 s). The SDK passes the caller's signal to its
- * held polls itself, but not to the held open (`workspaces.open()` with `wait`
- * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
- */
-export function makeFetch(env, base = fetch, signal) {
-    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.
@@ -47,7 +47,7 @@ function hintFor(info, cred, file) {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'operation_failed' && info.retryable) {
-        return info.details?.error_code === 'capacity_unavailable' ? 'no host could admit it before its deadline; nothing was started. Retry later.' : 'the operation may succeed if you retry it later.';
+        return info.details?.error_code === 'capacity_unavailable' ? 'nothing was started; run the same command again' : 'the operation may succeed if you retry it later.';
     }
     if (info.code === 'interrupted' && info.operation_id)
         return `keep waiting with: shard operations wait ${info.operation_id}`;
@@ -79,7 +79,7 @@ function hintFor(info, cred, file) {
     const policyHint = spendPolicyHint(info);
     if (policyHint)
         return policyHint;
-    // File patches (contracts §26.2): what to do about each refusal. details.index is the 0-based edit (--old) index.
+    // 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}` : '';
     if (reason === 'revision_mismatch') {
@@ -93,7 +93,7 @@ function hintFor(info, cred, file) {
     if (reason === 'edit_not_text')
         return 'the file is not UTF-8 text; use files write for binary data';
     if (reason === 'host_capacity')
-        return 'the workspace’s host has no room to run it right now; retry in a few seconds';
+        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);
     // A processful command that could not start (0.5.1): what to change, from the workspace's reason.
@@ -167,17 +167,15 @@ function spendPolicyHint(info) {
     }
 }
 /**
- * 409 conflict host_feature_unavailable (contracts §26.7; 0.5.0): the workspace runs on a host agent that predates the
- * call. Not retryable: it lasts until the workspace runs on an upgraded host (minutes to hours), so the hint names
- * another way to do it now.
+ * 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.
  */
 function hostFeatureHint(feature) {
-    const later = 'it will once the workspace runs on an upgraded host (retrying now does not help)';
     if (feature === 'file_search')
-        return `the workspace’s host does not support files search yet; ${later}. Search with a command instead: shard ws exec <id|key> -- grep -rn <pattern> <path>`;
+        return 'files search is not available for this workspace (retrying does not help); search with a command instead: shard ws exec <id|key> -- grep -rn <pattern> <path>';
     if (feature === 'file_patch')
-        return `the workspace’s host does not support files patch yet; ${later}. Rewrite the file instead: shard files read <id|key> <path> --out F, edit F, then shard files write <id|key> <path> --from F`;
-    return `the workspace’s host does not support this call yet; ${later}`;
+        return 'files patch is not available for this workspace (retrying does not help); rewrite the file instead: shard files read <id|key> <path> --out F, edit F, then shard files write <id|key> <path> --from F';
+    return 'this call is not available for this workspace (retrying does not help)';
 }
 /** What an execution that ended failed or lost ran into (error.details.reason), where the reason alone says little. */
 const EXECUTION_CAUSES = {
@@ -186,10 +184,10 @@ const EXECUTION_CAUSES = {
     host_unreachable: 'its host stopped answering',
     host_restarted: 'its host restarted',
     tree_moved: 'the tree changed while it ran',
-    no_execution_host: 'no host had room to run it',
+    no_execution_host: 'the execution could not be placed',
     workspace_deleted: 'the workspace was deleted',
 };
-/** Hints for file-first workspaces (0.5.0; contracts §29.7, §29.8): the mode refusals, tree revisions and executions. */
+/** Hints for file-first workspaces (0.5.0): the mode refusals, tree revisions and executions. */
 function fileFirstHint(info) {
     const d = info.details ?? {};
     const reason = d.reason;
@@ -211,7 +209,7 @@ function fileFirstHint(info) {
             return `this key already belongs to a ${has} workspace and a workspace’s mode never changes; use another key for a ${wants} workspace (or reopen this one without --mode)`;
         }
         case 'mode_not_available':
-            return 'this deployment does not offer file-first workspaces yet; leave out --mode file-first to open a processful workspace';
+            return 'this deployment does not offer file-first workspaces; leave out --mode file-first to open a processful workspace';
         case 'layout_unsupported':
             return d.mode === 'file_first' ? 'file-first workspaces run on layered template versions only; open a template version whose disk layouts include layered (shard templates get <slug> lists them)' : undefined;
         case 'tree_revision_mismatch': {
@@ -229,7 +227,7 @@ function fileFirstHint(info) {
         case 'execution_id_reused':
             return 'this --execution-id was already used for a different request (the same id with the same request returns its recorded result); pass a new --execution-id';
         case 'no_execution_host':
-            return 'no host had room to run the execution, also after retries with the same execution id; nothing ran. Retry later';
+            return 'the execution cannot be placed right now, also after retries with the same execution id; nothing ran. Retry';
         default:
             return undefined;
     }
@@ -271,7 +269,7 @@ function nudges(info, command) {
     const reason = reasonOf(info);
     return !NO_NUDGE_CODES.has(info.code) && !(reason !== undefined && NO_NUDGE_REASONS.has(reason));
 }
-/** `shard feedback` could not send: how to fix it, and the way to still reach the founder. */
+/** `shard feedback` could not send: how to fix it, and the way to still reach the Shardflux team. */
 function feedbackHint(info, credentialHint) {
     if (info.code === 'usage')
         return 'run "shard feedback --help"';
@@ -329,7 +327,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;
     };
@@ -361,7 +359,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);
@@ -562,9 +560,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

@@ -1,5 +1,5 @@
 /**
- * template.yaml text (contracts §24.1: the recipe v2 document in YAML; only clients parse YAML): the starter file of
+ * template.yaml text (the recipe v2 document in YAML; only clients parse YAML): the starter file of
  * `shard templates init` and the export of a version (`shard templates export`), written like the dashboard's
  * Template file section (keys in the recipe's order, long scripts as block literals, no line folding).
  */

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

@@ -17,6 +17,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 +32,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 +56,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 +100,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,
             }

package/dist/update-check.js

@@ -1,5 +1,5 @@
 /**
- * `shard` tells its user when it is outdated or no longer supported (0.5.0+; contracts §30.4). The API's
+ * `shard` tells its user when it is outdated or no longer supported (0.5.0+). The API's
  * GET /v1/client-versions names the latest published version of every client and the oldest one it still serves.
  *
  * - At most one request per 24 hours per API URL and package: the answer is cached in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.6.1",
+  "version": "0.7.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.0"
+    "@shardflux/sdk": "^0.12.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",