warpmetal 0.8.2 → 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,12 +324,30 @@ 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 \
   --json
 ```
 
+Installation gives pre-existing Docker containers exact liveness checks and
+tracks common container-runtime processes without collecting application
+configuration. The signed installer uses `crun` for its private rootless Podman
+engine, refuses package removals or changes to an installed container stack,
+and checks minimal liveness metadata after package installation and again
+immediately before registration. Safety refusals have no force bypass; review
+the reported `runtime_*` code instead of changing or restarting a third-party
+runtime automatically. With `--json`, that code is returned as structured
+`error.code`. A pending reboot and legacy preview Podman state are separate
+maintenance operations, not implicit install steps.
+
 See `skills/warpmetal/references/runtime.md` for the complete lifecycle,
 cleanup, access-grant, and strict host-key connection workflow.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.8.2",
+  "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

@@ -68,6 +68,36 @@ The CLI holds the one-time bootstrap only in memory, verifies the signed
 artifact, uploads it through OpenSSH without a shell-enabled local spawn, and
 does not print or store the bootstrap.
 
+The signed installer is designed to preserve container workloads already
+running on a supported host. It selects `crun` for WarpMetal's private rootless
+Podman service, refuses APT removals and DNF erasures, protects installed
+Docker/containerd/Podman and package-manager versions, and compares a minimal
+root-only liveness snapshot after the guarded package action and immediately
+before registration. The snapshot contains recognized runtime-process start
+metadata and, when Docker is active, container IDs, init PIDs, and start
+timestamps. Docker receives container-level checks; other recognized engines
+receive process-level checks and need separate certification for broader
+coexistence claims. The snapshot never collects names, images, environment,
+mounts, or logs.
+
+Treat these refusal codes as safety gates, not prompts to force or repair the
+host automatically:
+
+- `runtime_package_plan_unsafe`: the proposed package transaction was refused;
+- `runtime_workload_state_unverifiable`: an active Docker workload could not be
+  inspected safely;
+- `runtime_workload_drift_detected`: a pre-existing runtime process or Docker
+  container changed during the installation window;
+- `runtime_package_postcondition_failed`: a protected container package changed
+  unexpectedly; stop and review the host package logs;
+- `runtime_legacy_migration_required`: preview Podman state needs a separate,
+  explicitly reviewed migration and was not reset.
+
+There is no force bypass. If `runtime_reboot_required` is returned, schedule
+the reboot as a separate maintenance action and retry only after the host and
+its existing workloads are healthy. The ordinary installer never installs a
+kernel or runs `podman system reset`.
+
 ## Sizes and lifetime
 
 Use `small`, `medium`, `large`, or `xlarge` exactly as the live catalog
@@ -109,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]);

package/src/errors.js

@@ -1,9 +1,13 @@
 export class CliError extends Error {
-  constructor(message, { exitCode = 1, details = undefined } = {}) {
+  constructor(
+    message,
+    { exitCode = 1, details = undefined, code = undefined } = {},
+  ) {
     super(message);
     this.name = "CliError";
     this.exitCode = exitCode;
     this.details = details;
+    this.code = code ?? details?.code;
   }
 }
 

package/src/installer.js

@@ -24,6 +24,71 @@ const REQUIRED_FILES = [
   "warpmetal-sandbox.conf",
 ];
 
+const INSTALLER_ERROR_MESSAGES = new Map([
+  [
+    "runtime_install_lock_unavailable",
+    "The server cannot create the Agent Runtime installation lock.",
+  ],
+  [
+    "runtime_install_state_unavailable",
+    "The server cannot create private temporary state for the installation checks.",
+  ],
+  [
+    "runtime_install_in_progress",
+    "Another Agent Runtime installation is already running on this server.",
+  ],
+  [
+    "runtime_reboot_required",
+    "The server already requires a reboot. Reboot it as a separate maintenance action, then retry.",
+  ],
+  [
+    "runtime_package_index_failed",
+    "The server package index could not be refreshed; no Agent Runtime services were changed.",
+  ],
+  [
+    "runtime_package_plan_unsafe",
+    "Installation refused a package transaction that could change the existing container stack.",
+  ],
+  [
+    "runtime_package_apply_failed",
+    "The guarded dependency transaction failed; the Agent Runtime supervisor was not registered.",
+  ],
+  [
+    "runtime_package_postcondition_failed",
+    "An installed container package changed unexpectedly. Do not retry until the host package state is reviewed.",
+  ],
+  [
+    "runtime_workload_state_unverifiable",
+    "Installation could not safely inspect the existing container workload state.",
+  ],
+  [
+    "runtime_workload_drift_detected",
+    "An existing container workload changed during installation. Do not retry until the host runtime is reviewed.",
+  ],
+  [
+    "runtime_oci_runtime_unavailable",
+    "The certified crun OCI runtime is unavailable on this server.",
+  ],
+  [
+    "runtime_podman_unavailable",
+    "The private Podman service did not become available.",
+  ],
+  [
+    "runtime_legacy_migration_required",
+    "Existing preview Agent Runtime state requires a separately reviewed migration; it was not reset.",
+  ],
+]);
+
+function mappedInstallerError(result) {
+  const lines = `${result.stderr}\n${result.stdout}`
+    .split(/\r?\n/)
+    .map((line) => line.trim());
+  for (const [code, message] of INSTALLER_ERROR_MESSAGES) {
+    if (lines.includes(code)) return { code, message: `${message} (${code})` };
+  }
+  return undefined;
+}
+
 function validateArtifact(artifact) {
   if (
     !artifact ||
@@ -130,7 +195,7 @@ function appendBounded(current, chunk) {
 async function spawnChecked(
   command,
   args,
-  { stdin, spawnImpl = nodeSpawn, redact = [] } = {},
+  { stdin, spawnImpl = nodeSpawn, redact = [], mapError } = {},
 ) {
   const result = await new Promise((resolvePromise, reject) => {
     const child = spawnImpl(command, args, {
@@ -151,13 +216,18 @@ async function spawnChecked(
     else child.stdin?.end();
   });
   if (result.status !== 0) {
+    const mappedError = mapError?.(result);
     let message =
+      mappedError?.message ||
       result.stderr.trim() ||
       result.stdout.trim() ||
       `${command} exited unsuccessfully`;
     for (const secret of redact)
       if (secret) message = message.split(secret).join("[redacted]");
-    throw new CliError(message.slice(0, 500), { exitCode: 4 });
+    throw new CliError(message.slice(0, 500), {
+      exitCode: 4,
+      code: mappedError?.code,
+    });
   }
   return result;
 }
@@ -286,7 +356,12 @@ export async function installRuntime({
         "--bundle",
         remoteBundle,
       ],
-      { stdin: `${bootstrapToken}\n`, spawnImpl, redact: [bootstrapToken] },
+      {
+        stdin: `${bootstrapToken}\n`,
+        spawnImpl,
+        redact: [bootstrapToken],
+        mapError: mappedInstallerError,
+      },
     );
     await spawnChecked(
       "ssh",