fix(destroy): release final gateway on macOS

docs/reference/commands.mdx

@@ -1498,10 +1498,10 @@ It restores and verifies lockdown and revokes the active timer before deletion.
 It clears the remaining local shields state only after deletion succeeds.
 If hardening fails, the command refuses deletion and leaves the timer authority available to retry lockdown.
 If deletion fails after hardening, the command keeps the surviving sandbox's locked shields state instead of cleaning it up as though deletion succeeded.
-By default, `destroy` preserves the shared NemoClaw gateway.
-Pass `--cleanup-gateway` to remove the shared gateway when destroying the last sandbox, or `--no-cleanup-gateway` to force preservation when environment defaults request cleanup.
+By default, unattended final-sandbox destroys (`--yes`, `--force`, or `NEMOCLAW_NON_INTERACTIVE=1`) remove the shared NemoClaw gateway on macOS so the host listener is released, while Linux preserves it for reuse.
+Pass `--cleanup-gateway` to force removal, or `--no-cleanup-gateway` to force preservation.
 If the pre-delete workspace wipe cannot run, use a different sandbox name for a clean start.
-When this is the last sandbox, pass `--cleanup-gateway` to purge the shared cluster volume that retains the per-name persistent volume.
+Cleaning up the gateway after the last sandbox also purges the shared cluster volume that retains the per-name persistent volume.
 If the OpenShell gateway is unreachable and the sandbox has no managed MCP ownership state, `--force` removes only NemoClaw's local registry entry and local artifacts.
 Gateway-side deletion remains unconfirmed, shared host-service and gateway teardown are skipped, and the sandbox and retained volume may still exist if the gateway returns.
 Start the gateway with `$$nemoclaw <name> status` and retry destroy when you need a confirmed deletion.
@@ -3462,7 +3462,7 @@ The following flags change defaults for commands that manage existing sandboxes.
 
 | Variable | Format | Effect |
 |----------|--------|--------|
-| `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `$$nemoclaw <name> destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. |
+| `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Overrides the platform default for whether `$$nemoclaw <name> destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. |
 | `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` | Exact JSON array of sandbox names | Confirms to the installer that the exact listed set of pre-fingerprint OpenClaw or Hermes sandboxes used NemoClaw-managed images, allowing recovery onto the current managed image. The normalized names must exactly match the installer's printed array. Set it only after verifying every named sandbox. Recorded custom-image evidence remains blocked. |
 | `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `$$nemoclaw <name> connect` and `$$nemoclaw <name> connect --probe-only`. Use only as a troubleshooting escape hatch. |
 | `NEMOCLAW_SHIELDS_ACCEPT_LEGACY_BASELINE` | `1` to opt in | Allows advanced immutable-config verification to trust the current on-disk bytes for older or partial content baselines. Use only after you have rebuilt or manually inspected the sandbox state and accepted that the baseline is operator-approved. |

src/commands/sandbox/destroy.ts

@@ -26,7 +26,7 @@ export default class DestroyCliCommand extends NemoClawCommand {
     force: forceFlag(),
     "cleanup-gateway": Flags.boolean({
       description:
-        "When destroying the last sandbox, also tear down the shared NemoClaw gateway. Default: preserve. NEMOCLAW_CLEANUP_GATEWAY=1 sets the same default.",
+        "When destroying the last sandbox, also tear down the shared NemoClaw gateway. Default: preserve on Linux; cleanup for unattended macOS destroys. NEMOCLAW_CLEANUP_GATEWAY overrides the platform default.",
       allowNo: true,
     }),
   };

src/lib/actions/sandbox/destroy-flow.test.ts

@@ -37,6 +37,7 @@ describe("destroySandbox flow", () => {
       ? delete process.env.OPENSHELL_GATEWAY
       : (process.env.OPENSHELL_GATEWAY = originalGatewayEnv);
     vi.restoreAllMocks();
+    vi.unstubAllEnvs();
     resetDestroyModuleCache();
   });
 
@@ -54,6 +55,127 @@ describe("destroySandbox flow", () => {
     expectSuccessfulLiveDestroy(harness, exitSpy);
   });
 
+  it("cleans the final gateway for unattended macOS destroys (#4662)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    const harness = createDestroyHarness();
+
+    await expect(harness.destroySandbox("alpha", { yes: true })).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).toHaveBeenCalledWith(
+      "nemoclaw-19080",
+      harness.runOpenshellSpy,
+    );
+  });
+
+  it("cleans the final gateway for forced macOS destroys (#4662)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    const harness = createDestroyHarness();
+
+    await expect(harness.destroySandbox("alpha", { force: true })).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).toHaveBeenCalledWith(
+      "nemoclaw-19080",
+      harness.runOpenshellSpy,
+    );
+  });
+
+  it("cleans the final gateway for environment-driven non-interactive macOS destroys (#4662)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    vi.stubEnv("NEMOCLAW_NON_INTERACTIVE", "1");
+    const harness = createDestroyHarness();
+
+    await expect(harness.destroySandbox("alpha", {})).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).toHaveBeenCalledWith(
+      "nemoclaw-19080",
+      harness.runOpenshellSpy,
+    );
+  });
+
+  it("preserves the final gateway for environment-driven non-interactive Linux destroys (#2166)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("linux");
+    vi.stubEnv("NEMOCLAW_NON_INTERACTIVE", "1");
+    const harness = createDestroyHarness();
+
+    await expect(harness.destroySandbox("alpha", {})).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).not.toHaveBeenCalled();
+  });
+
+  it("preserves the final gateway for native Windows unattended destroys (#4662)", async () => {
+    // Supported Windows execution uses WSL2, which reports `linux`. Keep an
+    // unexpected native `win32` host on the conservative non-macOS default.
+    vi.spyOn(process, "platform", "get").mockReturnValue("win32");
+    const harness = createDestroyHarness();
+
+    await expect(harness.destroySandbox("alpha", { yes: true })).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).not.toHaveBeenCalled();
+  });
+
+  it("honors the gateway cleanup environment override on macOS (#4662)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    vi.stubEnv("NEMOCLAW_CLEANUP_GATEWAY", "1");
+    const harness = createDestroyHarness();
+
+    await expect(harness.destroySandbox("alpha", { yes: true })).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).toHaveBeenCalledWith(
+      "nemoclaw-19080",
+      harness.runOpenshellSpy,
+    );
+  });
+
+  it("honors the gateway preservation environment override on macOS (#4662)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    vi.stubEnv("NEMOCLAW_CLEANUP_GATEWAY", "0");
+    const harness = createDestroyHarness();
+
+    await expect(harness.destroySandbox("alpha", { yes: true })).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).not.toHaveBeenCalled();
+  });
+
+  it("cleans the final gateway when an interactive macOS user accepts (#4662)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    const harness = createDestroyHarness({ promptResponses: ["yes", "yes"] });
+
+    await expect(harness.destroySandbox("alpha", {})).resolves.toBeUndefined();
+
+    expect(harness.promptSpy).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining("destroy the gateway"),
+    );
+    expect(harness.cleanupGatewaySpy).toHaveBeenCalledWith(
+      "nemoclaw-19080",
+      harness.runOpenshellSpy,
+    );
+  });
+
+  it("preserves the final gateway when an interactive user declines cleanup (#2166)", async () => {
+    vi.stubEnv("NEMOCLAW_NON_INTERACTIVE", "");
+    const harness = createDestroyHarness({ promptResponses: ["yes", ""] });
+
+    await expect(harness.destroySandbox("alpha", {})).resolves.toBeUndefined();
+
+    expect(harness.promptSpy).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining("destroy the gateway"),
+    );
+    expect(harness.cleanupGatewaySpy).not.toHaveBeenCalled();
+  });
+
+  it("honors an explicit gateway-preservation override on macOS (#4662)", async () => {
+    vi.spyOn(process, "platform", "get").mockReturnValue("darwin");
+    const harness = createDestroyHarness();
+
+    await expect(
+      harness.destroySandbox("alpha", { yes: true, cleanupGateway: false }),
+    ).resolves.toBeUndefined();
+
+    expect(harness.cleanupGatewaySpy).not.toHaveBeenCalled();
+  });
+
   it("stops before local cleanup when OpenShell fails to delete the live sandbox", async () => {
     const harness = createDestroyHarness({
       deleteStatus: 7,

src/lib/actions/sandbox/destroy.ts

@@ -89,20 +89,24 @@ function isNonInteractive(): boolean {
 
 /**
  * Decide whether to tear down the shared NemoClaw gateway after destroying
- * the last sandbox. Default is to preserve it (#2166); explicit opt-in via
- * `cleanupGateway: true` (which `normalizeDestroySandboxOptions` also reads
- * from `--cleanup-gateway` / `NEMOCLAW_CLEANUP_GATEWAY`).
+ * the last sandbox. Linux preserves it by default for reuse (#2166), while
+ * unattended macOS destroys clean it up so the host listener is released
+ * (#4662). Explicit cleanup options always take precedence.
  *
  * Prompt rules:
  *   - explicit `cleanupGateway` set         → honour it without prompting
- *   - non-interactive or `--yes` / `--force` → preserve gateway (safe default)
+ *   - non-interactive or `--yes` / `--force` → use the platform default
  *   - interactive without `--yes`           → prompt the user
  */
 async function resolveCleanupGatewayDecision(options: DestroySandboxOptions): Promise<boolean> {
   if (options.cleanupGateway === true) return true;
   if (options.cleanupGateway === false) return false;
-  if (options.yes === true || options.force === true) return false;
-  if (isNonInteractive()) return false;
+  if (options.yes === true || options.force === true || isNonInteractive()) {
+    // macOS must release the leaked gateway listener after final destroy (#4662).
+    // Supported Windows runs use WSL2 (`linux`); unexpected `win32` hosts keep
+    // the conservative non-macOS gateway-preservation default.
+    return process.platform === "darwin";
+  }
   console.log(`  ${YW}This was the last sandbox.${R}`);
   console.log(
     "  Also destroy the shared NemoClaw gateway (port forward, gateway pod, cluster volumes)?",

src/lib/domain/lifecycle/options.ts

@@ -18,8 +18,8 @@ export interface DestroySandboxOptions {
   /**
    * When the sandbox being destroyed is the last one, also tear down the
    * shared NemoClaw gateway (port forward, gateway pod, cluster volumes).
-   * Default `false` — gateway is preserved so the next `nemoclaw onboard`
-   * can reuse it without a full re-bootstrap. See #2166.
+   * Unattended macOS destroys default to cleanup so the host listener is
+   * released; Linux preserves the gateway for reuse. See #4662 and #2166.
    *
    * Resolution order during normalization: explicit option, then
    * `--cleanup-gateway` argv flag, then `NEMOCLAW_CLEANUP_GATEWAY=1` env