warpmetal 0.8.3 → 0.8.4

package/README.md

@@ -296,6 +296,11 @@ compatible external signer.
 - Sandboxes use the fixed runtime image and fixed sizes. Persistent is the
   default; temporary sandboxes require explicit confirmation and permanently
   delete their workspace after 15 minutes to 24 hours.
+- `sandbox action --action refresh_image --confirm refresh_image --wait`
+  explicitly replaces one sandbox's root filesystem with the current immutable
+  production image. It briefly disconnects active sessions but preserves the
+  external workspace, lifetime, and start time. The wait completes only when
+  the observed digest and generation both match the accepted target.
 - Guarded reload powers the server off first. Runtime-enabled reload requires a
   second acknowledgment, after which the CLI guides supervisor reinstall and
   pinned connection-profile refresh. Post-reload owner SSH host keys must be
@@ -319,6 +324,13 @@ warpmetal sandbox create \
   --size small \
   --wait \
   --json
+warpmetal sandbox action \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --action refresh_image \
+  --confirm refresh_image \
+  --wait \
+  --json
 warpmetal sandbox access keygen \
   --output ~/.ssh/warpmetal-planner \
   --confirm GENERATE \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {

package/skills/warpmetal/references/cli-reference.md

@@ -215,7 +215,7 @@ warpmetal sandbox list --server <serverId> --json
 warpmetal sandbox get --server <serverId> --sandbox <sandboxId> [--wait] --json
 warpmetal sandbox action \
   --server <serverId> --sandbox <sandboxId> \
-  --action <start|stop|restart|make_persistent> --confirm <same-action> \
+  --action <start|stop|restart|make_persistent|refresh_image> --confirm <same-action> \
   [--wait] --json
 warpmetal sandbox delete \
   --server <serverId> --sandbox <sandboxId> --confirm DELETE [--wait] --json

package/skills/warpmetal/references/runtime.md

@@ -139,6 +139,25 @@ Use `sandbox list`, `sandbox get --wait`, and guarded `sandbox action` commands
 to observe and change desired state. HTTP 202 and CLI exit 8 mean accepted or
 pending, not complete.
 
+Refresh an existing sandbox to the current immutable production image only
+after the owner approves the brief connection interruption:
+
+```sh
+warpmetal sandbox action \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --action refresh_image \
+  --confirm refresh_image \
+  --wait \
+  --json
+```
+
+The supervisor must already support image refresh. The action pre-pulls and
+replaces only the container root filesystem while retaining the external
+workspace, sandbox lifetime, and original start time. `--wait` requires both
+the observed digest and generation to match the accepted target. A change to
+the global production image does not refresh existing sandboxes implicitly.
+
 Manual deletion is irreversible:
 
 ```sh

package/src/api.js

@@ -347,10 +347,14 @@ export class WarpMetalClient {
   }
 
   sandboxAction(serverId, sandboxId, action, token, idempotencyKey) {
+    const body =
+      action === "refresh_image"
+        ? { action, confirm: "refresh_image" }
+        : { action };
     return this.request(
       "POST",
       `/servers/${encodeURIComponent(serverId)}/sandboxes/${encodeURIComponent(sandboxId)}/actions`,
-      { body: { action }, token, idempotencyKey },
+      { body, token, idempotencyKey },
     );
   }
 

package/src/cli.js

@@ -114,6 +114,8 @@ Usage:
   warpmetal sandbox create --server <serverId> --name <name> --size <size>
     [--lifetime temporary] [--expires-in-seconds <n>] [--confirm TEMPORARY] [--wait]
   warpmetal sandbox create --server <serverId> --file <batch.json> [--confirm TEMPORARY]
+  warpmetal sandbox action --server <serverId> --sandbox <sandboxId>
+    --action <start|stop|restart|make_persistent|refresh_image> --confirm <same-action> [--wait]
   warpmetal sandbox list|get|action|delete ...
   warpmetal sandbox access keygen --output <private-key-path> --confirm GENERATE
   warpmetal sandbox access grant|list|get|revoke ...
@@ -2205,9 +2207,17 @@ async function handleSandboxAction(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const sandboxId = stringOption(options, "sandbox", { required: true });
   const action = stringOption(options, "action", { required: true });
-  if (!["start", "stop", "restart", "make_persistent"].includes(action)) {
+  if (
+    ![
+      "start",
+      "stop",
+      "restart",
+      "make_persistent",
+      "refresh_image",
+    ].includes(action)
+  ) {
     throw new CliError(
-      "--action must be start, stop, restart, or make_persistent.",
+      "--action must be start, stop, restart, make_persistent, or refresh_image.",
       {
         exitCode: 2,
       },
@@ -2231,6 +2241,11 @@ async function handleSandboxAction(client, store, options, context) {
   );
   if (booleanOption(options, "wait")) {
     const accepted = result.data.sandbox;
+    if (action === "refresh_image" && !accepted.desiredImageDigest) {
+      throw new CliError(
+        "WarpMetal accepted image refresh without an immutable desired image digest.",
+      );
+    }
     const expectedState =
       accepted.desiredState === "stopped" ? "stopped" : "running";
     result = await pollSandbox(
@@ -2241,7 +2256,9 @@ async function handleSandboxAction(client, store, options, context) {
       integerOption(options, "timeout-seconds", 900),
       (sandbox) =>
         sandbox.observedState === expectedState &&
-        Number(sandbox.observedGeneration) >= Number(accepted.generation),
+        Number(sandbox.observedGeneration) >= Number(accepted.generation) &&
+        (action !== "refresh_image" ||
+          sandbox.imageDigest === accepted.desiredImageDigest),
     );
   }
   await store.saveSandboxes(serverId, [result.data.sandbox]);