fix(uninstall): isolate scoped gateway shutdown

docs/manage-sandboxes/uninstall-nemoclaw.mdx

@@ -83,6 +83,17 @@ Rerun `NEMOCLAW_GATEWAY_PORT=<port> $$nemoclaw uninstall` with the gateway port
 For an externally supervised authority, uninstall preserves the local gateway state used by the running process in both full and gateway-scoped cleanup.
 It also preserves the gateway process, supervisor resources, marked Linux unit, Docker resources, OpenShell binaries, and the declared external state directory.
 A custom-port uninstall does not stop or remove the default gateway service or its environment file.
+Before scoped cleanup stops a Docker gateway process, including a managed default gateway service, NemoClaw requires two Docker namespace proofs.
+The selected Docker gateway configuration and any running gateway process must use the state-root-specific OpenShell sandbox namespace that NemoClaw generated.
+Because the supported OpenShell Podman schema does not expose `sandbox_namespace`, scoped Podman uninstall fails closed before signaling and preserves the gateway runtime evidence and local state.
+Full single-gateway Podman uninstall continues to use normal graceful teardown.
+For Docker, if either proof is absent, uninstall exits nonzero before it signals the host gateway.
+NemoClaw preserves the gateway runtime evidence and local state.
+Keep that state intact.
+Restore the selected Docker gateway through the supported install or onboarding recovery flow so it restarts with the generated configuration.
+Verify every gateway with `openshell gateway list`.
+Retry the scoped uninstall.
+Do not add `sandbox_namespace` manually to a live gateway configuration because the running process can still be using its previous namespace.
 
 <Note>
 In this section, `<selected-state-root>` is `~/.nemoclaw/` for the default gateway or `~/.nemoclaw/gateways/<port>/` for a non-default gateway.

docs/reference/commands.mdx

@@ -3892,6 +3892,17 @@ Rerun `NEMOCLAW_GATEWAY_PORT=<port> $$nemoclaw uninstall` with the gateway port
 For an externally supervised authority, uninstall preserves the selected local gateway state in both full and gateway-scoped cleanup.
 It also preserves the gateway process, supervisor resources, marked Linux unit, Docker resources, OpenShell binaries, and the declared external state directory.
 A custom-port uninstall does not stop or remove the default gateway service or its environment file.
+Before scoped cleanup stops a Docker gateway process, including a managed default gateway service, NemoClaw requires two Docker namespace proofs.
+The selected Docker gateway configuration and any running gateway process must use the state-root-specific OpenShell sandbox namespace that NemoClaw generated.
+Because the supported OpenShell Podman schema does not expose `sandbox_namespace`, scoped Podman uninstall fails closed before signaling and preserves the gateway runtime evidence and local state.
+Full single-gateway Podman uninstall continues to use normal graceful teardown.
+For Docker, if either proof is absent, uninstall exits nonzero before it signals the host gateway.
+NemoClaw preserves the gateway runtime evidence and local state.
+Keep that state intact.
+Restore the selected Docker gateway through the supported install or onboarding recovery flow so it restarts with the generated configuration.
+Verify every gateway with `openshell gateway list`.
+Retry the scoped uninstall.
+Do not add `sandbox_namespace` manually to a live gateway configuration because the running process can still be using its previous namespace.
 
 ##### Uninstalling Every Gateway Port
 

src/lib/actions/uninstall/run-plan-gateway-segregation.test.ts

@@ -23,6 +23,7 @@ function ok(stdout = ""): RunResult {
 
 function withManagedGatewayAuthority(deps: UninstallRunDeps): UninstallRunDeps {
   return {
+    isPortFree: () => true,
     resolveGatewayTeardownAuthority: ({ gatewayName, gatewayPort }) => ({
       gatewayName,
       gatewayPort,

src/lib/actions/uninstall/run-plan-gateway-service.test.ts

@@ -7,6 +7,7 @@ import path from "node:path";
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 
+import { gatewayIdForStateDir } from "../../onboard/docker-driver-gateway-config";
 import {
   getNemoclawOpenShellGatewayUserServicePath,
   getOpenShellUserConfigHome,
@@ -48,6 +49,7 @@ function fixture(useXdg = false): Fixture {
 }
 
 function writeManagedService(test: Fixture): string {
+  writeGatewayState(test);
   const servicePath = getNemoclawOpenShellGatewayUserServicePath(test.home, test.env);
   fs.mkdirSync(path.dirname(servicePath), { recursive: true });
   fs.writeFileSync(
@@ -84,16 +86,13 @@ function writeSelectedSandboxRegistry(test: Fixture, sandboxName: string): strin
 }
 
 function writeGatewayState(test: Fixture): string {
-  const configPath = path.join(
-    test.home,
-    ".local",
-    "state",
-    "nemoclaw",
-    "openshell-docker-gateway",
-    "openshell-gateway.toml",
-  );
+  const stateDir = path.join(test.home, ".local", "state", "nemoclaw", "openshell-docker-gateway");
+  const configPath = path.join(stateDir, "openshell-gateway.toml");
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, 'listen_address = "127.0.0.1:8080"\n');
+  fs.writeFileSync(
+    configPath,
+    `[openshell.drivers.docker]\nsandbox_namespace = "${gatewayIdForStateDir(stateDir)}"\n`,
+  );
   return configPath;
 }
 
@@ -109,6 +108,7 @@ function uninstall(
     {
       env: test.env,
       existsSync: (target) => String(target).startsWith(test.root) && fs.existsSync(target),
+      isPortFree: () => true,
       isTty: false,
       platform: "linux",
       resolveGatewayTeardownAuthority: ({ gatewayName, gatewayPort }) => ({
@@ -128,7 +128,9 @@ function uninstall(
       run: (command, args, options) =>
         command === "openshell" && args[0] === "gateway" && args[1] === "list"
           ? ok(JSON.stringify(gateways))
-          : run(command, args, options),
+          : command === "systemctl" && args.includes("--property=MainPID")
+            ? ok("0\n")
+            : run(command, args, options),
     },
   );
 }
@@ -245,6 +247,30 @@ describe("uninstall OpenShell gateway user service", () => {
     expect(fs.existsSync(servicePath)).toBe(false);
   });
 
+  it("does not signal a scoped service whose sandbox namespace is unproven (#8663)", () => {
+    const test = fixture(true);
+    const servicePath = writeManagedService(test);
+    fs.writeFileSync(writeGatewayState(test), "[openshell.drivers.docker]\n");
+    const calls: string[][] = [];
+
+    const result = uninstall(
+      test,
+      false,
+      {
+        commandExists: (command) => command === "systemctl",
+        run: (command, args) => {
+          calls.push([command, ...args]);
+          return ok();
+        },
+      },
+      [{ name: "nemoclaw" }, { name: "nemoclaw-8081" }],
+    );
+
+    expect(result.exitCode).toBe(1);
+    expect(fs.existsSync(servicePath)).toBe(true);
+    expect(calls.some(([command]) => command === "systemctl")).toBe(false);
+  });
+
   it("preserves the marked Linux unit when scoped sandbox deletion fails (#8220)", () => {
     const test = fixture(true);
     const servicePath = writeManagedService(test);

src/lib/actions/uninstall/run-plan.ts

@@ -58,6 +58,8 @@ import {
   resolveGatewayTeardownAuthority,
 } from "../../onboard/gateway-teardown-authority";
 import {
+  hasStateScopedSandboxNamespace,
+  processUsesStateScopedSandboxNamespace,
   type StopHostGatewayOptions,
   stopHostGatewayProcesses,
 } from "../../onboard/host-gateway-process";
@@ -98,12 +100,14 @@ export interface UninstallRunDeps {
   error?: (message: string) => void;
   existsSync?: (target: string) => boolean;
   fs?: FileSystemDeps;
+  isPortFree?: (port: number) => boolean;
   isTty?: boolean;
   kill?: (pid: number, signal?: NodeJS.Signals | number) => boolean;
   log?: (message: string) => void;
   openRegularFile?: typeof openRegularFileNoFollow;
   platform?: NodeJS.Platform;
   readProcessArgv?: (pid: number) => readonly string[] | null;
+  readProcessEnvironment?: (pid: number) => Record<string, string> | null;
   readLine?: () => string | null;
   requireCompleteGatewayProcessCleanup?: boolean;
   resolveGatewayTeardownAuthority?: GatewayTeardownAuthorityResolver;
@@ -406,12 +410,14 @@ interface UninstallRuntime {
   env: NodeJS.ProcessEnv;
   error: (message: string) => void;
   existsSync: (target: string) => boolean;
+  isPortFree: ((port: number) => boolean) | undefined;
   isTty: boolean;
   kill: (pid: number, signal?: NodeJS.Signals | number) => boolean;
   log: (message: string) => void;
   openRegularFile: typeof openRegularFileNoFollow;
   platform: NodeJS.Platform;
   readProcessArgv: ((pid: number) => readonly string[] | null) | undefined;
+  readProcessEnvironment: ((pid: number) => Record<string, string> | null) | undefined;
   readLine: () => string | null;
   requireCompleteGatewayProcessCleanup: boolean;
   resolveGatewayTeardownAuthority: GatewayTeardownAuthorityResolver;
@@ -432,6 +438,7 @@ function buildRuntime(deps: UninstallRunDeps): UninstallRuntime {
     env,
     error: deps.error ?? ((message) => console.error(message)),
     existsSync: deps.existsSync ?? ((target) => fs.existsSync(target)),
+    isPortFree: deps.isPortFree,
     // Side-effect-free TTY check + EAGAIN-tolerant reader; the
     // process.stdin/non-blocking-fd hazard is documented in core/stdin.ts.
     isTty: deps.isTty ?? isStdinTty(),
@@ -449,6 +456,7 @@ function buildRuntime(deps: UninstallRunDeps): UninstallRuntime {
     openRegularFile: deps.openRegularFile ?? openRegularFileNoFollow,
     platform: deps.platform ?? process.platform,
     readProcessArgv: deps.readProcessArgv,
+    readProcessEnvironment: deps.readProcessEnvironment,
     readLine: deps.readLine ?? readLineFromStdin,
     requireCompleteGatewayProcessCleanup: deps.requireCompleteGatewayProcessCleanup ?? false,
     resolveGatewayTeardownAuthority:
@@ -962,7 +970,10 @@ function stopOrphanedOpenShell(runtime: UninstallRuntime): void {
   }
 }
 
-function removeNemoclawOpenShellGatewayUserService(runtime: UninstallRuntime): boolean {
+function removeNemoclawOpenShellGatewayUserService(
+  runtime: UninstallRuntime,
+  scopedStateDir?: string,
+): boolean {
   if (runtime.platform !== "linux") return true;
   const servicePath = getNemoclawOpenShellGatewayUserServicePath(
     runtime.env.HOME || os.homedir(),
@@ -1000,6 +1011,33 @@ function removeNemoclawOpenShellGatewayUserService(runtime: UninstallRuntime): b
 
   const hasSystemctl = runtime.commandExists("systemctl");
   if (hasSystemctl) {
+    if (scopedStateDir !== undefined) {
+      const inspected = runtime.run(
+        "systemctl",
+        [
+          "--user",
+          "show",
+          NEMOCLAW_OPENSHELL_GATEWAY_USER_SERVICE,
+          "--property=MainPID",
+          "--value",
+        ],
+        { env: runtime.env },
+      );
+      const mainPid = Number(inspected.stdout.trim());
+      if (
+        !hasStateScopedSandboxNamespace(scopedStateDir) ||
+        inspected.status !== 0 ||
+        !inspected.stdout.trim() ||
+        !Number.isSafeInteger(mainPid) ||
+        mainPid < 0 ||
+        (mainPid > 0 && !processUsesStateScopedSandboxNamespace(mainPid, scopedStateDir, runtime))
+      ) {
+        runtime.warn(
+          "Refusing scoped gateway service stop because its loaded sandbox namespace cannot be proven.",
+        );
+        return false;
+      }
+    }
     const disabled = runtime.run(
       "systemctl",
       ["--user", "disable", "--now", NEMOCLAW_OPENSHELL_GATEWAY_USER_SERVICE],
@@ -1043,10 +1081,13 @@ function removeManagedDefaultGatewayUserService(
   runtime: UninstallRuntime,
   options: UninstallRunOptions,
   externallySupervised: boolean,
+  selectedStateDir?: string,
+  scoped = false,
 ): boolean {
-  return options.keepOpenShell || externallySupervised || GATEWAY_PORT !== DEFAULT_GATEWAY_PORT
-    ? true
-    : removeNemoclawOpenShellGatewayUserService(runtime);
+  if (options.keepOpenShell || externallySupervised || GATEWAY_PORT !== DEFAULT_GATEWAY_PORT) {
+    return true;
+  }
+  return removeNemoclawOpenShellGatewayUserService(runtime, scoped ? selectedStateDir : undefined);
 }
 
 function removeNemoclawOpenShellGatewayEnv(
@@ -2099,7 +2140,15 @@ function executePlan(
         return { ok: false };
       }
       if (scopedToSelectedGateway && !options.keepOpenShell && !externallySupervised) {
-        if (!removeManagedDefaultGatewayUserService(runtime, options, externallySupervised)) {
+        if (
+          !removeManagedDefaultGatewayUserService(
+            runtime,
+            options,
+            externallySupervised,
+            paths.selectedGatewayLocalStateDir,
+            true,
+          )
+        ) {
           return { ok: false };
         }
         stopHostGatewayProcessesForUninstall(runtime, {
@@ -2108,7 +2157,9 @@ function executePlan(
           openShellGatewayName: options.gatewayName || resolveGatewayName(GATEWAY_PORT),
           openShellGatewayPort: GATEWAY_PORT,
           preserveRuntimeFilesOnNonMatching: true,
+          scopedGatewayStop: true,
           stateDir: paths.selectedGatewayLocalStateDir,
+          usePgrepFallback: false,
         });
       } else if (scopedToSelectedGateway && externallySupervised) {
         runtime.log("Kept the externally supervised OpenShell gateway process running.");
@@ -2258,9 +2309,17 @@ function stopHostGatewayProcessesForUninstall(
       log: runtime.log,
       warn: runtime.warn,
       commandExists: runtime.commandExists,
+      isPortFree: runtime.isPortFree,
+      readProcessEnvironment: runtime.readProcessEnvironment,
     },
     options,
   );
+  if (options.scopedGatewayStop && (result.ownershipFailures?.length || result.failed.length)) {
+    runtime.error(
+      "Cannot prove ownership of or stop the selected host gateway process; retaining its runtime evidence.",
+    );
+    throw new IncompleteHostGatewayCleanupError();
+  }
   if (!runtime.requireCompleteGatewayProcessCleanup) return;
   if (result.failed.length === 0 && result.orphanScanComplete !== false) return;
   runtime.error("Cannot continue uninstall because host gateway process cleanup did not complete.");

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

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -16,6 +16,7 @@ export { ensureDockerDriverGatewayJwtBundle } from "./docker-driver-gateway-jwt-
 // See docs/security/openshell-0.0.72-compatibility-review.mdx for the source-of-truth review.
 export const DOCKER_DRIVER_GATEWAY_CONFIG_NAME = "openshell-gateway.toml";
 export const DOCKER_DRIVER_GATEWAY_JWT_TTL_SECS = 0;
+export const NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE_ENV = "NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE";
 
 function tomlString(value: string): string {
   return JSON.stringify(value);
@@ -55,9 +56,54 @@ function cleanupStaleAtomicFileTemps(dir: string, basename: string): void {
   }
 }
 
-function gatewayIdForStateDir(stateDir: string): string {
+export function gatewayIdForStateDir(stateDir: string): string {
   const leaf = path.basename(path.resolve(stateDir)).replace(/[^A-Za-z0-9_.-]/g, "-");
-  return leaf ? `nemoclaw-${leaf}` : "nemoclaw";
+  const scope = `${String(process.getuid?.() ?? "unknown")}\0${path.resolve(stateDir)}`;
+  const suffix = createHash("sha256").update(scope).digest("hex").slice(0, 12);
+  return `nemoclaw-${leaf || "gateway"}-${suffix}`;
+}
+
+/** Prove that a NemoClaw-owned Docker gateway config uses its state-scoped namespace. */
+export function hasStateScopedSandboxNamespace(stateDir: string): boolean {
+  if (typeof process.getuid !== "function" || typeof fs.constants.O_NOFOLLOW !== "number") {
+    return false;
+  }
+  const configPath = path.join(stateDir, DOCKER_DRIVER_GATEWAY_CONFIG_NAME);
+  let descriptor: number | undefined;
+  try {
+    const state = fs.lstatSync(stateDir);
+    descriptor = fs.openSync(configPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const config = fs.fstatSync(descriptor);
+    if (
+      !state.isDirectory() ||
+      state.isSymbolicLink() ||
+      !config.isFile() ||
+      config.nlink !== 1 ||
+      state.uid !== process.getuid() ||
+      config.uid !== state.uid ||
+      config.size > 64 * 1024
+    ) {
+      return false;
+    }
+    const expected = `sandbox_namespace = ${tomlString(gatewayIdForStateDir(stateDir))}`;
+    let inDriverTable = false;
+    const matches = fs
+      .readFileSync(descriptor, "utf-8")
+      .split(/\r?\n/)
+      .filter((line) => {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+          inDriverTable = trimmed === "[openshell.drivers.docker]";
+          return false;
+        }
+        return inDriverTable && trimmed.startsWith("sandbox_namespace =");
+      });
+    return matches.length === 1 && matches[0]?.trim() === expected;
+  } catch {
+    return false;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
 }
 
 function gatewayLocalTlsDir(gatewayEnv: Record<string, string>): string {
@@ -77,6 +123,7 @@ export function buildDockerDriverGatewayConfigToml(
   const driver = gatewayEnv.OPENSHELL_DRIVERS === "podman" ? "podman" : "docker";
   const localTlsDir = jwtBundle ? gatewayLocalTlsDir(gatewayEnv) : undefined;
   const dockerEntries: [string, string | undefined][] = [
+    ["sandbox_namespace", driver === "docker" ? gatewayId : undefined],
     ["grpc_endpoint", gatewayEnv.OPENSHELL_GRPC_ENDPOINT],
     ["host_gateway_ip", driver === "podman" ? PORTABLE_HOST_GATEWAY_IP : undefined],
     ["socket_path", driver === "podman" ? gatewayEnv.OPENSHELL_PODMAN_SOCKET : undefined],
@@ -169,5 +216,10 @@ export function prepareDockerDriverGatewayConfigEnv(
     gatewayEnv,
     sandboxBin,
   );
+  if (gatewayEnv.OPENSHELL_DRIVERS === "podman") {
+    delete gatewayEnv[NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE_ENV];
+  } else {
+    gatewayEnv[NEMOCLAW_OPENSHELL_SANDBOX_NAMESPACE_ENV] = gatewayIdForStateDir(stateDir);
+  }
   return gatewayEnv;
 }