warpmetal 0.8.1 → 0.8.3

package/README.md

@@ -98,6 +98,11 @@ checkout returns `serverId`, the CLI binds that ID to the identity so
 an `--identity` flag. Use `--ssh-public-key-file` instead when supplying a
 user-managed public key.
 
+WarpMetal installs the owner key for `root` on every supported image. The SSH
+key does not encode a login username: use `root@<server-ip>` for an owner shell
+and `--ssh-user root` for runtime installation, not a distribution convention
+such as `ubuntu`.
+
 Pass `--json` for structured, secret-redacted output. Use
 `WARPMETAL_API_URL` for an alternate API origin and `WARPMETAL_HOME` for an
 alternate state directory.
@@ -304,7 +309,7 @@ compatible external signer.
 warpmetal runtime enable --server <serverId> --json
 warpmetal runtime install \
   --server <serverId> \
-  --ssh-user ubuntu \
+  --ssh-user root \
   --confirm INSTALL \
   --wait \
   --json
@@ -320,6 +325,17 @@ warpmetal sandbox access keygen \
   --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.1",
+  "version": "0.8.3",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {

package/skills/warpmetal/SKILL.md

@@ -209,6 +209,13 @@ key-only policy: `PasswordAuthentication no`,
 `KbdInteractiveAuthentication no`, `PermitRootLogin prohibit-password`, and
 `AuthenticationMethods publickey`.
 
+The WarpMetal owner SSH account is `root` on every supported image. SSH public
+keys do not bind a login username. Use `root@<server-ip>` for an owner shell and
+pass `--ssh-user root` whenever a CLI command asks for the owner SSH account;
+never infer `ubuntu` or another distribution-default username. This does not
+apply to `sandbox connect`, which uses the gateway username from its connection
+profile.
+
 For routine management, prove possession of the installed SSH key without
 reading it:
 

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

@@ -202,7 +202,7 @@ process listings.
 warpmetal runtime enable --server <serverId> [--idempotency-key <key>] --json
 warpmetal runtime get --server <serverId> [--wait] [--timeout-seconds <n>] --json
 warpmetal runtime install \
-  --server <serverId> [--identity <owner-key>] --ssh-user <admin-user> \
+  --server <serverId> [--identity <owner-key>] --ssh-user root \
   --confirm INSTALL [--wait] [--timeout-seconds <n>] --json
 
 warpmetal sandbox create \

package/skills/warpmetal/references/runtime.md

@@ -48,12 +48,15 @@ the existing separate interactive-or-autonomous payment authority check.
 
 For an existing ready server:
 
+Use the WarpMetal owner account `root` for every supported host image; do not
+substitute a distribution-default account such as `ubuntu`.
+
 ```sh
 warpmetal runtime enable --server <serverId> --json
 warpmetal runtime install \
   --server <serverId> \
   --identity <owner-private-key-path> \
-  --ssh-user <os-admin-user> \
+  --ssh-user root \
   --confirm INSTALL \
   --wait \
   --json
@@ -65,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

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",