fix(onboard): continue onboarding when Homebrew refuses the pinned OpenShell tap

ci/platform-matrix.json

@@ -39,7 +39,7 @@
       "status": "caveated",
       "prd_priority": "P0",
       "ci_tested": true,
-      "notes": "Start the container runtime (Colima or Docker Desktop) before running the installer. When Homebrew is available, OpenShell uses its official formula and the gateway appears in `brew services list` as `openshell`; without Homebrew, NemoClaw uses the standalone OpenShell install and detached gateway fallback. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight."
+      "notes": "Start the container runtime (Colima or Docker Desktop) before running the installer. When Homebrew is available, OpenShell uses its official formula and the gateway appears in `brew services list` as `openshell`; without Homebrew, or when Homebrew refuses to load the official formula from its pinned tap, NemoClaw uses the standalone OpenShell install and detached gateway fallback. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight."
     },
     {
       "name": "DGX OS (Spark)",

docs/get-started/prerequisites.mdx

@@ -96,7 +96,7 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC
 | DGX OS (Spark) | Docker | Tested | Use the standard installer and `$$nemoclaw onboard`. For an end-to-end walkthrough with local inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). |
 | DGX OS (Station) | Docker | Tested with limitations | Tested with limitations across qualified profiles on one physical DGX Station GB300; see [Additional Setup for DGX Station](additional-setup/dgx-station-preparation) for accepted profiles, the pending no-OTA DGX OS `7.6.x` end-to-end qualification, runtime gates, and current dual-Station and dedicated CI limitations. |
 | Linux | Docker | Tested | Primary tested path. Ubuntu 24.04 has host-level onboarding validation. A digest-pinned Ubuntu 26.04 userspace lane builds the CLI and runs preflight, installer, and platform contracts on eligible main pushes; Docker-host, AppArmor, Landlock, and live onboarding validation on 26.04 remain pending. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. |
-| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Start the container runtime (Colima or Docker Desktop) before running the installer. When Homebrew is available, OpenShell uses its official formula and the gateway appears in `brew services list` as `openshell`; without Homebrew, NemoClaw uses the standalone OpenShell install and detached gateway fallback. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
+| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | Start the container runtime (Colima or Docker Desktop) before running the installer. When Homebrew is available, OpenShell uses its official formula and the gateway appears in `brew services list` as `openshell`; without Homebrew, or when Homebrew refuses to load the official formula from its pinned tap, NemoClaw uses the standalone OpenShell install and detached gateway fallback. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
 | Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | Requires WSL2 with Docker Desktop backend. See [Additional Setup for Windows Machines](additional-setup/windows-preparation) before the Quickstart. |
 
 For the complete platform support matrix, including all deferred platforms and CI coverage, refer to [Platform Support](../reference/platform-support).

docs/reference/architecture.mdx

@@ -90,7 +90,9 @@ The standalone Linux process is used only when the systemd user manager is unava
 On Apple Silicon macOS, Homebrew makes the official OpenShell formula authoritative.
 The installer stages the formula and onboarding starts its `openshell` service.
 When Homebrew is present, a missing formula, a formula from another tap, a service-start failure, or a health failure stops onboarding.
-Only a host without Homebrew uses the standalone macOS gateway fallback.
+Homebrew 6.x refuses to load formulae from taps it has not marked trusted, so it can fail to confirm the official formula's identity.
+When that happens, onboarding warns and uses the standalone macOS gateway fallback.
+A host without Homebrew also uses the standalone macOS gateway fallback.
 NemoClaw-managed gateways on custom ports remain detached and separate from the default service.
 An externally supervised gateway can use any matching configured port; its declared supervisor retains lifecycle authority.
 In both Docker-driver modes, the sandbox is a Docker container, not a Kubernetes pod.

docs/reference/platform-support.mdx

@@ -81,7 +81,7 @@ For install requirements and the shorter setup-oriented platform view, refer to
 | DGX OS (Spark) | Docker | Tested | P1 | Yes | Use the standard installer and `$$nemoclaw onboard`. For an end-to-end walkthrough with local inference, see the [NVIDIA Spark playbook](https://build.nvidia.com/spark/nemoclaw). |
 | DGX OS (Station) | Docker | Tested with limitations | P1 | No | The PRD marks this platform as P1. Physical validation on one DGX Station GB300 covers generic Ubuntu 24.04 ARM64, stock DGX OS `7.5.0`, the April 2026 NVIDIA Colossus BaseOS profile, and the June 2026 NVIDIA AI Developer Tools profile. A physical no-OTA DGX OS `7.6.0` host provided the release and hardware profile used for its stable workstation-family classifier and passed read-only eligibility and runtime-command preflight. Full Station Express end-to-end qualification for the accepted no-OTA DGX OS `7.6.x` profile is pending. The profile remains subject to the same physical GB300, driver, ECC, Docker, CDI, and container GPU validation. Clean-host end-to-end validation passed on generic Ubuntu and Colossus BaseOS; stock DGX OS and AI Developer Tools completed Station Express validation. The DGX OS `7.5.0` run used released OpenShell `0.0.85`, local Nemotron Ultra serving, sandbox `cuInit(0)`, and a Hermes write/read file-tool task. A dual-Station configuration has not been validated, and dedicated CI coverage is not available. Direct-GPU policies expose only the exact read-only BDF directory for each discovered display-class PCI device with NVIDIA vendor ID (`0x10de`) and GB300 device ID (`0x31c2` or `0x31c3`) plus required existing topology and module paths; they do not expose `/sys`, the PCI parent subtree, or sysfs write access. During physical validation, reads of `/sys/fs/cgroup/cgroup.controllers` and `/sys/class/net/lo/address` remained denied. For canonical hardware qualification, image requirements, preparation, repair limits, reboot handoff, and the explicit temporary metadata override, see [Prepare DGX Station to Install NemoClaw](../get-started/additional-setup/dgx-station-preparation). |
 | Linux | Docker | Tested | P0 | Yes | Primary tested path. Ubuntu 24.04 has host-level onboarding validation. A digest-pinned Ubuntu 26.04 userspace lane builds the CLI and runs preflight, installer, and platform contracts on eligible main pushes; Docker-host, AppArmor, Landlock, and live onboarding validation on 26.04 remain pending. Other distros (Ubuntu 22.04, Fedora, Rocky, Alma, NixOS, Arch) may work but are not validated. |
-| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | P0 | Yes | Start the container runtime (Colima or Docker Desktop) before running the installer. When Homebrew is available, OpenShell uses its official formula and the gateway appears in `brew services list` as `openshell`; without Homebrew, NemoClaw uses the standalone OpenShell install and detached gateway fallback. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
+| macOS (Apple Silicon) | Colima, Docker Desktop | Tested with limitations | P0 | Yes | Start the container runtime (Colima or Docker Desktop) before running the installer. When Homebrew is available, OpenShell uses its official formula and the gateway appears in `brew services list` as `openshell`; without Homebrew, or when Homebrew refuses to load the official formula from its pinned tap, NemoClaw uses the standalone OpenShell install and detached gateway fallback. Homebrew Colima users must install both Colima and the Docker CLI (`brew install colima docker`) before `docker info` can work. Xcode Command Line Tools (`xcode-select --install`) are typically required for Node native modules during install. NemoClaw recommends them but does not enforce them during preflight. |
 | NVIDIA RTX (consumer and Pro workstation GPUs) | Docker | Deferred | P1 | No | The PRD marks this platform as P1. Covers RTX consumer cards and RTX Pro workstation cards on Linux hosts that meet the generic-Linux-GPU requirements (NVIDIA Container Toolkit + CDI present). The provider menu emits managed vLLM behind `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm` for this host class today; the end-to-end onboard path on this hardware is not yet validated in CI. |
 | Windows WSL2 | Docker Desktop (WSL backend) | Tested with limitations | P1 | No | Requires WSL2 with Docker Desktop backend. |
 {/* platform-matrix-full:end */}

docs/reference/troubleshooting.mdx

@@ -911,7 +911,7 @@ Follow these steps to reconnect.
    ```
 
    If Homebrew is present but `openshell` is missing or comes from another tap, rerun the NemoClaw installer.
-   Onboarding does not use the standalone fallback while Homebrew is present.
+   If Homebrew refuses to load the formula and cannot confirm its identity, onboarding warns with Homebrew's reason and continues on the standalone fallback.
 
    On Linux package installs, inspect and restart the upstream service.
 

src/lib/onboard/docker-driver-gateway-service.test.ts

@@ -146,6 +146,77 @@ describe("docker-driver-gateway-service", () => {
     ).toThrow("must come from nvidia/openshell");
   });
 
+  it("continues without the Homebrew service when brew refuses to load the formula (#7707)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const refusal =
+      "Error: Refusing to load formula nvidia/openshell/openshell from untrusted tap nvidia/openshell.";
+    const options = {
+      commandExists: () => true,
+      platform: "darwin" as NodeJS.Platform,
+      spawnSyncImpl: vi.fn((_command: string, args: string[]) =>
+        args[0] === "info" ? spawnResult(1, refusal) : spawnResult(),
+      ),
+    };
+
+    expect(hasOpenShellGatewayUserService(options)).toBe(false);
+    expect(hasOpenShellGatewayUserService(options)).toBe(false);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(refusal));
+  });
+
+  it.each([
+    ["a generic brew info failure", "Error: Permission denied"],
+    [
+      "a refused foreign-tap formula",
+      "Error: Refusing to load formula other/tap/openshell from untrusted tap other/tap.",
+    ],
+  ])("keeps %s fatal during the formula identity check (#7707)", (_case, reason) => {
+    expect(() =>
+      hasOpenShellGatewayUserService({
+        commandExists: () => true,
+        platform: "darwin",
+        spawnSyncImpl: vi.fn((_command: string, args: string[]) =>
+          args[0] === "info" ? spawnResult(1, reason) : spawnResult(),
+        ),
+      }),
+    ).toThrow(`OpenShell Homebrew formula identity check failed: ${reason}`);
+  });
+
+  it("still reports a missing formula when brew list is blocked by the untrusted-tap refusal (#7707)", () => {
+    const refusal =
+      "Error: Refusing to load formula nvidia/openshell/openshell from untrusted tap nvidia/openshell.";
+    expect(() =>
+      hasOpenShellGatewayUserService({
+        commandExists: () => true,
+        platform: "darwin",
+        spawnSyncImpl: () => spawnResult(1, refusal),
+      }),
+    ).toThrow("official OpenShell Homebrew formula is not installed");
+  });
+
+  it("skips the Homebrew-managed start when the formula identity is unconfirmed (#7707)", async () => {
+    const refusal =
+      "Error: Refusing to load formula nvidia/openshell/openshell from untrusted tap nvidia/openshell.";
+    const started = await startPackageManagedDockerDriverGateway({
+      clearDockerDriverGatewayRuntimeFiles: () => {},
+      exitOnFailure: false,
+      gatewayName: "nemoclaw",
+      hasOpenShellGatewayUserService: () =>
+        hasOpenShellGatewayUserService({
+          commandExists: () => true,
+          platform: "darwin",
+          spawnSyncImpl: (_command: string, args: string[]) =>
+            args[0] === "info" ? spawnResult(1, refusal) : spawnResult(),
+        }),
+      registerDockerDriverGatewayEndpoint: () => true,
+      runCaptureOpenshell: () => "",
+      skipSandboxBridgeReachability: true,
+      verifySandboxBridgeGatewayReachableOrExit: async () => {},
+    });
+
+    expect(started).toBe(false);
+  });
+
   it("rejects a missing Homebrew formula when Homebrew is available (#6903)", () => {
     expect(() =>
       hasOpenShellGatewayUserService({

src/lib/onboard/docker-driver-gateway-service.ts

@@ -239,6 +239,31 @@ function hasUpstreamOpenShellGatewayUserService(
   return getOpenShellGatewayUserServicePaths().some(existsSync);
 }
 
+const warnedHomebrewIdentityCheckReasons = new Set<string>();
+
+// Homebrew 6.x refuses to load formulae from taps it has not marked trusted.
+// For the pinned official formula that refusal names the right tap, so it is
+// not evidence of a wrong formula, and managing the service through brew would
+// fail the same way. Continue on the standalone gateway fallback instead of
+// aborting; any other brew failure keeps the fail-closed abort (#7707).
+// The match is against Homebrew's literal refusal text: if Homebrew rewords
+// it, this case reverts to the fail-closed abort, not to a bypass.
+function isPinnedTapLoadRefusal(reason: string): boolean {
+  return reason
+    .replace(/\s+/g, " ")
+    .includes(
+      `Refusing to load formula ${OPENSHELL_GATEWAY_HOMEBREW_TAP}/${OPENSHELL_GATEWAY_HOMEBREW_SERVICE} from untrusted tap ${OPENSHELL_GATEWAY_HOMEBREW_TAP}`,
+    );
+}
+
+function warnHomebrewIdentityCheckUnavailable(reason: string): void {
+  if (warnedHomebrewIdentityCheckReasons.has(reason)) return;
+  warnedHomebrewIdentityCheckReasons.add(reason);
+  console.warn(
+    `  Homebrew could not confirm the OpenShell formula identity; falling back to the standalone gateway.\n  ${reason}`,
+  );
+}
+
 function hasOfficialHomebrewFormula(
   opts: Pick<
     OpenShellGatewayUserServiceOptions,
@@ -259,7 +284,14 @@ function hasOfficialHomebrewFormula(
     env,
     spawnSyncImpl,
   });
-  if (!info.ok) throw new Error(`OpenShell Homebrew formula identity check failed: ${info.reason}`);
+  if (!info.ok) {
+    const reason = info.reason ?? "brew info failed";
+    if (isPinnedTapLoadRefusal(reason)) {
+      warnHomebrewIdentityCheckUnavailable(reason);
+      return false;
+    }
+    throw new Error(`OpenShell Homebrew formula identity check failed: ${reason}`);
+  }
   try {
     const parsed = JSON.parse(info.stdout ?? "") as {
       formulae?: Array<{ name?: string; tap?: string }>;

src/lib/onboard/gateway-host-runtime-homebrew-untrusted-tap.test.ts

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createGatewayHostRuntime, type GatewayHostRuntimeDeps } from "./gateway-host-runtime";
+import type { PortProbeResult } from "./preflight";
+
+// Homebrew 6.x refuses to load formulae from taps it has not marked trusted,
+// so `brew info --json=v2 openshell` fails even though the formula is the
+// pinned official one. The refusal reaches the gateway-owner resolution
+// through the real spawnSync path, not an injected seam (#7707).
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...actual,
+    spawnSync: vi.fn((command: string, args: readonly string[]) =>
+      command === "brew" && args[0] === "info"
+        ? {
+            status: 1,
+            stderr:
+              "Error: Refusing to load formula nvidia/openshell/openshell from untrusted tap nvidia/openshell.",
+            stdout: "",
+          }
+        : { status: 0, stderr: "", stdout: "" },
+    ),
+  };
+});
+
+const ORIGINAL_ENV = { ...process.env };
+
+beforeEach(() => {
+  vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  process.env = { ...ORIGINAL_ENV };
+  vi.restoreAllMocks();
+});
+
+function createDeps(): GatewayHostRuntimeDeps {
+  return {
+    applyOverlayfsAutoFix: () => null,
+    checkGatewayPortAvailable: async () => ({ ok: true }) as PortProbeResult,
+    gatewayName: () => "nemoclaw",
+    gatewayPort: () => 8080,
+    getGatewayPortListenerRawScan: () => ({ pids: [], complete: true }),
+    getInstalledOpenshellVersion: () => "0.0.85",
+    runCaptureOpenshell: () => "healthy",
+    runOpenshell: () => ({ status: 0 }),
+    resolveOpenShellGatewayBinary: () => null,
+    waitForGatewayHttpReady: async () => true,
+  };
+}
+
+describe("gateway host runtime on Homebrew 6.x untrusted tap", () => {
+  it("resolves a standalone owner instead of aborting when brew refuses the pinned tap (#7707)", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const runtime = createGatewayHostRuntime(createDeps());
+
+    expect(runtime.getGatewayOwner()).toMatchObject({
+      gatewayName: "nemoclaw",
+      gatewayPort: 8080,
+      mode: "nemoclaw-managed",
+      source: "standalone",
+    });
+    expect(runtime.getGatewayOwner()).toMatchObject({ source: "standalone" });
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+});