@xenon-device-management/xenon 2.0.0 → 2.1.0

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

@@ -67,13 +67,18 @@ class NodeDevices {
             }
         });
     }
-    unRegisterNode(host) {
+    /**
+     * Ask the hub to forget this node's phones filed under `host`. With the
+     * node's id the hub takes every phone this node reported, whatever its
+     * host; it never takes another server's (grid.ts, removeNodeDevices).
+     */
+    unRegisterNode(host, nodeId) {
         return __awaiter(this, void 0, void 0, function* () {
             logger_1.default.info(`Unregistering node ${this.host}/xenon/api/register`);
             try {
                 const client = InternalHttpClient_1.InternalHttpClient.getClient(this.tlsRejectUnauthorized);
                 yield client.post(`${this.host}/xenon/api/register`, [], {
-                    params: { type: 'unregister', host },
+                    params: Object.assign({ type: 'unregister', host }, (nodeId ? { nodeId } : {})),
                     headers: this.nodeHeaders(),
                 });
                 logger_1.default.info(`Unregistered node ${host} from hub`);

package/lib/src/device-managers/android/AndroidH264StreamService.js

@@ -57,7 +57,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../../logger"));
-const device_store_1 = require("../../data-service/device-store");
+const ownDeviceRow_1 = require("../ownDeviceRow");
 const H264Multiplexer_1 = require("./H264Multiplexer");
 const h264NalParser_1 = require("./h264NalParser");
 const androidH264Config_1 = require("../../app/routers/androidH264Config");
@@ -266,7 +266,7 @@ let AndroidH264StreamService = class AndroidH264StreamService {
     startScrcpyOrThrow(udid, onPacket) {
         return __awaiter(this, void 0, void 0, function* () {
             const { ScrcpyServerSession, scrcpyMaxSizeFromDims } = yield Promise.resolve().then(() => __importStar(require('./ScrcpyServerSession')));
-            const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+            const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
             const maxSize = scrcpyMaxSizeFromDims(Number(device === null || device === void 0 ? void 0 : device.screenWidth), Number(device === null || device === void 0 ? void 0 : device.screenHeight));
             const parser = new h264NalParser_1.H264NalParser();
             const session = new ScrcpyServerSession(udid);
@@ -405,7 +405,7 @@ let AndroidH264StreamService = class AndroidH264StreamService {
     resolveCaptureSize(udid) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
-                const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                 const sw = Number(device === null || device === void 0 ? void 0 : device.screenWidth);
                 const sh = Number(device === null || device === void 0 ? void 0 : device.screenHeight);
                 if (Number.isFinite(sw) && Number.isFinite(sh) && sw > 0 && sh > 0) {

package/lib/src/device-managers/android/AndroidStreamService.js

@@ -59,6 +59,7 @@ const http_1 = __importDefault(require("http"));
 const sharp_1 = __importDefault(require("sharp"));
 const logger_1 = __importDefault(require("../../logger"));
 const device_store_1 = require("../../data-service/device-store");
+const ownDeviceRow_1 = require("../ownDeviceRow");
 const DeviceLockManager_1 = require("./DeviceLockManager");
 const typedi_1 = require("typedi");
 const ResourceIsolationService_1 = require("../../services/ResourceIsolationService");
@@ -272,7 +273,7 @@ let AndroidStreamService = class AndroidStreamService {
                             `(${decision.reason}); discarding it and starting fresh.`);
                         yield this.disposeSession(udid, existing);
                     }
-                    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 in DB`);
                     // Resolve the real adb binary once, up front, so the capture loop never
@@ -315,7 +316,7 @@ let AndroidStreamService = class AndroidStreamService {
                             catch (_d) {
                                 /* ignore */
                             }
-                            yield portAllocator.release(mjpegPort).catch(() => undefined);
+                            yield portAllocator.release(mjpegPort, udid).catch(() => undefined);
                             yield portAllocator.blockPort(mjpegPort, 'mjpeg').catch(() => undefined);
                         }
                     }
@@ -346,7 +347,7 @@ let AndroidStreamService = class AndroidStreamService {
                         logger_1.default.info(`[${udid}] MJPEG stream primed with first frame.`);
                     }
                     // Update device info in store to ensure other services (like VideoPipeline) can find the port
-                    const updatedDevice = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                    const updatedDevice = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
                     if (updatedDevice) {
                         yield device_store_1.DeviceStoreFactory.getStore().updateDevice(udid, updatedDevice.host, {
                             mjpegServerPort: mjpegPort,
@@ -393,7 +394,7 @@ let AndroidStreamService = class AndroidStreamService {
             if (this.sessions.get(udid) === session)
                 this.sessions.delete(udid);
             try {
-                yield typedi_1.Container.get(PortAllocator_1.PortAllocator).release(session.mjpegPort);
+                yield typedi_1.Container.get(PortAllocator_1.PortAllocator).release(session.mjpegPort, udid);
             }
             catch (e) {
                 logger_1.default.warn(`[${udid}] Failed to release mjpeg port lease while restarting stream: ${e}`);
@@ -420,7 +421,7 @@ let AndroidStreamService = class AndroidStreamService {
                 // 'mjpeg' lease is released here — the device-level 'system' port (leased
                 // by AndroidDeviceManager) belongs to the device lifecycle, not the stream.
                 try {
-                    yield typedi_1.Container.get(PortAllocator_1.PortAllocator).release(session.mjpegPort);
+                    yield typedi_1.Container.get(PortAllocator_1.PortAllocator).release(session.mjpegPort, udid);
                 }
                 catch (e) {
                     logger_1.default.warn(`[${udid}] Failed to release mjpeg port lease on stop: ${e}`);

package/lib/src/device-managers/android/previewHold.js

@@ -16,7 +16,7 @@ exports.mayReleasePreviewHold = mayReleasePreviewHold;
 exports.releaseIdlePreviewHold = releaseIdlePreviewHold;
 const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../../logger"));
-const device_store_1 = require("../../data-service/device-store");
+const ownDeviceRow_1 = require("../ownDeviceRow");
 const device_service_1 = require("../../data-service/device-service");
 const manualLock_1 = require("../../services/recording/manualLock");
 const recording_store_1 = require("../../services/recording/recording-store");
@@ -43,7 +43,7 @@ function releaseIdlePreviewHold(udid) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d, _e;
         try {
-            const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+            const device = yield (0, ownDeviceRow_1.findOwnDevice)(udid);
             if (!device)
                 return false;
             // eslint-disable-next-line @typescript-eslint/no-var-requires

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();
@@ -146,7 +167,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;
@@ -184,7 +205,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 +350,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 +390,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 +460,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 +474,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 +517,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 +533,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 +617,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 +654,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 +665,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 +683,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 +753,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 +888,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 +936,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 +1011,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 +1051,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 +1069,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}`);