warpmetal 0.2.3 → 0.3.0

package/README.md

@@ -4,8 +4,8 @@ The official command-line client and portable Agent Skill for WarpMetal.
 
 The CLI uses the public API at `https://api.warpmetal.com`, stores generated
 WarpMetal credentials in a user-private state file, and never reads or stores
-wallet private keys or SSH private-key contents. Version 0.2 adds the optional
-Agent Runtime workflow for fixed-size, isolated sandboxes on one owner's VPS.
+wallet private keys or SSH private-key contents. Version 0.3 adds guarded OS
+reload and Agent Runtime recovery to the fixed-size, isolated sandbox workflow.
 
 ## Distribution
 
@@ -69,7 +69,7 @@ alternate state directory.
   every OS reload. Password and keyboard-interactive login are disabled; never
   request, store, or expect a VPS login password.
 - The CLI accepts an externally produced x402 `PAYMENT-SIGNATURE` from a file.
-  Wallet key management and signing remain outside this package.
+Wallet key management and signing remain outside this package.
 - Destructive or state-changing commands require explicit confirmations and
   generate idempotency keys by default.
 - Runtime bootstrap credentials remain memory-only. Signed supervisor bundles
@@ -80,6 +80,11 @@ alternate state directory.
 - 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.
+- 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. Replacement owner SSH host keys must be
+  verified before updating `known_hosts`; erased workspaces are never described
+  as recoverable.
 
 ## Agent Runtime example
 

package/package.json

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

package/skills/warpmetal/SKILL.md

@@ -118,13 +118,31 @@ warpmetal server power \
   --json
 ```
 
-Do not fall back to raw API calls for reload, deletion, networking, renewal,
-or another unsupported mutation. Explain that the installed CLI version does
-not yet expose that guarded operation. The public reload contract requires
-both `confirm: "ERASE"` and `powerOffFirst: true`; the latter authorizes the
-same lifecycle operation to shut down the server and wait for provider power
-off before erasing it. This contract knowledge is not permission to bypass the
-CLI restriction.
+For a destructive reload, explain that every server-disk file is erased and
+obtain explicit approval. If Agent Runtime is enabled, also explain that every
+sandbox workspace is lost, desired sandboxes return as empty workspaces after
+reinstall, and pinned profiles must be refreshed. Then use only the guarded
+command:
+
+```sh
+warpmetal server reload \
+  --server <serverId> \
+  --confirm ERASE \
+  --power-off-first \
+  [--acknowledge-agent-runtime-reset] \
+  [--os '<exact-live-os-name>'] \
+  --wait \
+  --json
+```
+
+The CLI requires the recovery owner credential so it can keep polling after
+reload revokes SSH-derived access tokens. On success, reinstall Agent Runtime
+only after verifying the replacement owner-facing SSH host-key fingerprint
+through a trusted provider or console channel and safely updating
+`known_hosts`. Never bypass a mismatch. Then wait for grants to become applied and refresh every
+connection profile with `sandbox access refresh --confirm REFRESH` before
+connecting. Do not fall back to raw API calls for deletion, networking,
+renewal, or another unsupported mutation.
 
 ## Use Agent Runtime
 

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

@@ -68,6 +68,12 @@ warpmetal server power \
   [--wait] [--timeout-seconds <n>] \
   --json
 
+warpmetal server reload \
+  --server <serverId> --confirm ERASE --power-off-first \
+  [--acknowledge-agent-runtime-reset] [--hostname <name>] \
+  [--os <exact-live-os-name>] [--ssh-public-key-file <public-key-path>] \
+  [--idempotency-key <key>] [--wait] [--timeout-seconds <n>] --json
+
 warpmetal operation get \
   --operation <operationId> \
   [--server <serverId>] \
@@ -75,10 +81,11 @@ warpmetal operation get \
   --json
 ```
 
-This CLI version does not expose reload. The public reload API requires both
-`confirm: "ERASE"` and `powerOffFirst: true`, with shutdown, powered-off
-verification, and reload handled by one lifecycle operation. Do not call that
-endpoint with raw HTTP; wait for a guarded CLI command.
+Reload requires the recovery owner credential rather than a short-lived
+SSH-derived token. `--power-off-first` authorizes shutdown and powered-off
+verification inside the same operation. When Agent Runtime is enabled,
+`--acknowledge-agent-runtime-reset` is required because workspaces are erased,
+the supervisor must be reinstalled, and connection profiles must be refreshed.
 
 Use `--token-file` only for recovery when local state is unavailable. Prefer
 `WARPMETAL_OWNER_TOKEN` or `WARPMETAL_ACCESS_TOKEN` for a single command over a
@@ -124,6 +131,9 @@ warpmetal sandbox access grant \
 warpmetal sandbox access list --server <serverId> --sandbox <sandboxId> --json
 warpmetal sandbox access get \
   --server <serverId> --sandbox <sandboxId> --grant <grantId> [--wait] --json
+warpmetal sandbox access refresh \
+  --server <serverId> --sandbox <sandboxId> --grant <grantId> \
+  --connection-file <profile-path> --confirm REFRESH [--wait] --json
 warpmetal sandbox access revoke \
   --server <serverId> --sandbox <sandboxId> --grant <grantId> \
   --confirm REVOKE [--wait] --json
@@ -134,6 +144,9 @@ warpmetal sandbox connect --connection-file <profile-path> \
 `sandbox connect` is the only runtime command that does not use `--json`; it
 returns the OpenSSH or remote exit status. `--connection-file` on grant
 creation requires `--wait`.
+`sandbox access refresh` atomically replaces a stale token-free profile with
+the currently applied grant and API-reported pinned host keys; use it after an
+OS reload and supervisor reinstall.
 
 ## Skill installation and state
 

package/skills/warpmetal/references/runtime.md

@@ -145,6 +145,25 @@ The token-free profile is written only after the grant is `applied` and the
 API supplies verified VPS host keys. Do not print or open that profile in an
 agent conversation.
 
+After a destructive OS reload, reinstall the supervisor and wait for the
+retained active grant to become `applied`, then replace its stale pinned
+profile:
+
+```sh
+warpmetal sandbox access refresh \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --grant <grantId> \
+  --connection-file <profile-path> \
+  --confirm REFRESH \
+  --wait \
+  --json
+```
+
+The sandbox record is retained, but its old workspace is not; reconciliation
+creates a new empty workspace. Never bypass a host-key mismatch or reuse the
+pre-reload profile.
+
 Connect without an owner management credential:
 
 ```sh

package/skills/warpmetal/references/safety.md

@@ -54,8 +54,13 @@ Obtain explicit user approval immediately before:
 A reload requires both `confirm: "ERASE"` and `powerOffFirst: true`. Treat
 `powerOffFirst` as explicit authorization for WarpMetal to shut down the
 server, wait until it is powered off, and then erase and reinstall it inside
-one lifecycle operation. Do not reconstruct this flow with raw HTTP while the
-installed CLI lacks a guarded reload command.
+one lifecycle operation. When Agent Runtime is enabled, also require
+`acknowledgeAgentRuntimeReset`: all sandbox workspaces are permanently erased,
+the supervisor identity is revoked, desired sandboxes are recreated empty
+after reinstall, and all pinned profiles require refresh. Use only the guarded
+CLI command and stop on `manual_review`. Reload also replaces the owner-facing
+SSH host key; verify its fingerprint through a trusted provider or console
+channel before changing `known_hosts`, and never disable host-key checking.
 
 An order preparation is unpaid but consumes a limited prepared-order slot.
 Confirm the plan, hostname, OS, and public key before preparing it.

package/src/api.js

@@ -188,6 +188,18 @@ export class WarpMetalClient {
     );
   }
 
+  reloadServer(serverId, body, token, idempotencyKey) {
+    return this.request(
+      "POST",
+      `/api/servers/${encodeURIComponent(serverId)}/reload`,
+      {
+        body,
+        token,
+        idempotencyKey,
+      },
+    );
+  }
+
   getOperation(operationId, token) {
     return this.request(
       "GET",

package/src/cli.js

@@ -73,6 +73,9 @@ Usage:
   warpmetal server get --server <serverId>
   warpmetal server power --server <serverId> --action <boot|reboot|shutdown>
     --confirm <same-action> [--wait] [--idempotency-key <key>]
+  warpmetal server reload --server <serverId> --confirm ERASE --power-off-first
+    [--acknowledge-agent-runtime-reset] [--hostname <name>] [--os <exact-name>]
+    [--ssh-public-key-file <path>] [--wait] [--idempotency-key <key>]
   warpmetal operation get --operation <operationId> [--server <serverId>] [--wait]
   warpmetal runtime enable|get --server <serverId> [--wait]
   warpmetal runtime install --server <serverId> --identity <owner-key> --ssh-user <user>
@@ -83,6 +86,8 @@ Usage:
   warpmetal sandbox list|get|action|delete ...
   warpmetal sandbox access keygen --output <private-key-path> --confirm GENERATE
   warpmetal sandbox access grant|list|get|revoke ...
+  warpmetal sandbox access refresh --server <serverId> --sandbox <sandboxId>
+    --grant <grantId> --connection-file <path> --confirm REFRESH [--wait]
   warpmetal sandbox connect --connection-file <path> --identity <sandbox-key> [-- <command>]
   warpmetal state list
   warpmetal agent install --target <codex|claude|all> [--scope <user|project>] [--force]
@@ -199,6 +204,19 @@ async function requireServerToken(store, serverId, options, env) {
   return token;
 }
 
+async function requireReloadToken(store, serverId, options, env) {
+  const token =
+    (await credentialFromFile(options)) ||
+    (await store.serverOwnerToken(serverId, env));
+  if (!token) {
+    throw new CliError(
+      `Reload requires the recovery owner credential for ${serverId} so the CLI can poll after SSH-derived tokens are revoked. Restore the private state file, set WARPMETAL_OWNER_TOKEN, or use --token-file.`,
+      { exitCode: 4 },
+    );
+  }
+  return token;
+}
+
 function safePreparedOrder(data, stateFile) {
   return {
     task: data.task,
@@ -614,6 +632,98 @@ async function handleServerPower(client, store, options, context) {
   return result.data.operation.state === "manual_review" ? 6 : 0;
 }
 
+async function applyReloadResult(store, serverId, operation) {
+  if (operation?.state !== "succeeded") return;
+  await store.invalidateServerAccess(serverId);
+  if (operation.result?.reloadImpact?.agentRuntimeAffected) {
+    await store.saveRuntime(serverId, {
+      state: "needs_reinstall",
+      desiredRevision: undefined,
+      appliedRevision: 0,
+      lastSeenAt: null,
+    });
+  }
+}
+
+async function handleServerReload(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  if (stringOption(options, "confirm", { required: true }) !== "ERASE") {
+    throw new CliError("Confirm disk erasure with --confirm ERASE.", {
+      exitCode: 2,
+    });
+  }
+  if (!booleanOption(options, "power-off-first")) {
+    throw new CliError(
+      "Authorize the guarded shutdown with --power-off-first.",
+      { exitCode: 2 },
+    );
+  }
+  const acknowledgeRuntimeReset = booleanOption(
+    options,
+    "acknowledge-agent-runtime-reset",
+  );
+  const token = await requireReloadToken(
+    store,
+    serverId,
+    options,
+    context.env,
+  );
+  const server = (await client.getServer(serverId, token)).data?.task;
+  if (server?.agentRuntime && !acknowledgeRuntimeReset) {
+    throw new CliError(
+      "Agent Runtime is enabled. Reload permanently erases sandbox workspaces, revokes supervisor identity, and requires connection-profile refresh. Confirm with --acknowledge-agent-runtime-reset.",
+      { exitCode: 2 },
+    );
+  }
+
+  const body = {
+    confirm: "ERASE",
+    powerOffFirst: true,
+  };
+  if (acknowledgeRuntimeReset) body.acknowledgeAgentRuntimeReset = true;
+  const hostname = stringOption(options, "hostname");
+  const osName = stringOption(options, "os");
+  const publicKeyFile = stringOption(options, "ssh-public-key-file");
+  if (hostname) body.hostname = hostname;
+  if (osName) body.osName = osName;
+  if (publicKeyFile) body.sshPublicKey = await readSshPublicKey(publicKeyFile);
+
+  const key =
+    stringOption(options, "idempotency-key") || idempotencyKey("reload");
+  let result = await client.reloadServer(serverId, body, token, key);
+  const operationId = result.data?.operation?.id;
+  if (!operationId) {
+    throw new CliError("WarpMetal did not return a reload operation ID.");
+  }
+  await store.saveOperation(operationId, serverId, "reload");
+  if (booleanOption(options, "wait")) {
+    result = await pollOperation(
+      client,
+      operationId,
+      token,
+      integerOption(options, "timeout-seconds", 900),
+    );
+  }
+
+  const operation = result.data?.operation;
+  await applyReloadResult(store, serverId, operation);
+  emit(
+    context.stdout,
+    result.data,
+    context.json,
+    `Reload operation ${operationId}: ${operation?.state}.` +
+      (operation?.state === "succeeded" &&
+      operation.result?.reloadImpact?.agentRuntimeAffected
+        ? " Verify and refresh the owner SSH host key, reinstall Agent Runtime, then refresh every sandbox connection profile."
+        : operation?.state === "succeeded"
+          ? " Verify and refresh the owner SSH host key before reconnecting."
+        : ""),
+  );
+  if (operation?.state === "manual_review") return 6;
+  if (operation?.state === "failed") return 5;
+  return operation?.state === "succeeded" ? 0 : 8;
+}
+
 async function handleOperationGet(client, store, options, context) {
   const operationId = stringOption(options, "operation", { required: true });
   const saved = await store.operation(operationId);
@@ -626,7 +736,10 @@ async function handleOperationGet(client, store, options, context) {
       },
     );
   }
-  const token = await requireServerToken(store, serverId, options, context.env);
+  const token =
+    saved?.kind === "reload"
+      ? await requireReloadToken(store, serverId, options, context.env)
+      : await requireServerToken(store, serverId, options, context.env);
   const result = booleanOption(options, "wait")
     ? await pollOperation(
         client,
@@ -635,6 +748,9 @@ async function handleOperationGet(client, store, options, context) {
         integerOption(options, "timeout-seconds", 900),
       )
     : await client.getOperation(operationId, token);
+  if (saved?.kind === "reload") {
+    await applyReloadResult(store, serverId, result.data?.operation);
+  }
   emit(
     context.stdout,
     result.data,
@@ -1076,6 +1192,69 @@ async function handleAccessGet(client, store, options, context) {
   return result.data.accessGrant.observedState === "failed" ? 5 : 0;
 }
 
+async function handleAccessRefresh(client, store, options, context) {
+  const serverId = stringOption(options, "server", { required: true });
+  const sandboxId = stringOption(options, "sandbox", { required: true });
+  const grantId = stringOption(options, "grant", { required: true });
+  const profilePath = stringOption(options, "connection-file", {
+    required: true,
+  });
+  if (stringOption(options, "confirm", { required: true }) !== "REFRESH") {
+    throw new CliError(
+      "Confirm replacement of the pinned connection profile with --confirm REFRESH.",
+      { exitCode: 2 },
+    );
+  }
+  const token = await requireServerToken(store, serverId, options, context.env);
+  const result = booleanOption(options, "wait")
+    ? await pollGrant(
+        client,
+        serverId,
+        sandboxId,
+        grantId,
+        token,
+        integerOption(options, "timeout-seconds", 900),
+        (accessGrant) => accessGrant.observedState === "applied",
+      )
+    : await client.getAccessGrant(serverId, sandboxId, grantId, token);
+  if (result.data?.accessGrant?.observedState !== "applied") {
+    emit(
+      context.stdout,
+      { accessGrant: result.data?.accessGrant, connectionFile: null },
+      context.json,
+      `Access grant ${grantId} is not applied; no profile was changed.`,
+    );
+    return result.data?.accessGrant?.observedState === "failed" ? 5 : 8;
+  }
+  const profile = connectionProfile(
+    serverId,
+    sandboxId,
+    grantId,
+    result.data.connection,
+  );
+  const writtenConnectionFile = await writeConnectionProfile(
+    profilePath,
+    profile,
+  );
+  await store.saveAccessGrant(
+    serverId,
+    result.data.accessGrant,
+    writtenConnectionFile,
+  );
+  const safe = {
+    accessGrant: result.data.accessGrant,
+    connection: { available: true, profileWritten: true, printed: false },
+    connectionFile: writtenConnectionFile,
+  };
+  emit(
+    context.stdout,
+    safe,
+    context.json,
+    `Refreshed pinned connection profile for ${grantId} at ${writtenConnectionFile}.`,
+  );
+  return 0;
+}
+
 async function handleAccessRevoke(client, store, options, context) {
   const serverId = stringOption(options, "server", { required: true });
   const sandboxId = stringOption(options, "sandbox", { required: true });
@@ -1254,6 +1433,22 @@ async function dispatch(positionals, options, passthrough, context) {
         "timeout-seconds",
       ]);
       return handleServerPower(client, store, options, context);
+    case "server reload":
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "server",
+        "token-file",
+        "confirm",
+        "power-off-first",
+        "acknowledge-agent-runtime-reset",
+        "hostname",
+        "os",
+        "ssh-public-key-file",
+        "idempotency-key",
+        "wait",
+        "timeout-seconds",
+      ]);
+      return handleServerReload(client, store, options, context);
     case "operation get":
       rejectUnknownOptions(options, [
         ...COMMON_OPTIONS,
@@ -1387,6 +1582,19 @@ async function dispatch(positionals, options, passthrough, context) {
         "timeout-seconds",
       ]);
       return handleAccessGet(client, store, options, context);
+    case "sandbox access refresh":
+      rejectUnknownOptions(options, [
+        ...COMMON_OPTIONS,
+        "server",
+        "sandbox",
+        "grant",
+        "token-file",
+        "connection-file",
+        "confirm",
+        "wait",
+        "timeout-seconds",
+      ]);
+      return handleAccessRefresh(client, store, options, context);
     case "sandbox access revoke":
       rejectUnknownOptions(options, [
         ...COMMON_OPTIONS,

package/src/state.js

@@ -261,6 +261,20 @@ export class StateStore {
     return server.ownerToken;
   }
 
+  async serverOwnerToken(serverId, env = process.env) {
+    if (env.WARPMETAL_OWNER_TOKEN) return env.WARPMETAL_OWNER_TOKEN;
+    return (await this.server(serverId))?.ownerToken;
+  }
+
+  async invalidateServerAccess(serverId) {
+    await this.update((state) => {
+      const server = state.servers[serverId];
+      if (!server) return;
+      delete server.accessToken;
+      delete server.accessTokenExpiresAt;
+    });
+  }
+
   async summary() {
     const state = await this.read();
     return {