@xenon-device-management/xenon 2.0.0 → 2.2.0

package/lib/src/device-managers/ios/IOSDiscoveryService.js

@@ -76,6 +76,7 @@ const config_1 = require("../../config");
 const device_service_1 = require("../../data-service/device-service");
 const iOSTracker_1 = require("../iOSTracker");
 const networkAddresses_1 = require("../../helpers/networkAddresses");
+const localDeviceHosts_1 = require("../localDeviceHosts");
 /**
  * Should this simulator be given wda/mjpeg ports the moment we notice it?
  *
@@ -152,9 +153,13 @@ let IOSDiscoveryService = class IOSDiscoveryService {
                 console.log('[POISON PILL] REAL fetchLocalIOSDevices CALLED IN TEST MODE!');
             }
             const devices = yield this.getConnectedDevices();
+            // This server's own row for a phone: the exact host getDeviceInfo files
+            // it under. A node on this machine sees the same iPhone and shares the
+            // IP, so its row for the udid must not be taken for ours.
+            const ownHost = (0, localDeviceHosts_1.iosRealDeviceHost)(this.pluginArgs, this.hostPort);
             const deviceProcessingPromises = devices.map((udid) => __awaiter(this, void 0, void 0, function* () {
                 try {
-                    const existingDevice = existingDeviceDetails.find((device) => device.udid === udid);
+                    const existingDevice = existingDeviceDetails.find((device) => device.udid === udid && device.host === ownHost);
                     if (existingDevice) {
                         const networkIp = yield this.fetchRealDeviceNetworkIp(udid);
                         return Object.assign(Object.assign({}, existingDevice), { ip: networkIp || (0, networkAddresses_1.sanitizeDeviceNetworkIp)(existingDevice.ip) || '' });
@@ -176,10 +181,10 @@ let IOSDiscoveryService = class IOSDiscoveryService {
     getDeviceInfo(udid) {
         return __awaiter(this, void 0, void 0, function* () {
             const store = device_store_1.DeviceStoreFactory.getStore();
-            const storeDevice = yield store.findDevice({ udid });
-            const host = this.pluginArgs.remoteMachineProxyIP
-                ? String(this.pluginArgs.remoteMachineProxyIP)
-                : `http://${this.pluginArgs.bindHostOrIp}:${this.hostPort}`;
+            const host = (0, localDeviceHosts_1.iosRealDeviceHost)(this.pluginArgs, this.hostPort);
+            // Our own row only (udid AND host): it is spread over the result below,
+            // and another server's row would hand us its host, ports and busy state.
+            const storeDevice = yield store.findDevice({ udid, host });
             // A real device is going to want these, so ask now — but not at the cost
             // of the whole discovery pass. See tryAcquire: an exhausted range used to
             // throw out of here and take the device list with it.
@@ -257,9 +262,11 @@ let IOSDiscoveryService = class IOSDiscoveryService {
             }
             const store = device_store_1.DeviceStoreFactory.getStore();
             const nodeLanIp = this.resolveNodeLanIp();
+            // A node on this Mac lists the same simulators; only our own row's ports.
+            const simHost = (0, localDeviceHosts_1.iosSimulatorHost)(this.pluginArgs, this.hostPort);
             return yield Promise.all(simulators.map((d) => __awaiter(this, void 0, void 0, function* () {
                 var _a;
-                const storeDevice = yield store.findDevice({ udid: d.udid });
+                const storeDevice = yield store.findDevice({ udid: d.udid, host: simHost });
                 const willRunWda = simulatorNeedsPortNow(d.state);
                 return Object.assign(Object.assign(Object.assign({}, d), (0, appleIdentity_1.simulatorIdentity)(d.name)), { wdaLocalPort: (storeDevice === null || storeDevice === void 0 ? void 0 : storeDevice.wdaLocalPort) ||
                         (willRunWda
@@ -267,7 +274,7 @@ let IOSDiscoveryService = class IOSDiscoveryService {
                             : undefined), mjpegServerPort: (storeDevice === null || storeDevice === void 0 ? void 0 : storeDevice.mjpegServerPort) ||
                         (willRunWda
                             ? yield typedi_1.Container.get(PortAllocator_1.PortAllocator).tryAcquire('mjpeg', d.udid)
-                            : undefined), busy: false, realDevice: false, platform: (((_a = d.name) === null || _a === void 0 ? void 0 : _a.toLowerCase().includes('tv')) ? 'tvos' : 'ios'), deviceType: 'simulator', host: `http://${this.pluginArgs.bindHostOrIp}:${this.hostPort}`, ip: nodeLanIp, totalUtilizationTimeMilliSec: yield (0, device_utils_1.getUtilizationTime)(d.udid), sessionStartTime: 0 });
+                            : undefined), busy: false, realDevice: false, platform: (((_a = d.name) === null || _a === void 0 ? void 0 : _a.toLowerCase().includes('tv')) ? 'tvos' : 'ios'), deviceType: 'simulator', host: simHost, ip: nodeLanIp, totalUtilizationTimeMilliSec: yield (0, device_utils_1.getUtilizationTime)(d.udid), sessionStartTime: 0 });
             })));
         });
     }
@@ -323,7 +330,11 @@ let IOSDiscoveryService = class IOSDiscoveryService {
             }
         }));
         tracker.on('detached', (udid) => __awaiter(this, void 0, void 0, function* () {
-            const deviceRemoved = [{ udid, host: this.pluginArgs.bindHostOrIp }];
+            // The host 'attached' filed it under (getDeviceInfo), exact: a bare IP
+            // is matched as a substring and takes other servers' rows with it.
+            const deviceRemoved = [
+                { udid, host: (0, localDeviceHosts_1.iosRealDeviceHost)(this.pluginArgs, this.hostPort), nodeId: this.nodeId },
+            ];
             if (this.pluginArgs.hub) {
                 yield new NodeDevices_1.default(this.pluginArgs.hub, {
                     tlsRejectUnauthorized: this.pluginArgs.tlsRejectUnauthorized,

package/lib/src/device-managers/ios/IOSStreamService.js

@@ -60,8 +60,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IOS_IDLE_STOP_MS = void 0;
+exports.StreamRestartRefused = exports.IOS_IDLE_STOP_MS = void 0;
 exports.shouldStopIdleIosStream = shouldStopIdleIosStream;
+exports.heldByAppiumSession = heldByAppiumSession;
 const typedi_1 = require("typedi");
 const ProcessRegistry_1 = require("../../services/ProcessRegistry");
 const child_process_1 = require("child_process");
@@ -77,6 +78,7 @@ const helpers_1 = require("../../helpers");
 const singleFlight_1 = require("../../helpers/singleFlight");
 const PortAllocator_1 = require("../../services/PortAllocator");
 const device_store_1 = require("../../data-service/device-store");
+const ownDeviceRow_1 = require("../ownDeviceRow");
 const iosStreamDiagnostics_1 = require("./iosStreamDiagnostics");
 const tunnelProcess_1 = require("./tunnelProcess");
 const device_service_1 = require("../../data-service/device-service");
@@ -98,6 +100,25 @@ function shouldStopIdleIosStream(use) {
         return false;
     return !use.sessionId || (0, manualLock_1.isManualLock)(use.sessionId);
 }
+/**
+ * Whether a live Appium session holds the phone: busy under a session id that
+ * isn't a live-preview hold. A claim still waiting for its session id isn't
+ * one yet.
+ */
+function heldByAppiumSession(device) {
+    return !!(device === null || device === void 0 ? void 0 : device.busy) && !!device.session_id && !(0, manualLock_1.isManualLock)(device.session_id);
+}
+/**
+ * The ports go-ios's tunnel process listens on: its tunnel-info API
+ * (`GO_IOS_AGENT_PORT`, default 60105) and the first phone's userspace tunnel
+ * (API port + 1). On iOS 17+ every go-ios command that talks to the phone,
+ * `runwda` included, goes through that process.
+ */
+const GO_IOS_AGENT_PORTS = [60105, 60106];
+/** A start refused a restart because an Appium session holds the phone. */
+class StreamRestartRefused extends Error {
+}
+exports.StreamRestartRefused = StreamRestartRefused;
 let IOSStreamService = class IOSStreamService {
     constructor() {
         this.sessions = new Map();
@@ -117,7 +138,9 @@ let IOSStreamService = class IOSStreamService {
     startWatchdog() {
         // Every minute, and cheap: an unwatched preview's hold was held for good,
         // because the only idle check ran hourly and kept every busy device.
-        setInterval(() => void this.sweepIdle(), 60000);
+        // unref()ed: the server's listener keeps the process alive; these only
+        // need to fire while it runs.
+        setInterval(() => void this.sweepIdle(), 60000).unref();
         // Hourly: port leases and the stream health check, which probes WDA.
         setInterval(() => __awaiter(this, void 0, void 0, function* () {
             for (const [udid, session] of this.sessions.entries()) {
@@ -146,7 +169,7 @@ let IOSStreamService = class IOSStreamService {
                         logger_1.default.warn(`Stream watchdog detected failure for ${udid}. Attempting autonomous healing...`);
                         try {
                             // Get device state to check for Session Shield
-                            const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                            const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                             if (device && device.busy) {
                                 logger_1.default.info(`🛡️ [Watchdog] Skipping heal for ${udid} as it has an active session.`);
                                 continue;
@@ -166,7 +189,7 @@ let IOSStreamService = class IOSStreamService {
                     }
                 }
             }
-        }), 3600000); // 1hr interval for background stability
+        }), 3600000).unref(); // 1hr interval for background stability
     }
     /**
      * Stop streams nobody has watched for 10 minutes, which releases an
@@ -184,7 +207,7 @@ let IOSStreamService = class IOSStreamService {
                 if (session.viewerCount > 0 || idleMs <= exports.IOS_IDLE_STOP_MS)
                     continue;
                 try {
-                    const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                    const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                     const recording = yield typedi_2.Container.get(recording_store_1.RecordingStore).isRecording(udid);
                     const stop = shouldStopIdleIosStream({
                         idleMs,
@@ -329,20 +352,28 @@ let IOSStreamService = class IOSStreamService {
         });
     }
     /**
-     * Kill any orphan tunnel processes that might be left from previous runs
-     * This is critical for preventing 'address already in use' errors
+     * Kill go-ios tunnel processes left over from earlier runs, so a new tunnel
+     * can bind the agent's ports ('address already in use' otherwise).
+     *
+     * Never while an Appium session holds the phone. That session may be
+     * driving a WDA go-ios launched (iOSCapabilities points a session at the
+     * stream's WDA whenever a stream runs), and on iOS 17+ that WDA reaches the
+     * phone through the tunnel listening on these ports. Nothing here can tell
+     * that tunnel from an orphan, so the sweep waits for the next stop or start
+     * after the session ends; a restart reaps every go-ios process at boot.
      */
     cleanupOrphanTunnels(udid) {
         return __awaiter(this, void 0, void 0, function* () {
+            if (yield this.appiumSessionMayUse(udid, 'go-ios tunnels'))
+                return;
             logger_1.default.debug(`Cleaning up orphan tunnels for ${udid}...`);
             // Reap the tunnel process *group* for this udid so the self-forking go-ios
             // agent children (whose argv carries no udid, so a udid-scoped pkill can't
             // see them) die with their parent instead of orphaning. Group-scoped, so a
             // second device's tunnel is left untouched. See ./tunnelProcess.
             yield (0, tunnelProcess_1.reapTunnelsForUdid)(udid, execPromise);
-            // Check common go-ios agent ports (60105, 60106) and kill if bound
-            const agentPorts = [60105, 60106];
-            for (const port of agentPorts) {
+            // Whatever still listens on the go-ios agent's ports.
+            for (const port of GO_IOS_AGENT_PORTS) {
                 try {
                     const { stdout } = yield execPromise(`lsof -ti :${port}`);
                     const pids = stdout.trim().split('\n');
@@ -361,14 +392,65 @@ let IOSStreamService = class IOSStreamService {
             yield new Promise((resolve) => setTimeout(resolve, 500));
         });
     }
+    /**
+     * Whether an Appium session may be using what the caller is about to kill:
+     * one holds the phone, or the phone's row can't be read, in which case
+     * nothing is known and nothing is killed.
+     */
+    appiumSessionMayUse(udid, what) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
+                if (!heldByAppiumSession(device))
+                    return false;
+                logger_1.default.info(`[${udid}] Leaving ${what} alone: Appium session ${device === null || device === void 0 ? void 0 : device.session_id} holds the device and may be using them`);
+            }
+            catch (e) {
+                logger_1.default.warn(`[${udid}] Leaving ${what} alone: could not read the device: ${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e}`);
+            }
+            return true;
+        });
+    }
+    /**
+     * Throw StreamRestartRefused when an Appium session holds the phone, as the
+     * watchdog's heal already skips a busy device. A restart would kill the WDA
+     * and go-ios tunnel the session may be driving, or, on a stream attached to
+     * the session's own WDA, launch a second WDA over it. A WDA that is only
+     * slow to answer /status (a long command) would be killed for nothing. The
+     * stream is left as it is; it can restart once the session ends. A row that
+     * can't be read refuses too.
+     */
+    refuseRestartUnderAppiumSession(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            let device;
+            try {
+                device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
+            }
+            catch (e) {
+                throw new StreamRestartRefused(`Stream for ${udid} is not answering, and the device can't be read to check for an Appium session (${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e}): not restarting it.`);
+            }
+            if (!heldByAppiumSession(device))
+                return;
+            throw new StreamRestartRefused(`Stream for ${udid} is not answering, but Appium session ${device === null || device === void 0 ? void 0 : device.session_id} holds the device: not restarting the WDA and go-ios tunnel it may be driving. The stream can restart once the session ends.`);
+        });
+    }
     /**
      * Check if WDA is already running and responding
      * Principal Resilience: Retries transient connection errors (ECONNRESET) up to 2 times
      * with exponential backoff, as these often indicate WDA is restarting or tunnel is reconnecting.
+     *
+     * It says whether *a* WDA answers on the port, never whose. WDA names no
+     * phone: /status carries os, ios.ip, build and device (the form factor),
+     * and /wda/device/info's `uuid` is identifierForVendor, not the UDID. So it
+     * takes no udid. A caller that must know the phone relies on the port
+     * being one it already knows belongs to it: its own stream's leased port,
+     * or the Device row's port while an Appium session holds that phone.
      */
-    isWDARunning(wdaPort_1, udid_1) {
-        return __awaiter(this, arguments, void 0, function* (wdaPort, udid, retries = 2) {
-            var _a, _b, _c, _d, _e, _f, _g;
+    isWDARunning(wdaPort_1) {
+        return __awaiter(this, arguments, void 0, function* (wdaPort, retries = 2) {
+            var _a, _b, _c, _d;
             const axios = (yield Promise.resolve().then(() => __importStar(require('axios')))).default;
             const host = '127.0.0.1'; // Force IPv4 for local tunnels
             const maxRetries = retries;
@@ -380,15 +462,9 @@ let IOSStreamService = class IOSStreamService {
                         httpAgent: new http_1.default.Agent({ keepAlive: false }),
                         validateStatus: (status) => status === 200,
                     });
-                    // Principal Resilience: Verify the UDID if provided to ensure we're talking to the right device
-                    const remoteUdid = (_c = (_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.ios) === null || _c === void 0 ? void 0 : _c.udid;
-                    if (udid && remoteUdid && remoteUdid !== udid) {
-                        logger_1.default.warn(`[WDA] Port ${wdaPort} is used by a DIFFERENT device: ${remoteUdid} (expected ${udid})`);
-                        return false;
-                    }
-                    const isReady = ((_e = (_d = response.data) === null || _d === void 0 ? void 0 : _d.value) === null || _e === void 0 ? void 0 : _e.ready) === true;
+                    const isReady = ((_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.ready) === true;
                     if (!isReady) {
-                        logger_1.default.debug(`[WDA] Port ${wdaPort} active but not ready. Status: ${JSON.stringify((_f = response.data) === null || _f === void 0 ? void 0 : _f.value)}`);
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} active but not ready. Status: ${JSON.stringify((_c = response.data) === null || _c === void 0 ? void 0 : _c.value)}`);
                     }
                     return isReady;
                 }
@@ -400,7 +476,7 @@ let IOSStreamService = class IOSStreamService {
                         (error.response && error.response.status >= 500);
                     if (isTransientError && attempt < maxRetries) {
                         const backoffMs = Math.min(500 * Math.pow(2, attempt), 2000); // 500ms, 1000ms, 2000ms max
-                        logger_1.default.debug(`[WDA] Port ${wdaPort} transient error (${error.code || ((_g = error.response) === null || _g === void 0 ? void 0 : _g.status)}), retrying in ${backoffMs}ms (attempt ${attempt + 1}/${maxRetries + 1})`);
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} transient error (${error.code || ((_d = error.response) === null || _d === void 0 ? void 0 : _d.status)}), retrying in ${backoffMs}ms (attempt ${attempt + 1}/${maxRetries + 1})`);
                         yield new Promise((resolve) => setTimeout(resolve, backoffMs));
                         continue;
                     }
@@ -443,7 +519,7 @@ let IOSStreamService = class IOSStreamService {
             }
             if (!isWdaIproxyAlive || !isMjpegIproxyAlive) {
                 logger_1.default.warn(`🛡️ [${udid}] [Watchdog] Tunnel processes are dead. Attempting tunnel-only recovery...`);
-                const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                 if (device && device.ip) {
                     // Double check if WDA is alive via network IP
                     const isWdaAccessibleViaNetwork = yield this.isWDARunningOnHost(device.ip, 8100);
@@ -459,7 +535,7 @@ let IOSStreamService = class IOSStreamService {
             const isRespondingViaTunnel = yield this.isWDARunning(session.wdaPort);
             if (!isRespondingViaTunnel) {
                 logger_1.default.warn(`🛡️ [${udid}] [Watchdog] WDA tunnel on port ${session.wdaPort} is unresponsive. checking network...`);
-                const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                 if (device && device.ip) {
                     const isWdaAccessibleViaNetwork = yield this.isWDARunningOnHost(device.ip, 8100);
                     if (isWdaAccessibleViaNetwork) {
@@ -543,6 +619,8 @@ let IOSStreamService = class IOSStreamService {
                     logger_1.default.debug(`[${udid}] Stream already running and healthy, reusing existing session`);
                     return { wdaPort: existingSession.wdaPort, mjpegPort: existingSession.mjpegPort };
                 }
+                // Never under a live Appium session (see refuseRestartUnderAppiumSession).
+                yield this.refuseRestartUnderAppiumSession(udid);
                 // Stream exists but unhealthy - check cooldown before recovery
                 if (!this.canAttemptRecovery(udid)) {
                     const lastAttempt = this.recoveryCooldowns.get(udid);
@@ -578,6 +656,7 @@ let IOSStreamService = class IOSStreamService {
                             logger_1.default.debug(`[${udid}] Stream already running and healthy, reusing existing session`);
                             return { wdaPort: existingSession.wdaPort, mjpegPort: existingSession.mjpegPort };
                         }
+                        yield this.refuseRestartUnderAppiumSession(udid);
                         // Stream exists but unhealthy - check cooldown before recovery
                         if (!this.canAttemptRecovery(udid)) {
                             const lastAttempt = this.recoveryCooldowns.get(udid);
@@ -588,10 +667,17 @@ let IOSStreamService = class IOSStreamService {
                         logger_1.default.info(`Existing session for ${udid} not responding, restarting...`);
                         this.markRecoveryAttempt(udid);
                     }
-                    const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                    const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                     if (!device)
                         throw new Error(`Device ${udid} not found`);
-                    // Always resolve stream ports through the PortAllocator — never a value
+                    // Tear down this udid's previous session BEFORE acquiring ports, never
+                    // after. acquire() hands a udid back its own existing leases, so a
+                    // failed start's session names the very port numbers this start is
+                    // about to get. Stopped after acquiring, its release() deleted this
+                    // start's leases: the stream ran on unleased ports, and the allocator
+                    // gave its 9100 to the S9+. A no-op when there is no previous session.
+                    yield this.stopStream(udid);
+                    // Resolve stream ports through the PortAllocator — never a value
                     // persisted on the Device row. A stale persisted mjpegServerPort (e.g.
                     // 9100) bypassed the allocator and could collide with another device's
                     // live lease on the same port (the Android stream leases 9100 too),
@@ -599,13 +685,29 @@ let IOSStreamService = class IOSStreamService {
                     // guarantee a non-colliding port; the lease is refreshed by the watchdog
                     // and released in stopStream().
                     const portAllocator = typedi_2.Container.get(PortAllocator_1.PortAllocator);
-                    const wdaPort = yield portAllocator.acquire('wda', udid, { ttlMs: this.STREAM_PORT_TTL_MS });
-                    const mjpegPort = yield portAllocator.acquire('mjpeg', udid, {
-                        ttlMs: this.STREAM_PORT_TTL_MS,
-                    });
-                    // Principal Discovery: Check if WDA is already up (e.g. from an active Appium session)
-                    // If yes, and it belongs to our device, we simply attach to it instead of killing it.
-                    const alreadyUp = yield this.isWDARunning(wdaPort, udid);
+                    const ttl = { ttlMs: this.STREAM_PORT_TTL_MS };
+                    // Principal Discovery: attach to the WDA an Appium session runs on this
+                    // device instead of launching a second one over it. The one exception
+                    // to the rule above: that session's forwarder listens on the Device
+                    // row's wdaLocalPort (iOSCapabilities hands it to Appium), and acquire()
+                    // can't find it, because it refuses any port with a live listener, this
+                    // device's own included. Only while an Appium session holds the device:
+                    // WDA names no phone (see isWDARunning), so that session is the only
+                    // evidence the port is this phone's. Outside one, an answer on a stale
+                    // row's port may be another phone's WDA.
+                    const appiumWdaPort = heldByAppiumSession(device) ? device.wdaLocalPort : undefined;
+                    const alreadyUp = !!appiumWdaPort && (yield this.isWDARunning(appiumWdaPort));
+                    let wdaPort;
+                    if (appiumWdaPort && alreadyUp) {
+                        wdaPort = appiumWdaPort;
+                        if (!(yield portAllocator.claim('wda', udid, wdaPort, ttl))) {
+                            logger_1.default.warn(`[${udid}] WDA port ${wdaPort} is leased to another device; attaching unleased`);
+                        }
+                    }
+                    else {
+                        wdaPort = yield portAllocator.acquire('wda', udid, ttl);
+                    }
+                    const mjpegPort = yield portAllocator.acquire('mjpeg', udid, ttl);
                     if (alreadyUp) {
                         logger_1.default.info(`[${udid}] WDA already responding on port ${wdaPort}. Attaching to existing tunnel...`);
                         // WDA reachable on 127.0.0.1:wdaPort means the WDA iproxy is live, but the
@@ -653,7 +755,7 @@ let IOSStreamService = class IOSStreamService {
                         return { wdaPort, mjpegPort };
                     }
                     // Perform aggressive cleanup of any existing processes for THIS device/ports
-                    yield this.stopStream(udid);
+                    // (the previous session was already stopped, before the ports were acquired)
                     yield this.killStaleProcesses(udid, wdaPort, mjpegPort);
                     const session = {
                         udid,
@@ -788,7 +890,7 @@ let IOSStreamService = class IOSStreamService {
                                 logger_1.default.warn(`Failed to get screen size for ${udid}: ${e}`);
                             }
                             // Update device info in store
-                            const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                            const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                             if (device) {
                                 const updateData = {
                                     wdaLocalPort: wdaPort,
@@ -836,6 +938,9 @@ let IOSStreamService = class IOSStreamService {
                     throw new Error(`WDA failed to start within ${timeout / 1000}s. Check logs.`);
                 }
                 catch (error) {
+                    // Not a failed start: the running stream is left exactly as it was.
+                    if (error instanceof StreamRestartRefused)
+                        throw error;
                     const session = this.sessions.get(udid);
                     if (session) {
                         session.status = 'error';
@@ -908,12 +1013,29 @@ let IOSStreamService = class IOSStreamService {
             yield new Promise((resolve) => setTimeout(resolve, 500));
         });
     }
-    stopStream(udid) {
-        return __awaiter(this, void 0, void 0, function* () {
+    /**
+     * Stop this udid's stream: its processes, a live-preview hold, the go-ios
+     * orphan sweep (see cleanupOrphanTunnels) and its port leases.
+     *
+     * `forViewer` means the caller is only done watching (stream/stop,
+     * stream/leave). While an Appium session holds the phone and this stream
+     * launched its own WDA, nothing is stopped: a session allocated while the
+     * stream ran drives that WDA, through this stream's forwarder and go-ios
+     * tunnel. The session's teardown stops it (EventManager
+     * stopIdleStreamForDevice), or the idle watchdog once the session has
+     * ended. A restart never passes it: the WDA already failed its health check.
+     */
+    stopStream(udid_1) {
+        return __awaiter(this, arguments, void 0, function* (udid, opts = {}) {
             var _a, _b;
             const session = this.sessions.get(udid);
             if (!session)
                 return;
+            if (opts.forViewer &&
+                session.wdaProcess &&
+                (yield this.appiumSessionMayUse(udid, "the stream's WDA and go-ios tunnel"))) {
+                return;
+            }
             // Kill sidecar processes. The go-ios tunnel is detached (its own process
             // group), so reap the whole group — a plain p.kill() would leave the
             // self-forking agent children behind to respawn. See ./tunnelProcess.
@@ -931,7 +1053,7 @@ let IOSStreamService = class IOSStreamService {
             // The lock could belong to an Appium automation session (session_id is a real UUID).
             // We should only unblock if it's a manual control lock (session_id starts with 'manual_').
             try {
-                const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                 if (device && ((_b = device.session_id) === null || _b === void 0 ? void 0 : _b.startsWith('manual_'))) {
                     logger_1.default.info(`Stream Stop: Releasing manual control lock for ${udid}`);
                     yield (0, device_service_1.unblockDevice)(udid, device.host);
@@ -949,8 +1071,8 @@ let IOSStreamService = class IOSStreamService {
             // devices — they were held for the lifetime of this stream.
             try {
                 const portAllocator = typedi_2.Container.get(PortAllocator_1.PortAllocator);
-                yield portAllocator.release(session.wdaPort);
-                yield portAllocator.release(session.mjpegPort);
+                yield portAllocator.release(session.wdaPort, udid);
+                yield portAllocator.release(session.mjpegPort, udid);
             }
             catch (e) {
                 logger_1.default.warn(`Failed to release port leases for ${udid}: ${e}`);

package/lib/src/device-managers/localDeviceHosts.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverOrigin = serverOrigin;
+exports.parseAdbRemote = parseAdbRemote;
+exports.androidDeviceHost = androidDeviceHost;
+exports.iosRealDeviceHost = iosRealDeviceHost;
+exports.iosSimulatorHost = iosSimulatorHost;
+exports.localDeviceHosts = localDeviceHosts;
+exports.isLocalDeviceHost = isLocalDeviceHost;
+exports.isOwnDevice = isOwnDevice;
+exports.devicesClearedAtBoot = devicesClearedAtBoot;
+/** This server's origin, `http://<bindHostOrIp>:<port>`. */
+function serverOrigin(args, port) {
+    return `http://${args.bindHostOrIp}:${port}`;
+}
+/** An `adbRemote` entry, `host[:port]`, with adb's default port 5037. */
+function parseAdbRemote(value) {
+    const [adbHost, adbPort] = value.split(':');
+    return { adbHost, adbPort: parseInt(adbPort) || 5037 };
+}
+/**
+ * An Android phone: a phone on a remote adb server is filed under that
+ * server; otherwise under remoteMachineProxyIP with this server's port;
+ * otherwise under this server.
+ */
+function androidDeviceHost(args, port, adb) {
+    if ((adb === null || adb === void 0 ? void 0 : adb.adbHost) != null)
+        return `http://${adb.adbHost}:${adb.adbPort}`;
+    if (args.remoteMachineProxyIP !== undefined)
+        return `http://${args.remoteMachineProxyIP}:${port}`;
+    return serverOrigin(args, port);
+}
+/** A real iOS device: remoteMachineProxyIP as given (no port added), otherwise this server. */
+function iosRealDeviceHost(args, port) {
+    return args.remoteMachineProxyIP ? String(args.remoteMachineProxyIP) : serverOrigin(args, port);
+}
+/** An iOS simulator: always this server. */
+function iosSimulatorHost(args, port) {
+    return serverOrigin(args, port);
+}
+function localDeviceHosts(args, port) {
+    var _a;
+    return {
+        origin: serverOrigin(args, port),
+        hosts: new Set([
+            serverOrigin(args, port),
+            androidDeviceHost(args, port),
+            ...((_a = args.adbRemote) !== null && _a !== void 0 ? _a : []).map((value) => androidDeviceHost(args, port, parseAdbRemote(value))),
+            iosRealDeviceHost(args, port),
+            iosSimulatorHost(args, port),
+        ]),
+    };
+}
+/** Whether a row's host is one this server writes: exact, never by IP or prefix. */
+function isLocalDeviceHost(local, host) {
+    return host != null && local.hosts.has(host);
+}
+/**
+ * Whether a phone's row is this server's own, for stale cleanup. A row names
+ * the server process that found it (`nodeId`, new on every boot; a node's
+ * report carries the node's), so that decides: another server's phone is
+ * never pruned as this one's, even under a host this server also files
+ * phones under (a shared remoteMachineProxyIP or adb server), and is
+ * host-checked as the other server's. A row with no nodeId falls back to its
+ * host.
+ */
+function isOwnDevice(local, nodeId, device) {
+    if (device.nodeId)
+        return device.nodeId === nodeId;
+    return isLocalDeviceHost(local, device.host);
+}
+/**
+ * Which phones a server forgets when it starts: the hosts to clear, or
+ * undefined for every phone.
+ *
+ * A hub keeps its nodes' phones. Their sessions keep running on the nodes
+ * while the hub restarts, and the hub finds where to route them from those
+ * rows (SessionManager.recoverActiveSessions, gateway/sessionLocator.ts). A
+ * node that died meanwhile is pruned by removeStaleDevices, and a live one's
+ * next report refreshes its rows. A hub's own phones are cleared as before:
+ * discovery adds back the attached ones, and their sessions died with it.
+ * A node clears everything, as it always has.
+ */
+function devicesClearedAtBoot(args, local) {
+    return args.hub === undefined ? [...local.hosts] : undefined;
+}

package/lib/src/device-managers/ownDeviceRow.js

@@ -0,0 +1,38 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findOwnDevice = findOwnDevice;
+const typedi_1 = require("typedi");
+const device_store_1 = require("../data-service/device-store");
+const PluginContext_1 = require("../PluginContext");
+const localDeviceHosts_1 = require("./localDeviceHosts");
+/**
+ * This server's own Device row for a phone it drives: the udid under one of
+ * the hosts its discovery files phones under (localDeviceHosts), never
+ * another server's row. A hub's table also holds its nodes' rows, and a node
+ * on the same machine sees the same phones (an iPhone, emulator-5554), so a
+ * udid alone may name the node's row, with the node's holds and sessions.
+ *
+ * One lookup per own host, usually just one. Null when none of them has the
+ * phone.
+ */
+function findOwnDevice(udid) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const ctx = typedi_1.Container.get(PluginContext_1.PluginContext);
+        const store = device_store_1.DeviceStoreFactory.getStore();
+        for (const host of (0, localDeviceHosts_1.localDeviceHosts)(ctx.pluginArgs, ctx.port).hosts) {
+            const device = yield store.findDevice({ udid, host });
+            if (device)
+                return device;
+        }
+        return null;
+    });
+}