appium-xcuitest-driver 11.2.3 → 11.3.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [11.3.0](https://github.com/appium/appium-xcuitest-driver/compare/v11.2.4...v11.3.0) (2026-05-09)
+
+### Features
+
+* add download-wda command ([#2835](https://github.com/appium/appium-xcuitest-driver/issues/2835)) ([1f568b4](https://github.com/appium/appium-xcuitest-driver/commit/1f568b4823a75ede182afdc7c82b73193f554765))
+
+## [11.2.4](https://github.com/appium/appium-xcuitest-driver/compare/v11.2.3...v11.2.4) (2026-05-08)
+
+### Bug Fixes
+
+* Tunnels cleanup ([#2834](https://github.com/appium/appium-xcuitest-driver/issues/2834)) ([e17218c](https://github.com/appium/appium-xcuitest-driver/commit/e17218c49111c500bef98aeee8d3739aafdfeb24))
+
 ## [11.2.3](https://github.com/appium/appium-xcuitest-driver/compare/v11.2.2...v11.2.3) (2026-05-07)
 
 ### Miscellaneous Chores

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "11.2.3",
+  "version": "11.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "11.2.3",
+      "version": "11.3.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/strongbox": "^1.0.0-rc.1",
@@ -35,7 +35,7 @@
         "ws": "^8.13.0"
       },
       "devDependencies": {
-        "@appium/docutils": "^2.0.0-rc.1",
+        "@appium/docutils": "^2.4.0",
         "@appium/eslint-config-appium-ts": "^3.0.0",
         "@appium/tsconfig": "^1.0.0-rc.1",
         "@appium/types": "^1.0.0-rc.1",
@@ -240,6 +240,18 @@
         "sharp": "0.34.5"
       }
     },
+    "node_modules/@appium/support/node_modules/semver": {
+      "version": "7.7.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
+      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/@appium/tsconfig": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/@appium/tsconfig/-/tsconfig-1.1.2.tgz",
@@ -551,9 +563,9 @@
       }
     },
     "node_modules/appium-ios-device": {
-      "version": "3.1.12",
-      "resolved": "https://registry.npmjs.org/appium-ios-device/-/appium-ios-device-3.1.12.tgz",
-      "integrity": "sha512-2EEeGzWz2uDmUJftxuZ4b5DCptGqvQuND+FDMQ6p4qOpxbQX6E5HmAs0LyeepB/xAxkUP9wXZdBRl1OnrLKqvg==",
+      "version": "3.1.13",
+      "resolved": "https://registry.npmjs.org/appium-ios-device/-/appium-ios-device-3.1.13.tgz",
+      "integrity": "sha512-W10U63ISs2z/OwrkvRkSpGJeLc3qeBfIBhKd33jLaaDZE3VNR3yD7vLVLBfXxVaaM6UFOqx3yL5BtoeYltsmYQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/support": "^7.2.2",
@@ -595,12 +607,12 @@
       }
     },
     "node_modules/appium-ios-simulator": {
-      "version": "8.1.2",
-      "resolved": "https://registry.npmjs.org/appium-ios-simulator/-/appium-ios-simulator-8.1.2.tgz",
-      "integrity": "sha512-rA5FXFMMPYYNqStHK9k4OBlpqiogXnHASp3QdLtDOEEzjQZMPV1QPHfeoa/W3jmlLGxICkHSdlP2NB5CbJBJmA==",
+      "version": "8.1.3",
+      "resolved": "https://registry.npmjs.org/appium-ios-simulator/-/appium-ios-simulator-8.1.3.tgz",
+      "integrity": "sha512-ED3dNbxTO7YC/8UNKECY2mvePELtTKp9AXj+qwccK0UOMPWLURPszB1vVmZA5UGIykyeOeHBVcKbkSk709R8Gg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@appium/support": "^7.0.0-rc.1",
+        "@appium/support": "^7.2.2",
         "@xmldom/xmldom": "^0.x",
         "appium-xcode": "^6.0.0",
         "async-lock": "^1.0.0",
@@ -655,9 +667,9 @@
       }
     },
     "node_modules/appium-webdriveragent": {
-      "version": "12.2.1",
-      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-12.2.1.tgz",
-      "integrity": "sha512-iSY3s4EUiNqY7SZg36ufI3Jt84dBDcFxIUxmusAUJzjxkHPYy+VNTOyIdtuP5RkhFNoSh4VHg8JjusGKqdKWwg==",
+      "version": "12.2.2",
+      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-12.2.2.tgz",
+      "integrity": "sha512-/GbzAjEHaaNgBUK8eVnmtf8s2fudjyCi55IBoEzv0sFg/188Bo+wsJfQhECjrk9CdhkpiwjsHAlJGLUy+iEpIQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/base-driver": "^10.3.0",
@@ -667,7 +679,7 @@
         "appium-ios-simulator": "^8.0.0",
         "async-lock": "^1.0.0",
         "asyncbox": "^6.1.0",
-        "axios": "^1.4.0",
+        "axios": "^1.16.0",
         "teen_process": "^4.0.7"
       },
       "engines": {
@@ -676,12 +688,12 @@
       }
     },
     "node_modules/appium-xcode": {
-      "version": "6.2.1",
-      "resolved": "https://registry.npmjs.org/appium-xcode/-/appium-xcode-6.2.1.tgz",
-      "integrity": "sha512-vY7D7GSm/m9KvRwJjk0AP9U+hT/MRoLN5OEohC2/vvbe5hxGp2H0nhUFYal2/6VwrL5U/P1zQKEIFUe3O8g0Dw==",
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/appium-xcode/-/appium-xcode-6.2.2.tgz",
+      "integrity": "sha512-THnFNNPW2M680OzSdyHHcvF46CusrvW+/t+zCvVA+MK/sO1AE22GIHoUScbl8HeRxVI9gf1SsXravNSh8OoNaA==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@appium/support": "^7.0.0-rc.1",
+        "@appium/support": "^7.2.2",
         "asyncbox": "^6.0.1",
         "semver": "^7.0.0",
         "teen_process": "^4.0.4"
@@ -1062,9 +1074,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.5",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
-      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
+      "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
@@ -1953,9 +1965,9 @@
       }
     },
     "node_modules/get-east-asian-width": {
-      "version": "1.5.0",
-      "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.5.0.tgz",
-      "integrity": "sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==",
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz",
+      "integrity": "sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==",
       "license": "MIT",
       "engines": {
         "node": ">=18"
@@ -2780,9 +2792,9 @@
       }
     },
     "node_modules/node-devicectl": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/node-devicectl/-/node-devicectl-1.3.0.tgz",
-      "integrity": "sha512-BrX8w5XkqeiZHW6wbfQBTnfu9HUAb/dPdNphtmiO4xrQJQBdxB44nyhtsTHMcdLzZLJJGJhyT+YWMNudFx9/dA==",
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/node-devicectl/-/node-devicectl-1.3.1.tgz",
+      "integrity": "sha512-hjjE/1RuvQ7BnjHqTfi4yhKGVVcTo/rEPdVzj1sIIQk29cvdsa1yXqfM4v4tQNiRcL2lMMqbO1hSkCBVAJ/w1g==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/logger": "^2.0.0-rc.1",
@@ -2806,9 +2818,9 @@
       }
     },
     "node_modules/node-simctl": {
-      "version": "8.2.2",
-      "resolved": "https://registry.npmjs.org/node-simctl/-/node-simctl-8.2.2.tgz",
-      "integrity": "sha512-VdEsKHI9r1dih0UvYejNG1sFqb/EYjfr4fp5LiV3ny7PEni3j7IzYIqQzJ1XilTdI7mk8vZG7kTOKqr24OCq9Q==",
+      "version": "8.2.3",
+      "resolved": "https://registry.npmjs.org/node-simctl/-/node-simctl-8.2.3.tgz",
+      "integrity": "sha512-udjYoXRsApFQP0fggKwGWFWUqinJKY11zIUmMxMv8Q4sfMLV0Uu9iavRUfiB3QOmJvL4WAXTaHv+tZvkiT+nyQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/logger": "^2.0.0-rc.1",
@@ -3450,9 +3462,9 @@
       "optional": true
     },
     "node_modules/semver": {
-      "version": "7.7.4",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
-      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "version": "7.8.0",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
+      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "11.2.3",
+  "version": "11.3.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -34,6 +34,7 @@
       "build-wda": "./scripts/build-wda.mjs",
       "open-wda": "./scripts/open-wda.mjs",
       "tunnel-creation": "./scripts/tunnel-creation.mjs",
+      "download-wda": "./scripts/download-wda.mjs",
       "download-wda-sim": "./scripts/download-wda-sim.mjs",
       "image-mounter": "./scripts/image-mounter.mjs",
       "list-real-devices": "./scripts/list-real-devices.mjs",
@@ -143,7 +144,7 @@
     "appium": "^3.0.0-rc.2"
   },
   "devDependencies": {
-    "@appium/docutils": "^2.0.0-rc.1",
+    "@appium/docutils": "^2.4.0",
     "@appium/eslint-config-appium-ts": "^3.0.0",
     "@appium/tsconfig": "^1.0.0-rc.1",
     "@appium/types": "^1.0.0-rc.1",

package/scripts/download-wda-sim.mjs

@@ -1,80 +1,25 @@
-import {fs, logger, zip, net, node} from 'appium/support.js';
-import _ from 'lodash';
-import os from 'node:os';
-import path from 'node:path';
+import {getWDAPrebuiltPackage} from './download-wda.mjs';
 import {Command} from 'commander';
+import { deprecate } from 'node:util';
 
-const log = logger.getLogger('download-wda-sim');
-const wdaUrl = (/** @type {string} */ version, /** @type {string} */ zipFileName) =>
-  `https://github.com/appium/WebDriverAgent/releases/download/v${version}/${zipFileName}`;
-const destZip = (/** @type {string} */ platform) => {
-  const scheme = `WebDriverAgentRunner${_.toLower(platform) === 'tvos' ? '_tvOS' : ''}`;
-  return `${scheme}-Build-Sim-${os.arch() === 'arm64' ? 'arm64' : 'x86_64'}.zip`;
-};
-
-/**
- * Return installed appium-webdriveragent package version
- * @returns {Promise<string>}
- */
-async function webdriveragentPkgVersion() {
-  const moduleRoot = node.getModuleRootSync('appium-xcuitest-driver', import.meta.url);
-  if (!moduleRoot) {
-    throw new Error('Cannot resolve module root for appium-xcuitest-driver');
-  }
-  const pkgPath = path.join(
-    moduleRoot,
-    'node_modules',
-    'appium-webdriveragent',
-    'package.json'
-  );
-  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
-  return String(pkg.version);
-};
-
-/**
- * Prepare the working root directory.
- * @param {string} outdir
- * @returns {Promise<string>} Root directory to download and unzip.
- */
-async function prepareRootDir(outdir) {
-  const destDir = path.resolve(process.cwd(), outdir);
-  if (await fs.exists(destDir)) {
-    throw new Error(`${destDir} already exists`);
-  }
-  await fs.mkdir(destDir, {recursive: true});
-  return destDir;
-}
-
-/**
- * @param {DownloadOptions} options
- */
-async function getWDAPrebuiltPackage(options) {
-  const destDir = await prepareRootDir(options.outdir);
-  const zipFileName = destZip(options.platform);
-  const wdaVersion = await webdriveragentPkgVersion();
-  const urlToDownload = wdaUrl(wdaVersion, zipFileName);
-  const downloadedZipFile = path.join(destDir, zipFileName);
-  try {
-    log.info(`Downloading ${urlToDownload}`);
-    await net.downloadFile(urlToDownload, downloadedZipFile);
-
-    log.info(`Unpacking ${downloadedZipFile} into ${destDir}`);
-    await zip.extractAllTo(downloadedZipFile, destDir);
-
-    log.info(`Deleting ${downloadedZipFile}`);
-  } finally {
-    if (await fs.exists(downloadedZipFile)) {
-      await fs.unlink(downloadedZipFile);
-    }
-  }
-}
+const DEPRECATION_MESSAGE =
+  "[DEPRECATED] 'download-wda-sim' is deprecated. " +
+  "Use 'appium driver run xcuitest download-wda -- --kind=sim --platform=<platform> --outdir=<outdir>' instead.";
 
 async function main() {
   const program = new Command();
 
+  const oldHandler = deprecate(
+    async (options) => {
+      await getWDAPrebuiltPackage({...options, kind: 'sim'});
+    },
+    DEPRECATION_MESSAGE
+  );
+
   program
     .name('appium driver run xcuitest download-wda-sim')
     .description('Download a prebuilt WebDriverAgentRunner for iOS/tvOS simulator')
+    .addHelpText('beforeAll', `${DEPRECATION_MESSAGE}\n\n`)
     .requiredOption('--outdir <path>', 'Destination directory to download and unpack into')
     .requiredOption(
       '--platform <platform>',
@@ -86,14 +31,12 @@ async function main() {
       `
 EXAMPLES:
   # Download WDA for iOS simulator
-  appium driver run xcuitest download-wda-sim --outdir ./wda-sim --platform iOS
+  appium driver run xcuitest download-wda-sim -- --outdir ./wda-sim --platform iOS
 
   # Download WDA for tvOS simulator
-  appium driver run xcuitest download-wda-sim --outdir ./wda-sim-tvos --platform tvOS`,
+  appium driver run xcuitest download-wda-sim -- --outdir ./wda-sim-tvos --platform tvOS`,
     )
-    .action(async (options) => {
-      await getWDAPrebuiltPackage(options);
-    });
+    .action(oldHandler);
 
   await program.parseAsync(process.argv);
 }

package/scripts/download-wda.mjs

@@ -0,0 +1,167 @@
+import {fs, logger, zip, net, node} from 'appium/support.js';
+import {constants as fsConstants, promises as fsPromises} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {Command} from 'commander';
+
+const log = logger.getLogger('download-wda');
+const WDA_KIND_REAL = 'real';
+const WDA_KIND_SIM = 'sim';
+
+const wdaUrl = (/** @type {string} */ version, /** @type {string} */ zipFileName) =>
+  `https://github.com/appium/WebDriverAgent/releases/download/v${version}/${zipFileName}`;
+
+/**
+ * Download and unpack a prebuilt WDA package for the given platform and kind.
+ * @param {DownloadOptions} options
+ * @returns {Promise<void>}
+ */
+export async function getWDAPrebuiltPackage(options) {
+  const kind = normalizeKind(options.kind);
+  const destDir = await prepareRootDir(options.outdir);
+  const zipFileName = destZip(options.platform, kind);
+  const wdaVersion = await getWebdriveragentPkgVersion();
+  const urlToDownload = wdaUrl(wdaVersion, zipFileName);
+  const downloadedZipFile = path.join(destDir, zipFileName);
+  try {
+    log.info(`Downloading ${urlToDownload}`);
+    await net.downloadFile(urlToDownload, downloadedZipFile);
+
+    log.info(`Unpacking ${downloadedZipFile} into ${destDir}`);
+    await zip.extractAllTo(downloadedZipFile, destDir);
+
+    log.info(`Deleting ${downloadedZipFile}`);
+  } finally {
+    if (await fs.exists(downloadedZipFile)) {
+      await fs.unlink(downloadedZipFile);
+    }
+  }
+}
+
+const destZip = (/** @type {string} */ platform, /** @type {WDAKind} */ kind) => {
+  const scheme = `WebDriverAgentRunner${String(platform).toLowerCase() === 'tvos' ? '_tvOS' : ''}`;
+  if (kind === WDA_KIND_SIM) {
+    return `${scheme}-Build-Sim-${os.arch() === 'arm64' ? 'arm64' : 'x86_64'}.zip`;
+  }
+  return `${scheme}-Runner.zip`;
+};
+
+/**
+ * Normalize the kind value, ensuring it is either 'real' or 'sim'. Default to 'real' if undefined.
+ * @param {string | undefined} kind
+ * @returns {WDAKind}
+ */
+function normalizeKind(kind) {
+  const normalized = String(kind || WDA_KIND_REAL).toLowerCase();
+  if (![WDA_KIND_REAL, WDA_KIND_SIM].includes(normalized)) {
+    throw new Error(`Unsupported kind '${kind}'. Supported values are '${WDA_KIND_REAL}' and '${WDA_KIND_SIM}'`);
+  }
+  return /** @type {WDAKind} */ (normalized);
+}
+
+/**
+ * Return installed appium-webdriveragent package version
+ * @returns {Promise<string>}
+ */
+async function getWebdriveragentPkgVersion() {
+  const moduleRoot = node.getModuleRootSync('appium-xcuitest-driver', import.meta.url);
+  if (!moduleRoot) {
+    throw new Error('Cannot resolve module root for appium-xcuitest-driver');
+  }
+  const pkgPath = path.join(
+    moduleRoot,
+    'node_modules',
+    'appium-webdriveragent',
+    'package.json'
+  );
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+  if (!pkg.version || typeof pkg.version !== 'string') {
+    throw new Error(`Cannot find version in ${pkgPath}`);
+  }
+  return pkg.version;
+};
+
+/**
+ * Prepare the working root directory.
+ * @param {string} outdir
+ * @returns {Promise<string>} Root directory to download and unzip.
+ */
+async function prepareRootDir(outdir) {
+  const destDir = path.resolve(process.cwd(), outdir);
+  if (await fs.exists(destDir)) {
+    throw new Error(`${destDir} already exists`);
+  }
+
+  const parentDir = path.dirname(destDir);
+  try {
+    await fsPromises.access(parentDir, fsConstants.W_OK);
+  } catch (err) {
+    throw new Error(`Parent directory '${parentDir}' is not writable`, {
+      cause: err,
+    });
+  }
+
+  try {
+    await fs.mkdir(destDir, {recursive: true});
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Cannot create directory '${destDir}': ${message}`, {
+      cause: err,
+    });
+  }
+  return destDir;
+}
+
+async function main() {
+  const program = new Command();
+
+  program
+    .name('appium driver run xcuitest download-wda')
+    .description('Download a prebuilt WebDriverAgentRunner for iOS/tvOS real devices or simulators')
+    .requiredOption('--outdir <path>', 'Destination directory to download and unpack into')
+    .requiredOption(
+      '--platform <platform>',
+      'Target platform (e.g. iOS or tvOS)',
+      (value) => value,
+    )
+    .option(
+      '--kind <kind>',
+      `Target package type: ${WDA_KIND_REAL} (real devices) or ${WDA_KIND_SIM} (simulators). Default: ${WDA_KIND_REAL}`,
+    )
+    .addHelpText(
+      'after',
+      `
+EXAMPLES:
+  # Download WDA for iOS real device (default)
+  appium driver run xcuitest download-wda -- --outdir ./wda-real --platform iOS
+
+  # Download WDA for tvOS simulator
+  appium driver run xcuitest download-wda -- --outdir ./wda-sim-tvos --platform tvOS --kind sim`,
+    )
+    .action(async (options) => {
+      await getWDAPrebuiltPackage({
+        ...options,
+        kind: options.kind ?? WDA_KIND_REAL,
+      });
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+const isMainModule =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+  await main();
+}
+
+/**
+ * @typedef {'real' | 'sim'} WDAKind
+ */
+
+/**
+ * @typedef {Object} DownloadOptions
+ * @property {string} outdir
+ * @property {string} platform
+ * @property {WDAKind | undefined} [kind]
+ */

package/scripts/tunnel-creation.mjs

@@ -41,6 +41,8 @@ class TunnelCreator {
     this._tunnelRegistryPort = 42314;
     /** @type {import('appium-ios-remotexpc').TunnelRegistry | null} */
     this._registry = null;
+    /** @type {import('appium-ios-remotexpc').TunnelRegistryServer | null} */
+    this._registryServer = null;
     /** @type {Map<string, import('appium-ios-remotexpc').UsbmuxDevice>} */
     this._usbDevices = new Map();
     /** @type {Map<string, Promise<void>>} */
@@ -75,6 +77,10 @@ class TunnelCreator {
     return this._registry;
   }
 
+  get registryServer() {
+    return this._registryServer;
+  }
+
   set packetStreamBasePort(port) {
     this._packetStreamBasePort = port;
   }
@@ -97,6 +103,13 @@ class TunnelCreator {
     this._registry = value;
   }
 
+  /**
+   * @param {import('appium-ios-remotexpc').TunnelRegistryServer | null} value
+   */
+  set registryServer(value) {
+    this._registryServer = value;
+  }
+
   /**
    * @param {number | null} maxAttempts - null disables retries; 0 means unlimited retries
    * @param {number} intervalMs
@@ -171,12 +184,29 @@ class TunnelCreator {
   async cleanup() {
     this._isCleaningUp = true;
     log.warn('Cleaning up tunnel resources...');
+    /** @type {Error[]} */
+    const cleanupErrors = [];
+    const recordCleanupError = (message, err) => {
+      const wrapped = err instanceof Error ? err : new Error(String(err));
+      cleanupErrors.push(new Error(message, {cause: wrapped}));
+      log.warn(`${message}: ${wrapped.message}`);
+    };
+
     while (this._registryWatcherStops.length > 0) {
       const stop = this._registryWatcherStops.pop();
       try {
         await stop?.();
       } catch (err) {
-        log.warn(`Failed to stop tunnel registry watcher: ${err}`);
+        recordCleanupError('Failed to stop tunnel registry watcher', err);
+      }
+    }
+    if (this._registryServer) {
+      try {
+        await this._registryServer.stop();
+      } catch (err) {
+        recordCleanupError('Failed to stop tunnel registry server', err);
+      } finally {
+        this._registryServer = null;
       }
     }
 
@@ -194,7 +224,7 @@ class TunnelCreator {
             await server.stop();
             log.info(`Closed packet stream server for device ${udid}`);
           } catch (err) {
-            log.warn(`Failed to close packet stream server for device ${udid}: ${err}`);
+            recordCleanupError(`Failed to close packet stream server for device ${udid}`, err);
           }
         }),
       );
@@ -216,9 +246,18 @@ class TunnelCreator {
     })();
 
     await Promise.allSettled([closeUsbPacketStreamServers, closeAppleTVTunnels]);
+    try {
+      await TunnelManager.closeAllTunnels();
+    } catch (err) {
+      recordCleanupError('Failed to close managed tunnel(s)', err);
+    }
     await Promise.allSettled([...this._reconnectTasks.values()]);
 
-    log.info('Cleanup completed.');
+    if (cleanupErrors.length > 0) {
+      throw new AggregateError(cleanupErrors, 'Tunnel cleanup encountered errors');
+    } else {
+      log.info('Cleanup completed.');
+    }
   }
 
   /**
@@ -914,6 +953,9 @@ function setupCleanupHandlers(tunnelCreator) {
       await tunnelCreator.cleanup();
     } catch (err) {
       log.warn(`Error during tunnel cleanup: ${err?.message ?? err}`);
+      if (!process.exitCode) {
+        process.exitCode = 1;
+      }
     }
   };
 
@@ -923,7 +965,8 @@ function setupCleanupHandlers(tunnelCreator) {
       if (process.exitCode == null) {
         // Follow conventional POSIX exit codes for signals where possible.
         if (signal === 'SIGINT') {
-          process.exitCode = 130;
+          // SIGINT is typically sent by Ctrl+C, so we exit with code 0 to indicate success.
+          process.exitCode = 0;
         } else if (signal === 'SIGTERM') {
           process.exitCode = 143;
         } else {
@@ -1093,7 +1136,10 @@ async function main() {
       return;
     }
 
-    await startTunnelRegistryServer(registry, tunnelCreator.tunnelRegistryPort);
+    tunnelCreator.registryServer = await startTunnelRegistryServer(
+      registry,
+      tunnelCreator.tunnelRegistryPort,
+    );
     tunnelCreator._attachTunnelRegistryLifecycleWatch(watchTunnelRegistrySockets, usbResults, {
       onTunnelDead: async ({udid}) => {
         tunnelCreator._reconnectTunnelByUdid(udid);