warpmetal 0.8.6 → 0.8.7

package/README.md

@@ -349,6 +349,36 @@ warpmetal sandbox access keygen \
   --json
 ```
 
+WarpMetal CLI v0.8.7 with Agent Runtime v0.1.25 or newer can enable the narrowly
+scoped AppArmor exception required by a verified workload that creates an inner
+Bubblewrap PID namespace and private `/proc`:
+
+```sh
+warpmetal runtime install \
+  --server <serverId> \
+  --ssh-user root \
+  --confirm INSTALL \
+  --nested-private-procfs enable \
+  --wait \
+  --json
+```
+
+This is an explicit host-scoped opt-in for nested-Bubblewrap hosts, not a
+requirement for ordinary VPS or Runtime workloads that use only the outer
+sandbox. The default `preserve` action leaves the current policy state
+unchanged. Use `disable` during an approved maintenance window to unload
+WarpMetal's policy and restore the pre-install file and loaded-policy state.
+Because Runtime sandboxes share one Unix owner, treat an enabled policy as
+available to every sandbox on that Runtime host whose process matches the
+signed, root-owned bwrap path; it is not a per-sandbox permission.
+
+Common inner-boundary designs are planning with an exact read-only checkout,
+coding with only one approved checkout and output directory writable, and QA
+with an exact candidate plus isolated test processes and scratch space. The
+boundary protects a persistent trusted runner from repository-controlled
+commands and sibling attempts. GitHub access, installing Codex or another AI
+CLI, and delegating to subagents do not by themselves require this capability.
+
 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

package/package.json

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

package/skills/warpmetal/SKILL.md

@@ -283,6 +283,16 @@ sizes. Use `--runtime-file` to include sandbox intent in an unpaid order, or
 `warpmetal runtime enable` after the VPS is ready. Supervisor installation is
 separate and requires approval plus `--confirm INSTALL`.
 
+For any verified workload that creates an inner Bubblewrap PID namespace and
+private `/proc`, CLI 0.8.7 with Runtime 0.1.25 or newer may add
+`--nested-private-procfs enable` to the approved Runtime install. Planning with
+a read-only checkout, coding in one writable checkout, and independent QA are
+common uses. GitHub access, an AI CLI, or subagent delegation alone does not
+require it. Omission means `preserve`, which leaves policy state unchanged;
+`disable` is an explicit maintenance action. The exception is host-scoped
+rather than sandbox-scoped, so separate workloads onto different VPS hosts when
+they must not share it.
+
 Omitted lifetime means persistent. A temporary sandbox requires
 `--confirm TEMPORARY`, expires 15 minutes to 24 hours after first reaching
 running, and permanently deletes its workspace at expiry. Never describe a

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

@@ -212,7 +212,9 @@ 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 root \
-  --confirm INSTALL [--wait] [--timeout-seconds <n>] --json
+  --confirm INSTALL \
+  [--nested-private-procfs <preserve|enable|disable>] \
+  [--wait] [--timeout-seconds <n>] --json
 
 warpmetal sandbox create \
   --server <serverId> --name <name> --size <small|medium|large|xlarge> \
@@ -230,6 +232,15 @@ warpmetal sandbox delete \
   --server <serverId> --sandbox <sandboxId> --confirm DELETE [--wait] --json
 ```
 
+The nested-private-procfs action requires CLI 0.8.7 and Runtime 0.1.25 or
+newer. It defaults to `preserve`. `enable` is a host-level opt-in for any
+verified workload that creates an inner Bubblewrap PID namespace and private
+`/proc`; read-only planning, single-workspace coding, and independent QA are
+common examples. GitHub use, an AI CLI, or subagent delegation alone does not
+require it. `disable` unloads WarpMetal's policy and restores the recorded
+pre-enable state. It is not a per-sandbox capability because Runtime sandboxes
+share one Unix owner.
+
 See [runtime.md](runtime.md) for capacity, lifetime, cleanup, polling, and
 installation safety. Exit 8 means accepted or pending, never applied.
 

package/skills/warpmetal/references/runtime.md

@@ -58,6 +58,7 @@ warpmetal runtime install \
   --identity <owner-private-key-path> \
   --ssh-user root \
   --confirm INSTALL \
+  [--nested-private-procfs <preserve|enable|disable>] \
   --wait \
   --json
 warpmetal runtime get --server <serverId> --wait --json
@@ -68,6 +69,29 @@ 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.
 
+`--nested-private-procfs` is supported by `warpmetal` CLI 0.8.7 with Agent
+Runtime 0.1.25 or newer. Its default is `preserve`, which makes no AppArmor
+policy change. Select `enable` only when this VPS is intentionally dedicated to
+a verified workload that creates an inner Bubblewrap PID namespace and private
+procfs. Ordinary VPS users and Runtime workloads that rely only on the outer
+sandbox do not need it. Select `disable` only during an approved maintenance
+action to unload WarpMetal's policy and restore the exact file and loaded-policy
+state that existed before enablement.
+
+Examples include a planner with an exact read-only checkout, a coder with only
+one approved checkout and output directory writable, and QA with an exact
+candidate plus isolated test processes and scratch space. This protects a
+persistent trusted runner from repository-controlled commands and sibling
+attempts. GitHub access, installing an AI CLI, and subagent delegation alone do
+not require nested private procfs.
+
+This setting is host-scoped, not sandbox-scoped. Runtime sandboxes share one
+Unix owner, so every sandbox on the host can use the exception only through the
+signed, root-owned, fixed bwrap path matched by the policy. Enabling it does not
+authorize arbitrary bwrap binaries or change the trust boundary for the
+Runtime image selected by WarpMetal's authenticated backend. Isolate workloads
+on separate VPS hosts if they must not share this host capability.
+
 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
@@ -92,6 +116,16 @@ host automatically:
   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.
+- `runtime_nested_private_procfs_architecture_unsupported`: the requested
+  coding-host policy is unsupported by this CPU architecture;
+- `runtime_apparmor_state_unverifiable`: the host's current AppArmor state
+  cannot be established safely;
+- `runtime_apparmor_policy_conflict`: an existing file or loaded-policy state
+  conflicts with WarpMetal's recorded transaction;
+- `runtime_apparmor_policy_rollback_failed`: the installer could not restore
+  the exact prior AppArmor state; stop and perform operator recovery.
+- `runtime_apparmor_policy_recovery_failed`: an interrupted prior policy
+  transaction could not be recovered; stop and perform operator recovery.
 
 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

package/src/cli.js

@@ -110,7 +110,7 @@ Usage:
   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>
-    --confirm INSTALL [--wait]
+    --confirm INSTALL [--nested-private-procfs <preserve|enable|disable>] [--wait]
   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]
@@ -132,6 +132,16 @@ Global options:
   --help                 Show help
   --version              Show the CLI version
 
+Nested private procfs (CLI 0.8.7+, Runtime 0.1.25+):
+  preserve               Default; do not inspect or change AppArmor policy state
+  enable                 Enable the exact-path Bubblewrap policy on an amd64 host
+  disable                Remove it and restore the recorded pre-enable policy state
+
+Use enable once per dedicated Runtime host when a verified workload creates an
+inner Bubblewrap PID namespace and private /proc. Planning, coding, and QA are
+common examples. GitHub access, an AI CLI, and subagent delegation alone do not
+require it. The capability is host-scoped, not per-sandbox.
+
 Credential environment variables:
   WARPMETAL_OWNER_TOKEN  Recovery/bootstrap credential for one explicit command
   WARPMETAL_ACCESS_TOKEN Short-lived SSH-derived credential for one explicit command
@@ -2140,6 +2150,14 @@ async function handleRuntimeInstall(client, store, options, context) {
     stringOption(options, "identity"),
   );
   const sshUser = stringOption(options, "ssh-user", { required: true });
+  const nestedPrivateProcfs =
+    stringOption(options, "nested-private-procfs") || "preserve";
+  if (!["preserve", "enable", "disable"].includes(nestedPrivateProcfs)) {
+    throw new CliError(
+      "--nested-private-procfs must be preserve, enable, or disable.",
+      { exitCode: 2 },
+    );
+  }
   if (stringOption(options, "confirm", { required: true }) !== "INSTALL") {
     throw new CliError(
       "Confirm supervisor installation with --confirm INSTALL.",
@@ -2167,6 +2185,7 @@ async function handleRuntimeInstall(client, store, options, context) {
     identity,
     sshUser,
     bootstrap: bootstrap.data,
+    nestedPrivateProcfs,
     fetchImpl: context.fetchImpl,
     spawnImpl: context.spawnImpl,
   });
@@ -2975,6 +2994,7 @@ async function dispatch(positionals, options, passthrough, context) {
         "identity",
         "ssh-user",
         "confirm",
+        "nested-private-procfs",
         "idempotency-key",
         "wait",
         "timeout-seconds",

package/src/installer.js

@@ -5,14 +5,14 @@ import {
   verify as verifySignature,
 } from "node:crypto";
 import { spawn as nodeSpawn } from "node:child_process";
-import { access, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
 import { CliError } from "./errors.js";
 
 const MAX_ARTIFACT_BYTES = 256 * 1024 * 1024;
-const REQUIRED_FILES = [
+const BASE_REQUIRED_FILES = [
   "install.sh",
   "warpmetal-agentctl",
   "warpmetal-sandbox-gateway",
@@ -24,6 +24,26 @@ const REQUIRED_FILES = [
   "warpmetal-sandbox.conf",
 ];
 
+const NESTED_PRIVATE_PROCFS_FILES = [
+  "nested-private-procfs-oracle.sh",
+  "warpmetal-agent-runtime-bwrap",
+  "warpmetal-apparmor-policy.sh",
+  "warpmetal-policy-metadata",
+];
+
+function supportsNestedPrivateProcfs(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return false;
+  const [, major, minor, patch] = match.map(Number);
+  return major > 0 || minor > 1 || (minor === 1 && patch >= 25);
+}
+
+function requiredFiles(version) {
+  return supportsNestedPrivateProcfs(version)
+    ? [...BASE_REQUIRED_FILES, ...NESTED_PRIVATE_PROCFS_FILES]
+    : BASE_REQUIRED_FILES;
+}
+
 const INSTALLER_ERROR_MESSAGES = new Map([
   [
     "runtime_install_lock_unavailable",
@@ -77,12 +97,75 @@ const INSTALLER_ERROR_MESSAGES = new Map([
     "runtime_legacy_migration_required",
     "Existing preview Agent Runtime state requires a separately reviewed migration; it was not reset.",
   ],
+  [
+    "runtime_nested_private_procfs_architecture_unsupported",
+    "Nested private procfs is unavailable on this host architecture.",
+  ],
+  [
+    "runtime_nested_private_procfs_mode_invalid",
+    "The Agent Runtime installer rejected the nested-private-procfs action.",
+  ],
+  [
+    "runtime_apparmor_policy_bundle_invalid",
+    "The signed Runtime bundle does not contain a valid nested-private-procfs policy set.",
+  ],
+  [
+    "runtime_apparmor_state_unverifiable",
+    "The server's AppArmor state could not be verified safely.",
+  ],
+  [
+    "runtime_apparmor_policy_unsupported",
+    "The server cannot safely enable the nested-private-procfs AppArmor policy.",
+  ],
+  [
+    "runtime_apparmor_policy_backup_failed",
+    "The existing AppArmor policy state could not be preserved exactly.",
+  ],
+  [
+    "runtime_apparmor_policy_conflict",
+    "The server has a conflicting nested-private-procfs AppArmor policy state.",
+  ],
+  [
+    "runtime_apparmor_policy_parse_failed",
+    "The signed nested-private-procfs AppArmor policy did not pass host validation.",
+  ],
+  [
+    "runtime_apparmor_policy_install_failed",
+    "The nested-private-procfs AppArmor policy could not be installed safely.",
+  ],
+  [
+    "runtime_apparmor_policy_load_failed",
+    "The nested-private-procfs AppArmor policy could not be loaded and verified.",
+  ],
+  [
+    "runtime_apparmor_policy_disable_failed",
+    "The nested-private-procfs AppArmor policy could not be disabled and restored safely.",
+  ],
+  [
+    "runtime_apparmor_policy_rollback_failed",
+    "The AppArmor policy transaction could not restore its prior state; operator recovery is required.",
+  ],
+  [
+    "runtime_apparmor_policy_recovery_failed",
+    "A prior interrupted AppArmor policy transaction could not be recovered; operator recovery is required.",
+  ],
 ]);
 
+const RECOVERY_ERROR_PRIORITY = [
+  "runtime_apparmor_policy_rollback_failed",
+  "runtime_apparmor_policy_recovery_failed",
+];
+
 function mappedInstallerError(result) {
   const lines = `${result.stderr}\n${result.stdout}`
     .split(/\r?\n/)
     .map((line) => line.trim());
+  for (const code of RECOVERY_ERROR_PRIORITY) {
+    if (lines.includes(code)) {
+      const message = INSTALLER_ERROR_MESSAGES.get(code);
+      return { code, message: `${message} (${code})` };
+    }
+  }
   for (const [code, message] of INSTALLER_ERROR_MESSAGES) {
     if (lines.includes(code)) return { code, message: `${message} (${code})` };
   }
@@ -271,6 +354,7 @@ export async function installRuntime({
   identity,
   sshUser,
   bootstrap,
+  nestedPrivateProcfs = "preserve",
   fetchImpl = globalThis.fetch,
   spawnImpl = nodeSpawn,
 }) {
@@ -284,6 +368,20 @@ export async function installRuntime({
     });
   }
   const metadata = validateArtifact(bootstrap?.artifact);
+  if (!new Set(["preserve", "enable", "disable"]).has(nestedPrivateProcfs)) {
+    throw new CliError("The nested private procfs action is invalid.", {
+      exitCode: 2,
+    });
+  }
+  if (
+    nestedPrivateProcfs !== "preserve" &&
+    !supportsNestedPrivateProcfs(metadata.version)
+  ) {
+    throw new CliError(
+      `Agent Runtime ${metadata.version} does not support nested private procfs actions.`,
+      { exitCode: 4 },
+    );
+  }
   const bootstrapToken = bootstrap?.bootstrapToken;
   if (
     typeof bootstrapToken !== "string" ||
@@ -316,16 +414,26 @@ export async function installRuntime({
         spawnImpl,
       },
     );
-    for (const file of REQUIRED_FILES) await access(join(extractPath, file));
-    const unexpected = (await readdir(extractPath)).filter(
-      (name) => !REQUIRED_FILES.includes(name),
-    );
-    if (unexpected.length > 0) {
+    const expectedFiles = requiredFiles(metadata.version);
+    const actualFiles = await readdir(extractPath);
+    const exactNames =
+      actualFiles.length === expectedFiles.length &&
+      expectedFiles.every((name) => actualFiles.includes(name));
+    if (!exactNames) {
       throw new CliError(
-        "The signed runtime bundle contains unsupported files.",
+        "The signed runtime bundle files do not match this CLI version.",
         { exitCode: 4 },
       );
     }
+    for (const file of expectedFiles) {
+      const metadata = await lstat(join(extractPath, file));
+      if (!metadata.isFile() || metadata.isSymbolicLink()) {
+        throw new CliError(
+          "The signed runtime bundle files do not match this CLI version.",
+          { exitCode: 4 },
+        );
+      }
+    }
     remoteTouched = true;
     await spawnChecked(
       "scp",
@@ -351,19 +459,23 @@ export async function installRuntime({
       ],
       { spawnImpl },
     );
+    const installerArguments = [
+      ...ssh,
+      "sudo",
+      `${remoteBundle}/install.sh`,
+      "--api",
+      client.baseUrl,
+      "--server",
+      serverId,
+      "--bundle",
+      remoteBundle,
+    ];
+    if (nestedPrivateProcfs !== "preserve") {
+      installerArguments.push("--nested-private-procfs", nestedPrivateProcfs);
+    }
     await spawnChecked(
       "ssh",
-      [
-        ...ssh,
-        "sudo",
-        `${remoteBundle}/install.sh`,
-        "--api",
-        client.baseUrl,
-        "--server",
-        serverId,
-        "--bundle",
-        remoteBundle,
-      ],
+      installerArguments,
       {
         stdin: `${bootstrapToken}\n`,
         spawnImpl,
@@ -378,7 +490,12 @@ export async function installRuntime({
         spawnImpl,
       },
     );
-    return { serverId, supervisorVersion: metadata.version, installed: true };
+    return {
+      serverId,
+      supervisorVersion: metadata.version,
+      installed: true,
+      nestedPrivateProcfsAction: nestedPrivateProcfs,
+    };
   } catch (error) {
     operationFailed = true;
     throw error;