@shardflux/cli 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -3,7 +3,32 @@
 Every command and option the README shows is available from the version named here. Below 1.0, a minor release may
 break compatibility; breaking changes are marked **Breaking**.
 
-## 0.5.2 (not yet published)
+## 0.6.0 (not yet published)
+
+Needs `@shardflux/sdk` 0.11.0 or later.
+
+### A resume that restarted processes says so (cold boot, contracts §12)
+
+When the platform's VM runtime changed after a suspend and no host can restore the memory snapshot, the cell resumes
+the workspace by booting its saved disk (a cold boot), automatically, also when a command wakes it. Files are as of the
+suspend; every process was restarted.
+
+- After a command whose resume or wake did that (`ws resume --wait`, `operations wait` of that resume, or `ws exec`,
+  `files ...` and `ws changes` waking a suspended workspace), `shard` prints one line on stderr after the output, with
+  or without `--timing`: `note: workspace <id> resumed from its saved disk; running processes were restarted
+  (runtime_changed)`. Also with `--json` (stdout unchanged); not after a `--json` failure, whose stderr is only the
+  error document. On a text failure it comes before the error line. The exit code does not change.
+- `--json --timing`: `timing.server` adds `memory_restored` (`false` for a cold boot, `true` for a memory resume,
+  `null` when the API did not say) and `cold_boot_reason`. The human `--timing` block says `resume from cold_boot:
+  processes restarted (runtime_changed)` (the SDK's `formatTiming()`).
+- `coldBootNotice()` is exported next to `TimingRecorder`, which records the call as `coldBoot`.
+
+## 0.5.3
+
+Fix: `shard --version`, the User-Agent and the update check reports 0.5.3. 0.5.2 was published reporting 0.5.1, its previous version; the build now
+fails when `CLI_VERSION` differs from package.json.
+
+## 0.5.2
 
 Public support: package metadata and the README now link to the [shared bug tracker](https://github.com/shardfluxdev/community/issues),
 feature requests, and private support/security reporting.

package/README.md

@@ -576,6 +576,21 @@ without waking it (the state at suspension); `files search` then notes it on std
   `shard operations wait <id>` keeps waiting.
 - A resume or open that fails exits 6.
 
+**A resume can restart processes (0.6.0+).** A resume normally restores memory and running processes. When the
+platform's VM runtime changed after the suspend and no host can restore that memory snapshot, the resume boots the
+workspace's saved disk instead (a cold boot), automatically, also when a command wakes the workspace. The command
+still runs, and the files are as of the suspend, but every process was restarted, as after a reboot: start dev
+servers and background jobs again. `shard` then prints one line on stderr after the output (also with `--json`,
+except on a failure, whose stderr is only the error document), whether or not you pass `--timing`:
+
+```text
+note: workspace 01a0e5a8-3edd-74ba-b489-d62b8925e342 resumed from its saved disk; running processes were restarted (runtime_changed)
+```
+
+`shard ws resume --wait --json` prints the operation with its `result` as the API sent it (`resume_path`
+`cold_boot`, `memory_restored` false, `cold_boot_reason`), and `--timing` shows `resume from cold_boot: processes
+restarted (runtime_changed)`. The same applies to `operations wait` of such a resume.
+
 ## Suspend when idle (0.5.1+)
 
 A running workspace is billed while it is awake. When an agent's turn ends, ask for a suspend once the workspace has
@@ -686,8 +701,9 @@ Which call is timed:
 
 With `--json`, stdout carries the timing as a `timing` field of the command's JSON instead: `action`, `outcome`,
 `workspace_id`, `operation_id`, `total_ms`, `phases` (`phase`, `reason`, `operation_id`, `start_ms`, `duration_ms`),
-`retries`, `server` (`queued_ms`, `run_ms`, `total_ms`, `start_path`, `resume_path`, `boot_to_ready_ms`, ...) and
-`outside_server_ms`. It is `null` when the command made no lifecycle call. On a failure the error document on stderr
+`retries`, `server` (`queued_ms`, `run_ms`, `total_ms`, `start_path`, `resume_path`, `memory_restored` and
+`cold_boot_reason` (0.6.0+; `memory_restored` is `false` when a resume booted the saved disk, `null` when the API did
+not say), `boot_to_ready_ms`, ...) and `outside_server_ms`. It is `null` when the command made no lifecycle call. On a failure the error document on stderr
 carries it: `{"error": {...}, "timing": {...}}`.
 
 `shard` does not stream progress while it waits. For live events, use the SDK's `onProgress`.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.5.1";
+export declare const CLI_VERSION = "0.6.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

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.5.1';
+export const CLI_VERSION = '0.6.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).' },

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, timingJson, timingText } from './timing.js';
+export { TimingRecorder, coldBootNotice, 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, timingJson, timingText } from "./timing.js";
+export { TimingRecorder, coldBootNotice, 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, timingJson, timingText } from "./timing.js";
+import { TimingRecorder, coldBootNotice, 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.
@@ -329,7 +329,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) : ''}${errorText(info, hint, feedback)}`;
+            : `${timing ? timingText(timing) : ''}${traces.coldBoot ? coldBootNotice(traces.coldBoot) : ''}${errorText(info, hint, feedback)}`;
         io.stderr.write(redact(text, ...secrets));
         return code;
     };
@@ -562,6 +562,9 @@ 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));
         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/timing.d.ts

@@ -4,6 +4,12 @@ export declare class TimingRecorder {
     last: LifecycleTiming | null;
     /** The operation the command's traced calls last observed: named when Ctrl-C interrupts a wait. */
     operationId: string | null;
+    /**
+     * (0.6.0+) The last traced call whose resume booted the workspace's saved disk instead of restoring its memory
+     * (`resume_path` `cold_boot`, `memory_restored` false): a `ws resume --wait`, an `operations wait` of that resume, or
+     * the wake of a command that found the workspace suspended. `coldBootNotice()` says it.
+     */
+    coldBoot: 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
@@ -11,6 +17,11 @@ export declare class TimingRecorder {
      */
     forError(err: unknown): LifecycleTiming | null;
 }
+/**
+ * The one-line stderr notice after a command whose resume booted the workspace's saved disk (0.6.0+), with or without
+ * `--timing`: the workspace runs and its files are as of the suspend, but running processes were restarted.
+ */
+export declare function coldBootNotice(t: LifecycleTiming): 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

@@ -11,13 +11,22 @@ export class TimingRecorder {
     last = null;
     /** The operation the command's traced calls last observed: named when Ctrl-C interrupts a wait. */
     operationId = null;
+    /**
+     * (0.6.0+) The last traced call whose resume booted the workspace's saved disk instead of restoring its memory
+     * (`resume_path` `cold_boot`, `memory_restored` false): a `ws resume --wait`, an `operations wait` of that resume, or
+     * the wake of a command that found the workspace suspended. `coldBootNotice()` says it.
+     */
+    coldBoot = null;
     listener = (e) => {
         if (e.action === 'token' || e.action === 'tool')
             return;
         if (e.operationId)
             this.operationId = e.operationId;
-        if (e.type === 'done')
-            this.last = e.timing;
+        if (e.type !== 'done')
+            return;
+        this.last = e.timing;
+        if (restartedProcesses(e.timing))
+            this.coldBoot = e.timing;
     };
     /**
      * The failed call's own timing (`err.timing`) when the SDK attached one, else the last recorded. A refused tool token
@@ -28,6 +37,18 @@ export class TimingRecorder {
         return own && own.action !== 'token' ? own : this.last;
     }
 }
+/** A resume that booted the saved disk: files as of the suspend, every process restarted (never a null memory_restored). */
+function restartedProcesses(t) {
+    return t.server?.resumePath === 'cold_boot' && t.server.memoryRestored === false;
+}
+/**
+ * The one-line stderr notice after a command whose resume booted the workspace's saved disk (0.6.0+), with or without
+ * `--timing`: the workspace runs and its files are as of the suspend, but running processes were restarted.
+ */
+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 human form (stderr): formatTiming() of the SDK, one block. */
 export function timingText(t) {
     return `${formatTiming(t)}\n`;
@@ -56,6 +77,8 @@ export function timingJson(t) {
                 start_path: s.startPath,
                 warm_fallback: s.warmFallback,
                 resume_path: s.resumePath,
+                memory_restored: s.memoryRestored ?? null,
+                cold_boot_reason: s.coldBootReason ?? null,
                 boot_to_ready_ms: s.bootToReadyMs,
                 host_timings_ms: s.hostTimingsMs,
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.5.2",
+  "version": "0.6.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.10.1"
+    "@shardflux/sdk": "^0.11.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",