feat(cli): add Hermes portable lifecycle authority

ci/onboard-entry-composition-budget.json

@@ -6,21 +6,17 @@
     "runOnboard": 2
   },
   "messaging": {
-    "createSandboxWithBaseImageResolution": 9,
-    "createSandboxWithBaseImageResolution.plan.rebindMessagingTokenDefs": 1,
     "getOpenShellInstallDeps.hasRequiredOpenshellMessagingFeatures": 4,
     "runOnboard": 1,
     "runOnboard.finalizationDeps.verifyDeployment.getMessagingChannels": 1
   },
   "policy": {
     "createOnboardPolicyApplication.getRecordedPolicyTier": 1,
-    "createSandboxWithBaseImageResolution": 7,
     "preflightAuthoritativeRebuildTarget": 1,
     "runOnboard": 6,
     "sandboxCreateIntentResolver.getAgentPolicyPath": 1
   },
   "provider": {
-    "createSandboxWithBaseImageResolution": 20,
     "handleNimLocalSelection": 36,
     "handleRemoteProviderSelection": 84,
     "handleRemoteProviderSelection.providerExistsInGateway": 1,

ci/source-architecture-budget.json

@@ -49,7 +49,7 @@
       "src/lib/inference/local.ts": 21,
       "src/lib/inference/onboard-probes.ts": 21,
       "src/lib/inference/vllm.ts": 21,
-      "src/lib/onboard.ts": 203,
+      "src/lib/onboard.ts": 201,
       "src/lib/onboard/machine/handlers/sandbox.ts": 21,
       "src/lib/sandbox/config.ts": 22,
       "src/lib/shields/index.ts": 23

install.sh

@@ -65,14 +65,18 @@ has_payload_marker() {
 clone_nemoclaw_ref() {
   local ref="$1" dest="$2"
 
-  git init --quiet "$dest"
-  git -C "$dest" remote add origin https://github.com/NVIDIA/NemoClaw.git
-  if ! git -C "$dest" fetch --quiet --depth 1 origin "+${ref}:refs/nemoclaw-install/target"; then
-    printf "[ERROR] Requested install ref '%s' is not available from https://github.com/NVIDIA/NemoClaw.git.\n" "$ref" >&2
-    printf "        Check NEMOCLAW_INSTALL_TAG/NEMOCLAW_INSTALL_REF and try again.\n" >&2
-    exit 1
-  fi
-  git -C "$dest" -c advice.detachedHead=false checkout --quiet --detach refs/nemoclaw-install/target
+  (
+    # Git applies the process umask when it creates the authoritative source checkout.
+    umask 022
+    git init --quiet "$dest"
+    git -C "$dest" remote add origin https://github.com/NVIDIA/NemoClaw.git
+    if ! git -C "$dest" fetch --quiet --depth 1 origin "+${ref}:refs/nemoclaw-install/target"; then
+      printf "[ERROR] Requested install ref '%s' is not available from https://github.com/NVIDIA/NemoClaw.git.\n" "$ref" >&2
+      printf "        Check NEMOCLAW_INSTALL_TAG/NEMOCLAW_INSTALL_REF and try again.\n" >&2
+      exit 1
+    fi
+    git -C "$dest" -c advice.detachedHead=false checkout --quiet --detach refs/nemoclaw-install/target
+  )
 }
 
 exec_installer_from_ref() {

scripts/dev-tier-selector.mts

@@ -61,7 +61,7 @@ runner.run = () => successfulRunResult;
 runner.runCapture = () => "";
 
 registry.getSandbox = () => ({ name: "test-sb", model: null, provider: null });
-registry.registerSandbox = () => true;
+registry.registerSandbox = (entry) => entry;
 registry.updateSandbox = () => true;
 
 // ── Run ────────────────────────────────────────────────────────────────────

scripts/install.sh

@@ -12,6 +12,10 @@ set -euo pipefail
 # are removed on any exit path (set -e, unhandled signal, unexpected error).
 _cleanup_pids=()
 _cleanup_files=()
+# Bind the portable installer's temporary Docker CLI selector so only that
+# exact value can be removed from the Hermes onboarding child.
+unset _PORTABLE_INSTALLER_DOCKER_HOST
+_PORTABLE_INSTALLER_DOCKER_HOST=""
 # #4414: When re-launched as a staged copy via `curl | bash`, queue the
 # staged tmpfile for removal on EXIT. NEMOCLAW_INSTALLER_STAGED carries
 # the staged path forward so both the loop guard and cleanup use one var.
@@ -173,12 +177,16 @@ resolve_stamped_version() {
 clone_nemoclaw_ref() {
   local ref="$1" dest="$2"
 
-  git init --quiet "$dest"
-  git -C "$dest" remote add origin https://github.com/NVIDIA/NemoClaw.git
-  if ! git -C "$dest" fetch --quiet --depth 1 origin "+${ref}:refs/nemoclaw-install/target"; then
-    error "Requested install ref '$ref' is not available from https://github.com/NVIDIA/NemoClaw.git. Check NEMOCLAW_INSTALL_TAG/NEMOCLAW_INSTALL_REF and try again."
-  fi
-  git -C "$dest" -c advice.detachedHead=false checkout --quiet --detach refs/nemoclaw-install/target
+  (
+    # Git applies the process umask when it creates the authoritative source checkout.
+    umask 022
+    git init --quiet "$dest"
+    git -C "$dest" remote add origin https://github.com/NVIDIA/NemoClaw.git
+    if ! git -C "$dest" fetch --quiet --depth 1 origin "+${ref}:refs/nemoclaw-install/target"; then
+      error "Requested install ref '$ref' is not available from https://github.com/NVIDIA/NemoClaw.git. Check NEMOCLAW_INSTALL_TAG/NEMOCLAW_INSTALL_REF and try again."
+    fi
+    git -C "$dest" -c advice.detachedHead=false checkout --quiet --detach refs/nemoclaw-install/target
+  )
 }
 
 # ---------------------------------------------------------------------------
@@ -3937,15 +3945,28 @@ run_onboard() {
     # forward --yes so the Ollama size-confirmation gate does not abort
     # the unattended download (the size is still printed to logs).
     onboard_cmd+=(--yes)
+  fi
+
+  local invoke_bin="$cli_invoke"
+  local -a invoke_args=("${onboard_cmd[@]}")
+  if [[ "${NEMOCLAW_EXPERIMENTAL_PROFILE:-}" == "portable" &&
+    "${NEMOCLAW_AGENT:-openclaw}" == "hermes" &&
+    -n "$_PORTABLE_INSTALLER_DOCKER_HOST" &&
+    "${DOCKER_HOST:-}" == "$_PORTABLE_INSTALLER_DOCKER_HOST" ]]; then
+    invoke_bin="/usr/bin/env"
+    invoke_args=(-u DOCKER_HOST "$cli_invoke" "${onboard_cmd[@]}")
+  fi
+
+  if [ "${NON_INTERACTIVE:-}" = "1" ]; then
     NEMOCLAW_INSTALLER_AUTO_FRESH_RECEIPT_GENERATION="$installer_auto_fresh_receipt_generation" \
-      "$cli_invoke" "${onboard_cmd[@]}" || status=$?
+      "$invoke_bin" "${invoke_args[@]}" || status=$?
   elif [ -t 0 ]; then
     NEMOCLAW_INSTALLER_AUTO_FRESH_RECEIPT_GENERATION="$installer_auto_fresh_receipt_generation" \
-      "$cli_invoke" "${onboard_cmd[@]}" || status=$?
+      "$invoke_bin" "${invoke_args[@]}" || status=$?
   elif { exec 3</dev/tty; } 2>/dev/null; then
     info "Installer stdin is piped; attaching onboarding to /dev/tty…"
     NEMOCLAW_INSTALLER_AUTO_FRESH_RECEIPT_GENERATION="$installer_auto_fresh_receipt_generation" \
-      "$cli_invoke" "${onboard_cmd[@]}" <&3 || status=$?
+      "$invoke_bin" "${invoke_args[@]}" <&3 || status=$?
     exec 3<&-
   else
     error "Interactive onboarding requires a TTY. Re-run in a terminal or set NEMOCLAW_NON_INTERACTIVE=1 with --yes-i-accept-third-party-software."
@@ -4164,6 +4185,7 @@ prepare_portable_experimental_runtime_override() {
     /*) export DOCKER_HOST="unix://${podman_socket}" ;;
     *) error "Podman reported an invalid rootless API socket path: ${podman_socket:-empty}" ;;
   esac
+  _PORTABLE_INSTALLER_DOCKER_HOST="$DOCKER_HOST"
 
   info "Portable profile selected rootless Podman through DOCKER_HOST=${DOCKER_HOST}."
 }

src/commands/credentials.test.ts

@@ -14,7 +14,9 @@ const mocks = vi.hoisted(() => ({
 
 vi.mock("../lib/credentials/store", () => ({
   KNOWN_CREDENTIAL_ENV_KEYS: ["NVIDIA_INFERENCE_API_KEY"],
+  getCredential: vi.fn(),
   prompt: mocks.prompt,
+  saveCredential: vi.fn(),
 }));
 vi.mock("../lib/actions/global", () => ({
   recoverNamedGatewayRuntime: mocks.recoverNamedGatewayRuntime,

src/commands/global-oclif-command-adapters.test.ts

@@ -16,6 +16,11 @@ const mocks = vi.hoisted(() => ({
   runInferenceSet: vi.fn(),
   runOnboardAction: vi.fn(),
   runUpgradeSandboxesAction: vi.fn(),
+  assertNoHermesPortableHostAuthority: vi.fn(),
+  withPortableHostFence: vi.fn(
+    async (homeOrOperation: string | (() => unknown), operation?: () => unknown) =>
+      (typeof homeOrOperation === "function" ? homeOrOperation : operation)?.(),
+  ),
   showStatusCommand: vi.fn(),
   onboardRuntimeDeps: { googlechatTunnelRuntime: {} },
 }));
@@ -42,6 +47,13 @@ vi.mock("../lib/actions/global", () => ({
   runUpgradeSandboxesAction: mocks.runUpgradeSandboxesAction,
 }));
 
+vi.mock("../lib/state/portable-uninstall-retirement", async (importOriginal) => ({
+  ...(await importOriginal()),
+  assertNoHermesPortableHostAuthority: mocks.assertNoHermesPortableHostAuthority,
+  withCurrentPortableHostFence: mocks.withPortableHostFence,
+  withPortableHostFence: mocks.withPortableHostFence,
+}));
+
 vi.mock("../lib/cli/onboard-runtime-deps", () => ({
   createOnboardActionRuntimeDeps: mocks.createOnboardActionRuntimeDeps,
 }));
@@ -88,6 +100,7 @@ const rootDir = process.cwd();
 describe("global oclif command adapters", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mocks.assertNoHermesPortableHostAuthority.mockReset();
     mocks.buildListCommandDeps.mockReturnValue({ getLiveInference: vi.fn() });
     mocks.buildStatusCommandDeps.mockReturnValue({ statusDeps: true });
     mocks.getSandboxInventory.mockResolvedValue({ sandboxes: [] });
@@ -111,6 +124,11 @@ describe("global oclif command adapters", () => {
   it("runs list through inventory helpers", async () => {
     await ListCommand.run([], rootDir);
 
+    expect(mocks.withPortableHostFence).toHaveBeenCalledOnce();
+    expect(mocks.assertNoHermesPortableHostAuthority).toHaveBeenCalledWith(
+      expect.any(String),
+      "list",
+    );
     expect(mocks.buildListCommandDeps).toHaveBeenCalledWith();
     expect(mocks.getSandboxInventory).toHaveBeenCalledWith({
       getLiveInference: expect.any(Function),
@@ -170,6 +188,8 @@ describe("global oclif command adapters", () => {
   it("runs status through status helpers", async () => {
     await StatusCommand.run([], rootDir);
 
+    expect(mocks.withPortableHostFence).toHaveBeenCalledOnce();
+    expect(mocks.assertNoHermesPortableHostAuthority).not.toHaveBeenCalled();
     expect(mocks.buildStatusCommandDeps).toHaveBeenCalledWith(rootDir);
     expect(mocks.showStatusCommand).toHaveBeenCalledWith({ statusDeps: true });
   });
@@ -214,6 +234,40 @@ describe("global oclif command adapters", () => {
     });
   });
 
+  it.each([
+    [
+      "list",
+      () => ListCommand.run([], rootDir),
+      [mocks.buildListCommandDeps, mocks.getSandboxInventory],
+    ],
+    ["inference:get", () => InferenceGetCommand.run([], rootDir), [mocks.runInferenceGet]],
+    [
+      "upgrade-sandboxes",
+      () => UpgradeSandboxesCommand.run(["--check"], rootDir),
+      [mocks.runUpgradeSandboxesAction],
+    ],
+  ] as const)(
+    "rejects %s under the host fence before any action (#9203)",
+    async (commandId, run, effects) => {
+      mocks.assertNoHermesPortableHostAuthority.mockImplementation(() => {
+        throw new Error(
+          `Command '${commandId}' is not supported while an experimental Hermes portable lifecycle receipt exists. No legacy Docker or OpenShell action was attempted.`,
+        );
+      });
+
+      await expect(run()).rejects.toThrow(
+        `Command '${commandId}' is not supported while an experimental Hermes portable lifecycle receipt exists`,
+      );
+
+      expect(mocks.withPortableHostFence).toHaveBeenCalledOnce();
+      expect(mocks.assertNoHermesPortableHostAuthority).toHaveBeenCalledWith(
+        expect.any(String),
+        commandId,
+      );
+      expect(effects.every((effect) => effect.mock.calls.length === 0)).toBe(true);
+    },
+  );
+
   it("maps onboard-family flags directly into the shared typed action", async () => {
     await OnboardCliCommand.run(["--name", "alpha", "--resume"], rootDir);
     await SetupCliCommand.run(["--name", "alpha", "--resume"], rootDir);
@@ -272,6 +326,11 @@ describe("global oclif command adapters", () => {
     const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
     try {
       await InferenceGetCommand.run(["--json"], rootDir);
+      expect(mocks.withPortableHostFence).toHaveBeenCalledOnce();
+      expect(mocks.assertNoHermesPortableHostAuthority).toHaveBeenCalledWith(
+        expect.any(String),
+        "inference:get",
+      );
       expect(mocks.runInferenceGet).toHaveBeenCalledWith({ quiet: true });
       expect(JSON.parse(String(log.mock.calls.at(-1)?.[0]))).toEqual({
         provider: "nvidia-prod",

src/commands/sandbox/config/rotate-token.ts

@@ -2,7 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { Args, Flags } from "@oclif/core";
-import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command";
+import {
+  assertHermesPortableCommandUnavailable,
+  NemoClawCommand,
+  withSandboxCommandLifecycleLock,
+} from "../../../lib/cli/nemoclaw-oclif-command";
 
 import * as sandboxConfig from "../../../lib/sandbox/config";
 
@@ -37,9 +41,12 @@ export default class SandboxConfigRotateTokenCommand extends NemoClawCommand {
   public async run(): Promise<void> {
     const { args, flags } = await this.parse(SandboxConfigRotateTokenCommand);
     try {
-      await sandboxConfig.configRotateToken(args.sandboxName, {
-        fromEnv: flags["from-env"] ?? null,
-        fromStdin: flags.stdin ?? false,
+      await withSandboxCommandLifecycleLock(args.sandboxName, () => {
+        assertHermesPortableCommandUnavailable(args.sandboxName, "sandbox:config:rotate-token");
+        return sandboxConfig.configRotateToken(args.sandboxName, {
+          fromEnv: flags["from-env"] ?? null,
+          fromStdin: flags.stdin ?? false,
+        });
       });
     } catch (error) {
       if (error instanceof sandboxConfig.SandboxConfigError) {

src/commands/sandbox/config/set.ts

@@ -2,7 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { Args, Flags } from "@oclif/core";
-import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command";
+import {
+  assertHermesPortableCommandUnavailable,
+  NemoClawCommand,
+  withSandboxCommandLifecycleLock,
+} from "../../../lib/cli/nemoclaw-oclif-command";
 
 import * as sandboxConfig from "../../../lib/sandbox/config";
 
@@ -42,11 +46,14 @@ export default class SandboxConfigSetCommand extends NemoClawCommand {
   public async run(): Promise<void> {
     const { args, flags } = await this.parse(SandboxConfigSetCommand);
     try {
-      await sandboxConfig.configSet(args.sandboxName, {
-        key: flags.key ?? null,
-        value: flags.value ?? null,
-        restart: flags.restart ?? false,
-        acceptNewPath: flags["config-accept-new-path"] ?? false,
+      await withSandboxCommandLifecycleLock(args.sandboxName, () => {
+        assertHermesPortableCommandUnavailable(args.sandboxName, "sandbox:config:set");
+        return sandboxConfig.configSet(args.sandboxName, {
+          key: flags.key ?? null,
+          value: flags.value ?? null,
+          restart: flags.restart ?? false,
+          acceptNewPath: flags["config-accept-new-path"] ?? false,
+        });
       });
     } catch (error) {
       if (error instanceof sandboxConfig.SandboxConfigError) {

src/commands/sandbox/exec.test.ts

@@ -9,6 +9,7 @@ vi.mock("../../lib/actions/sandbox/exec", () => ({
 }));
 
 import { log } from "../../lib/cli/logger";
+import * as portableAgentLifecycle from "../../lib/onboard/experimental/portable-agent-lifecycle";
 import SandboxExecCommand from "./exec";
 
 const rootDir = process.cwd();
@@ -34,6 +35,20 @@ describe("SandboxExecCommand oclif parse path", () => {
     );
   });
 
+  it("rejects schema-5 inside the user-facing exec lifecycle fence (#9203)", async () => {
+    vi.spyOn(portableAgentLifecycle, "assertHermesPortableCommandUnavailable").mockImplementation(
+      () => {
+        throw new Error("schema-5 rejected");
+      },
+    );
+
+    await expect(SandboxExecCommand.run(["alpha", "--", "true"], rootDir)).rejects.toThrow(
+      "schema-5 rejected",
+    );
+
+    expect(execSandboxMock).not.toHaveBeenCalled();
+  });
+
   it("does not assign host meaning to logging flags after --", async () => {
     const configure = vi.spyOn(log, "configure").mockImplementation(() => undefined);
 

src/commands/sandbox/exec.ts

@@ -3,7 +3,11 @@
 
 import { Args, Flags } from "@oclif/core";
 import { execSandbox } from "../../lib/actions/sandbox/exec";
-import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command";
+import {
+  assertHermesPortableCommandUnavailable,
+  NemoClawCommand,
+  withSandboxCommandLifecycleLock,
+} from "../../lib/cli/nemoclaw-oclif-command";
 
 export default class SandboxExecCommand extends NemoClawCommand {
   static id = "sandbox:exec";
@@ -51,11 +55,14 @@ export default class SandboxExecCommand extends NemoClawCommand {
     const cmd = (
       separatorIndex === -1 ? argv.slice(1) : originalArgv.slice(separatorIndex + 1)
     ) as string[];
-    await execSandbox(args.sandboxName, cmd, {
-      workdir: flags.workdir,
-      tty: typeof flags.tty === "boolean" ? flags.tty : null,
-      timeoutSeconds: flags.timeout,
-      stdin: flags.stdin,
+    await withSandboxCommandLifecycleLock(args.sandboxName, () => {
+      assertHermesPortableCommandUnavailable(args.sandboxName, "sandbox:exec");
+      return execSandbox(args.sandboxName, cmd, {
+        workdir: flags.workdir,
+        tty: typeof flags.tty === "boolean" ? flags.tty : null,
+        timeoutSeconds: flags.timeout,
+        stdin: flags.stdin,
+      });
     });
   }
 }