warpmetal 0.8.5 → 0.8.7

package/README.md

@@ -141,6 +141,18 @@ confirmation is pending. As soon as `confirmed` is true, stop all payment
 submission—even when `finalized` is false—and let WarpMetal continue signed-
 receipt finality while provisioning or renewal proceeds.
 
+For an interactive initial purchase, `checkout challenge` may also return a
+short-lived `humanCheckout` object. Its `url` and `qrPayload` are the same
+`https://pay.x402api.com/c/...` bearer capability for the exact charge; encode
+that URL as the QR, never the WarpMetal recipient address. The buyer connects
+their own wallet and needs only the advertised USDC/USDT balance because
+x402api sponsors the native gas. This is an alternative to the agent-wallet
+workflow, not a second payment. After browser payment, run the exact
+`humanCheckout.afterPayment.argv` status command. When the ready result asks
+for `ask_human_for_notification_email`, ask the owner and add the optional
+lifecycle-notification address they provide. Autonomous purchases and renewals
+continue to use the bounded agent-wallet path.
+
 - When a human is actively chatting with the agent, show the exact live terms
   and ask for confirmation immediately before authorizing and submitting.
 - In an unattended run, a pre-funded dedicated wallet is standing spend
@@ -337,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.5",
+  "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

@@ -88,6 +88,18 @@ returns `paymentTerms` plus exact `paymentWorkflow.authorize.argv` and
 `paymentWorkflow.submit.argv` arrays. Do not reconstruct those commands or
 open either file.
 
+In an interactive initial purchase, the result may also contain
+`humanCheckout`. Offer it as an alternative to the local agent wallet. Show
+`humanCheckout.url` as clickable text and render only the identical
+`humanCheckout.qrPayload` URL as the purchase QR; never render the recipient
+address as this QR. The URL is an expiring bearer capability, so do not log,
+save, or send it anywhere except to the buyer who requested this purchase. If
+the buyer uses it, do not authorize or submit through the agent wallet. Run the
+exact `humanCheckout.afterPayment.argv` command, wait for the server to become
+ready, then follow `ask_human_for_notification_email`: ask the owner for the
+optional lifecycle-notification address and add only the address they provide.
+Ignore this path in unattended purchasing and renewal automation.
+
 Determine payment authority from the current execution context. In an
 interactive conversation, show the human the exact amount, asset, network,
 recipient, profile, and maximum authorization lifetime from `paymentTerms`,
@@ -271,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

@@ -72,6 +72,15 @@ retire that attempt and return a new `paymentAttemptId`. The CLI replaces the
 saved challenge and stale wallet-attempt metadata; use only the newly returned
 workflow.
 
+For interactive initial purchases, the response may additionally include
+`humanCheckout.url`, the identical `qrPayload`, `expiresAt`, and an exact
+`afterPayment.argv` command. The URL is a short-lived bearer capability for the
+same charge, not a recipient address. If the buyer pays in the hosted checkout,
+do not submit an agent-wallet artifact; run the returned status command and,
+after ready, follow `ask_human_for_notification_email` to offer lifecycle
+notices. The CLI does not persist the hosted URL. Renewal commands never expose
+or use this interactive option.
+
 The current integration targets `@x402api/agent-wallet-cli@0.2.9`. A compatible
 live term is marked `agentWalletSupported: true` and must use the sponsored
 Base USDC or Solana USDC/USDT launch profile with buyer native fees disabled.
@@ -203,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> \
@@ -221,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/payments.md

@@ -123,6 +123,16 @@ warpmetal checkout challenge --task <taskId> --json
 Read only the returned safe JSON. Confirm `paymentTerms`, then use the exact
 argv arrays returned under `paymentWorkflow`:
 
+For an interactive initial purchase, an optional `humanCheckout` object offers
+a second presentation path for the same charge. Its `url` and `qrPayload` must
+be identical hosted-checkout URLs; render that URL as the QR and copyable link,
+never a recipient address. If the buyer completes this path, skip agent-wallet
+authorization and run `humanCheckout.afterPayment.argv`. Continue bounded
+status polling until ready, then ask for the optional lifecycle-notification
+email when the result returns `ask_human_for_notification_email`. The hosted
+URL expires at `humanCheckout.expiresAt`, is not persisted by the CLI, and is
+never used for unattended purchases or renewals.
+
 ```text
 paymentWorkflow.authorize.argv
   x402api payment authorize --wallet <wallet-name>

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
@@ -427,7 +437,11 @@ function challengeResult(
   taskId,
   checkoutBody,
   response,
-  { requireChallenge = true } = {},
+  {
+    requireChallenge = true,
+    allowHumanCheckout = false,
+    humanCheckoutContext = undefined,
+  } = {},
 ) {
   const status = response.data?.status;
   const rejected = response.status === 402 && status === "payment_rejected";
@@ -459,6 +473,13 @@ function challengeResult(
       "WarpMetal returned PAYMENT-REQUIRED without X-X402API-Challenge-Digest.",
     );
   }
+  const humanCheckout = allowHumanCheckout
+    ? humanCheckoutResult(
+        response.data?.humanCheckout,
+        taskId,
+        humanCheckoutContext,
+      )
+    : undefined;
   return {
     status,
     taskId,
@@ -469,6 +490,7 @@ function challengeResult(
     challengeHandle,
     challengeDigest,
     checkoutBodySha256: createHash("sha256").update(checkoutBody).digest("hex"),
+    ...(humanCheckout ? { humanCheckout } : {}),
     ...(rejected
       ? {
           errorCode: response.data?.errorCode,
@@ -479,6 +501,74 @@ function challengeResult(
   };
 }
 
+function humanCheckoutResult(value, taskId, { baseUrl, stateDirectory } = {}) {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new CliError("WarpMetal returned malformed hosted checkout details.");
+  }
+  const keys = Object.keys(value).sort();
+  if (keys.join(",") !== "expiresAt,qrPayload,url") {
+    throw new CliError("WarpMetal returned malformed hosted checkout details.");
+  }
+  if (
+    typeof value.url !== "string" ||
+    typeof value.qrPayload !== "string" ||
+    value.url !== value.qrPayload ||
+    typeof value.expiresAt !== "string"
+  ) {
+    throw new CliError("WarpMetal returned malformed hosted checkout details.");
+  }
+  let url;
+  try {
+    url = new URL(value.url);
+  } catch {
+    throw new CliError("WarpMetal returned an invalid hosted checkout URL.");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.origin !== "https://pay.x402api.com" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    !/^\/c\/chk_[A-Za-z0-9_-]{32}$/.test(url.pathname) ||
+    url.toString() !== value.url
+  ) {
+    throw new CliError("WarpMetal returned an invalid hosted checkout URL.");
+  }
+  const rfc3339 =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+  const expiresAt = Date.parse(value.expiresAt);
+  if (
+    !rfc3339.test(value.expiresAt) ||
+    !Number.isFinite(expiresAt) ||
+    expiresAt <= Date.now()
+  ) {
+    throw new CliError(
+      "WarpMetal returned an invalid or expired hosted checkout expiry.",
+    );
+  }
+  return {
+    url: value.url,
+    qrPayload: value.qrPayload,
+    expiresAt: value.expiresAt,
+    afterPayment: {
+      argv: [
+        "warpmetal",
+        "order",
+        "status",
+        "--task",
+        taskId,
+        "--wait",
+        ...(baseUrl ? ["--base-url", baseUrl] : []),
+        ...(stateDirectory ? ["--state-dir", stateDirectory] : []),
+        "--json",
+      ],
+      notificationNextAction: "ask_human_for_notification_email",
+    },
+  };
+}
+
 async function attachPaymentWorkflow(
   client,
   store,
@@ -517,7 +607,8 @@ async function attachPaymentWorkflow(
     paymentChallengeDigest: request.challengeDigest,
     paymentWorkflow: workflow,
   });
-  await store.savePaymentChallenge(taskId, safe);
+  const { humanCheckout: _ephemeralHostedCheckout, ...persisted } = safe;
+  await store.savePaymentChallenge(taskId, persisted);
   return safe;
 }
 
@@ -773,9 +864,20 @@ async function handleCheckoutChallenge(client, store, options, context) {
     store,
     taskId,
     order,
-    challengeResult(taskId, order.checkoutBody, response),
+    challengeResult(taskId, order.checkoutBody, response, {
+      // Initial checkout is the only interactive direct-payment surface.
+      // Autonomous renewal continues to use the bounded agent-wallet policy.
+      allowHumanCheckout: true,
+      humanCheckoutContext: {
+        baseUrl: client.baseUrl,
+        stateDirectory: store.directory,
+      },
+    }),
     stringOption(options, "request-envelope-out"),
   );
+  const directCheckoutInstructions = safe.humanCheckout
+    ? `\nDirect wallet checkout (optional, expires ${safe.humanCheckout.expiresAt}): ${safe.humanCheckout.url}\nEncode only that URL as the purchase QR. After payment, continue with: ${shellCommand(safe.humanCheckout.afterPayment.argv)}. When provisioning is ready, ask the owner for the optional lifecycle-notification email before adding it.`
+    : "";
   const paymentInstructions = safe.paymentWorkflow
     ? `\nWallet package: ${safe.paymentWorkflow.signerPackage.spec} (Node ${safe.paymentWorkflow.signerNodeRequirement})\nInstall: ${shellCommand(safe.paymentWorkflow.signerPackage.install.argv)}\nVerify: ${shellCommand(safe.paymentWorkflow.signerContract.probe.argv)}\n${walletWorkflowInstructions(safe.paymentWorkflow)}\nRequest envelope: ${safe.paymentWorkflow.requestEnvelopePath}\nAuthorize only after selecting/funding one wallet: ${shellCommand(safe.paymentWorkflow.authorize.argv)}\nSubmit with WarpMetal: ${shellCommand(safe.paymentWorkflow.submit.argv)}`
     : "";
@@ -784,7 +886,7 @@ async function handleCheckoutChallenge(client, store, options, context) {
     safe,
     context.json,
     response.status === 402
-      ? `Payment authorization required for ${taskId}.${paymentInstructions}`
+      ? `Payment authorization required for ${taskId}.${directCheckoutInstructions}${paymentInstructions}`
       : `Checkout status for ${taskId}: ${safe.status}`,
   );
   return response.status === 409 ? 6 : response.status === 402 ? 7 : 0;
@@ -2048,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.",
@@ -2075,6 +2185,7 @@ async function handleRuntimeInstall(client, store, options, context) {
     identity,
     sshUser,
     bootstrap: bootstrap.data,
+    nestedPrivateProcfs,
     fetchImpl: context.fetchImpl,
     spawnImpl: context.spawnImpl,
   });
@@ -2883,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;