fix(tunnel): release NemoClaw gateway port on stop (#5968)

.github/workflows/macos-e2e.yaml

@@ -70,6 +70,12 @@ jobs:
           npm ci --ignore-scripts
           npm run build
 
+      - name: Run gateway lifecycle regressions
+        run: >-
+          npx vitest run --project integration
+          test/tunnel-gateway-port-release-runtime.test.ts
+          test/onboard-gateway-prelaunch-cutover.test.ts
+
       - name: Detect Docker availability
         id: docker
         run: |

ci/platform-matrix.json

@@ -93,7 +93,7 @@
       "name": "Other OpenAI-compatible endpoint",
       "status": "caveated",
       "endpoint_type": "Custom OpenAI-compatible",
-      "notes": "Adapter path validated against OpenRouter as the `compatible-endpoint` provider with `openrouter/auto` (see `src/lib/inference/config.test.ts:119`); the onboarding prompt that surfaces OpenRouter as the worked example is at `src/lib/onboard.ts:3585`. Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints."
+      "notes": "Adapter path validated against OpenRouter as the `compatible-endpoint` provider with `openrouter/auto` (see `src/lib/inference/config.test.ts:119`); the onboarding prompt that surfaces OpenRouter as the worked example is in `handleRemoteProviderSelection` in `src/lib/onboard.ts`. Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints."
     },
     {
       "name": "Anthropic",
@@ -218,12 +218,12 @@
     {
       "name": "Podman / other container runtimes",
       "status": "unsupported",
-      "notes": "Onboard surfaces an explicit unsupported-runtime error for Podman (`src/lib/onboard/fatal-runtime-preflight.ts:50` prints the rejection; `src/lib/onboard/preflight.ts:676` flags the unsupported runtime upstream). Only Docker Engine, Docker Desktop, and Colima are supported. See issue #420 (closed)."
+      "notes": "Onboard surfaces an explicit unsupported-runtime error for Podman (`src/lib/onboard/fatal-runtime-preflight.ts:50` prints the rejection; `src/lib/onboard/preflight.ts:677` flags the unsupported runtime upstream). Only Docker Engine, Docker Desktop, and Colima are supported. See issue #420 (closed)."
     },
     {
       "name": "Intel Mac (macOS x86_64)",
       "status": "unsupported",
-      "notes": "OpenShell does not publish macOS x86_64 standalone gateway assets. Install hard-fails on x86_64 macOS (`scripts/install-openshell.sh:654`). See issue #954 (closed)."
+      "notes": "OpenShell does not publish macOS x86_64 standalone gateway assets. Install hard-fails on x86_64 macOS (`scripts/install-openshell.sh:663`). See issue #954 (closed)."
     },
     {
       "name": "Non-Ubuntu/Debian Linux distros",

docs/inference/inference-options.mdx

@@ -43,7 +43,7 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l
 |----------|--------|---------------|-------|
 | NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com |
 | OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs |
-| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated against OpenRouter as the `compatible-endpoint` provider with `openrouter/auto` (see `src/lib/inference/config.test.ts:119`); the onboarding prompt that surfaces OpenRouter as the worked example is at `src/lib/onboard.ts:3585`. Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. |
+| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated against OpenRouter as the `compatible-endpoint` provider with `openrouter/auto` (see `src/lib/inference/config.test.ts:119`); the onboarding prompt that surfaces OpenRouter as the worked example is in `handleRemoteProviderSelection` in `src/lib/onboard.ts`. Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. |
 | Anthropic | Tested | Native Anthropic | Uses anthropic-messages |
 | Other Anthropic-compatible endpoint | Tested with limitations | Custom Anthropic-compatible | Adapter path validated with AWS Bedrock (`src/lib/onboard/bedrock-runtime.ts`). Behavior on other Anthropic-compatible proxies and gateways may vary; this row claims the adapter, not the universe of compatible endpoints. |
 | Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint |

docs/reference/commands-nemohermes.mdx

@@ -1710,7 +1710,9 @@ Use `nemohermes <name> channels stop <channel>` when you only want to pause one
 nemohermes tunnel stop
 ```
 
-`nemohermes stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`.
+`nemohermes stop` remains as a deprecated legacy full stop.
+It stops the tunnel services and also releases the managed host gateway port.
+Use `nemohermes tunnel stop` when the shared gateway should remain available.
 
 ### `nemohermes tunnel status`
 
@@ -1733,10 +1735,12 @@ This command remains as a compatibility alias to `nemohermes tunnel start`.
 ### `nemohermes stop`
 
 <Warning>
-Deprecated. Use `nemohermes tunnel stop` instead.
+Deprecated legacy full stop.
+Use `nemohermes tunnel stop` when the shared gateway should remain available.
 </Warning>
 
-This command remains as a compatibility alias to `nemohermes tunnel stop`.
+This command stops tunnel services and also releases the managed host gateway port.
+It is retained for compatibility with full-stop automation; unlike `nemohermes tunnel stop`, it intentionally tears down that host gateway.
 
 ### `nemohermes status`
 

docs/reference/commands.mdx

@@ -2121,7 +2121,9 @@ Use `$$nemoclaw <name> channels stop <channel>` when you only want to pause one
 $$nemoclaw tunnel stop
 ```
 
-`$$nemoclaw stop` remains as a deprecated alias that prints a warning and delegates to `tunnel stop`.
+`$$nemoclaw stop` remains as a deprecated legacy full stop.
+It stops the tunnel services and also releases the managed host gateway port.
+Use `$$nemoclaw tunnel stop` when the shared gateway should remain available.
 
 ### `$$nemoclaw tunnel status`
 
@@ -2144,10 +2146,12 @@ This command remains as a compatibility alias to `$$nemoclaw tunnel start`.
 ### `$$nemoclaw stop`
 
 <Warning>
-Deprecated. Use `$$nemoclaw tunnel stop` instead.
+Deprecated legacy full stop.
+Use `$$nemoclaw tunnel stop` when the shared gateway should remain available.
 </Warning>
 
-This command remains as a compatibility alias to `$$nemoclaw tunnel stop`.
+This command stops tunnel services and also releases the managed host gateway port.
+It is retained for compatibility with full-stop automation; unlike `$$nemoclaw tunnel stop`, it intentionally tears down that host gateway.
 
 ### `$$nemoclaw status`
 

docs/reference/platform-support.mdx

@@ -95,7 +95,7 @@ NemoClaw routes inference through the OpenShell gateway. Each row below is a pro
 |----------|--------|---------------|-------|
 | NVIDIA Endpoints | Tested | OpenAI-compatible | Hosted models on integrate.api.nvidia.com |
 | OpenAI | Tested | Native OpenAI-compatible | Uses OpenAI model IDs |
-| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated against OpenRouter as the `compatible-endpoint` provider with `openrouter/auto` (see `src/lib/inference/config.test.ts:119`); the onboarding prompt that surfaces OpenRouter as the worked example is at `src/lib/onboard.ts:3585`. Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. |
+| Other OpenAI-compatible endpoint | Tested with limitations | Custom OpenAI-compatible | Adapter path validated against OpenRouter as the `compatible-endpoint` provider with `openrouter/auto` (see `src/lib/inference/config.test.ts:119`); the onboarding prompt that surfaces OpenRouter as the worked example is in `handleRemoteProviderSelection` in `src/lib/onboard.ts`. Behavior on other OpenAI-compatible proxies, gateways, and self-hosted implementations may vary; this row claims the adapter, not the universe of compatible endpoints. |
 | Anthropic | Tested | Native Anthropic | Uses anthropic-messages |
 | Other Anthropic-compatible endpoint | Tested with limitations | Custom Anthropic-compatible | Adapter path validated with AWS Bedrock (`src/lib/onboard/bedrock-runtime.ts`). Behavior on other Anthropic-compatible proxies and gateways may vary; this row claims the adapter, not the universe of compatible endpoints. |
 | Google Gemini | Tested | OpenAI-compatible | Uses Google's OpenAI-compatible endpoint |
@@ -160,8 +160,8 @@ They are listed here so launch material, sales conversations, and support triage
 {/* out-of-scope:begin */}
 | Item | Status | Why |
 |------|--------|-----|
-| Podman / other container runtimes | Unsupported | Onboard surfaces an explicit unsupported-runtime error for Podman (`src/lib/onboard/fatal-runtime-preflight.ts:50` prints the rejection; `src/lib/onboard/preflight.ts:676` flags the unsupported runtime upstream). Only Docker Engine, Docker Desktop, and Colima are supported. See issue #420 (closed). |
-| Intel Mac (macOS x86_64) | Unsupported | OpenShell does not publish macOS x86_64 standalone gateway assets. Install hard-fails on x86_64 macOS (`scripts/install-openshell.sh:654`). See issue #954 (closed). |
+| Podman / other container runtimes | Unsupported | Onboard surfaces an explicit unsupported-runtime error for Podman (`src/lib/onboard/fatal-runtime-preflight.ts:50` prints the rejection; `src/lib/onboard/preflight.ts:677` flags the unsupported runtime upstream). Only Docker Engine, Docker Desktop, and Colima are supported. See issue #420 (closed). |
+| Intel Mac (macOS x86_64) | Unsupported | OpenShell does not publish macOS x86_64 standalone gateway assets. Install hard-fails on x86_64 macOS (`scripts/install-openshell.sh:663`). See issue #954 (closed). |
 | Non-Ubuntu/Debian Linux distros | Unsupported | Installer assumes `apt-get`. Fedora/Rocky/Alma/Arch/NixOS are not validated and the installer's package-manager probes do not cover them. See open issue #899 (Fedora hang). |
 | Native Kubernetes or OpenShift deployments | Unsupported | NemoClaw runs the sandbox as a Docker container, not a Kubernetes pod. The default Docker-driver topology does not embed k3s. Operator-managed K8s/OpenShift deployments are out of scope; see issue #407 (community OpenShift through agent-sandbox CRD). |
 | Air-gapped / offline installs | Unsupported | Onboard assumes network reachability for package fetches, container pulls, and provider validation. See open issues #4872 and #2218 (production-deployment epic covering air-gapped support, China network guidance, multi-host topology). |

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

@@ -283,6 +283,12 @@ describe("simple global oclif adapters", () => {
     expect(mocks.runStopCommand).toHaveBeenCalledWith(
       expect.objectContaining({ listSandboxes: expect.any(Function), stopAll: mocks.stopAll }),
     );
+    expect(mocks.runStopCommand.mock.calls).toEqual(
+      expect.arrayContaining([
+        [expect.not.objectContaining({ releaseGatewayPort: true })],
+        [expect.objectContaining({ releaseGatewayPort: true })],
+      ]),
+    );
   });
 
   it("passes uninstall runtime dependencies to the uninstall action", async () => {

src/commands/stop.ts

@@ -2,26 +2,27 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { NemoClawCommand } from "../lib/cli/nemoclaw-oclif-command";
-
-import { stopAll } from "../lib/tunnel/services";
-import { runStopCommand } from "../lib/tunnel/service-command";
 import { serviceDeps } from "../lib/tunnel/command-support";
+import { runStopCommand } from "../lib/tunnel/service-command";
+import { stopAll } from "../lib/tunnel/services";
 
 export default class DeprecatedStopCommand extends NemoClawCommand {
   static id = "stop";
   static strict = true;
-  static summary = "Deprecated alias for 'tunnel stop'";
-  static description = "Deprecated alias for tunnel stop.";
+  static summary = "Deprecated full stop (also releases the managed gateway port)";
+  static description =
+    "Stop tunnel services and release the managed host gateway port. Use 'tunnel stop' to preserve the shared gateway.";
   static usage = ["stop"];
   static examples = ["<%= config.bin %> stop"];
   static state = "deprecated" as const;
   static deprecationOptions = {
-    message: "Deprecated: 'nemoclaw stop' is now 'nemoclaw tunnel stop'. See 'nemoclaw help'.",
+    message:
+      "Deprecated: use 'nemoclaw tunnel stop' for tunnel-only shutdown. This legacy command also releases the managed host gateway port.",
   };
   static flags = {};
 
   public async run(): Promise<void> {
     await this.parse(DeprecatedStopCommand);
-    runStopCommand({ ...serviceDeps(), stopAll });
+    runStopCommand({ ...serviceDeps(), stopAll, releaseGatewayPort: true });
   }
 }