@shardflux/cli 0.5.3 → 0.6.1

package/CHANGELOG.md

@@ -3,7 +3,39 @@
 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.3 (not yet published)
+## 0.6.1
+
+Needs `@shardflux/sdk` 0.11.0 or later.
+
+### `--when-idle 0`: suspend as soon as the workspace is idle
+
+`shard ws suspend <id|key> --when-idle` accepts `0` (also `0s`) up to `1h`; before it refused anything under `30s`.
+The API now takes `after_seconds` from 0: the workspace is suspended as soon as it is idle (a few seconds of activity
+flush grace after its last work), and a running command, an attached stream or a keepalive still postpones it until
+it ends. The human output says `is suspended as soon as it is idle`, and `ws get` shows `as soon as idle`. Out of
+range is still exit 2 before any request: `--when-idle must be between 0s and 1h`.
+
+## 0.6.0
+
+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.

package/README.md

@@ -385,7 +385,7 @@ shows the status; `shard version --check` asks now (`--json`: `{"cli", "sdk", "u
 | `files search <id\|key> <path> <pattern> [--regex] [-i\|--ignore-case] [--include G]... [--exclude G]... [--max N]` | Search file contents under a directory (or in one file; gitignore-style globs): `path:line:column: text` per match (0.5.0+). |
 | `files patch <id\|key> <path> (--old T --new T)... [--replace-all] \| --content-file F\|- [--expected-revision R] [--if-revision N]` | Replace exact text (each `--old` must occur once unless `--replace-all`), or the whole content, atomically; `R` is a revision from `files stat --revision` or `absent` (0.5.0+). `--if-revision` (0.5.0+): file-first workspaces only. |
 | `workspaces suspend\|resume <id\|key> [--wait] [--timeout T] [--timing]` | Lifecycle operation. Returns immediately unless you pass `--wait`. |
-| `workspaces suspend <id\|key> --when-idle D` / `--cancel-when-idle` | (0.5.1+) Suspend once the workspace has been idle for `D` (30s to 1h), or cancel that. See "Suspend when idle". |
+| `workspaces suspend <id\|key> --when-idle D` / `--cancel-when-idle` | (0.5.1+) Suspend once the workspace has been idle for `D` (0 to 1h; `0` = as soon as it is idle, 0.6.1+), or cancel that. See "Suspend when idle". |
 | `workspaces fork <id\|key> <new-key> [caps] [--wait]` | Fork into a new key. |
 | `workspaces delete <id\|key> --yes [--wait]` | Delete the workspace. Tool access ends at once. The key of a persistent workspace is never reused. |
 | `workspaces close <id\|key> [--wait]` | End a session workspace now: it is deleted, and the key then opens a new workspace. A persistent workspace is refused (`not_session`). |
@@ -576,17 +576,34 @@ 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
 been idle for a short time, instead of waiting for its idle policy:
 
 ```sh
-shard ws suspend acme/demo --when-idle 2m    # 30s to 1h; whole seconds
+shard ws suspend acme/demo --when-idle 2m    # 0 to 1h; whole seconds
 shard ws get acme/demo                       # "suspend when idle  after 120 s idle, not before ..."
 shard ws suspend acme/demo --cancel-when-idle
 ```
 
+- `--when-idle 0` (0.6.1+) suspends the workspace as soon as it is idle (a few seconds after its last work).
+
 - The idle time counts from the later of the workspace's last work and the request.
 - A command still running, an attached stream or a keepalive postpones the suspend until the duration after it ends.
 - The next tool call on the workspace (the next turn) or a resume cancels the request. Repeating replaces it.
@@ -686,8 +703,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.3";
+export declare const CLI_VERSION = "0.6.1";
 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.3';
+export const CLI_VERSION = '0.6.1';
 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).' },
@@ -274,7 +274,7 @@ const KEY_COMMANDS = [
         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.',
         positionals: [REF],
         options: {
-            'when-idle': { type: 'string', value: '<duration>', description: 'Suspend once the workspace has been idle this long (30s to 1h, e.g. 30s, 2m; 0.5.1+). Cannot be combined with --wait.' },
+            '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).' },
             ...WAIT,
         },

package/dist/commands.d.ts

@@ -70,7 +70,7 @@ 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 30 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, contracts §20.6). */
 export declare function whenIdleSeconds(text: string): number;
 export declare function waitTimeout(values: Values): number;
 /**

package/dist/commands.js

@@ -66,14 +66,16 @@ 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 30 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, contracts §20.6). */
 export function whenIdleSeconds(text) {
+    if (/^0+(?:\.0+)?(?:ms|s|m|h)?$/.test(text.trim()))
+        return 0;
     const ms = parseDuration(text, 'when-idle');
     if (ms % 1000 !== 0)
         throw new UsageError('--when-idle must be a whole number of seconds (e.g. 30s, 90s, 2m)');
     const s = ms / 1000;
-    if (s < 30 || s > 3600)
-        throw new UsageError(`--when-idle must be between 30s and 1h (got "${text}")`);
+    if (s > 3600)
+        throw new UsageError(`--when-idle must be between 0s and 1h (got "${text}")`);
     return s;
 }
 export function waitTimeout(values) {

package/dist/format.js

@@ -109,13 +109,13 @@ export function startupTail(s) {
 }
 /** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
 export function suspendRequestText(r) {
-    return `after ${r.after_seconds} s idle, not before ${time(r.not_before)} (requested ${time(r.requested_at)})`;
+    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)})`;
 }
 /** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
 export function suspendWhenIdleText(w, r) {
     if (r.suspend_request) {
         const s = r.suspend_request;
-        return (`Suspend when idle: ${w.key} (${w.id}) is suspended once it has been idle for ${s.after_seconds} s, not before ${time(s.not_before)}.\n` +
+        return (`Suspend when idle: ${w.key} (${w.id}) is suspended ${s.after_seconds === 0 ? 'as soon as it is idle' : `once it has been idle for ${s.after_seconds} s`}, not before ${time(s.not_before)}.\n` +
             'A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.\n' +
             `cancel with: shard workspaces suspend ${w.key} --cancel-when-idle\n`);
     }

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.3",
+  "version": "0.6.1",
   "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.2"
+    "@shardflux/sdk": "^0.11.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",