@midscene/android 1.12.0 → 1.12.1-beta-20260824081858.0

package/dist/es/index.mjs

@@ -8,7 +8,7 @@ import { getMidsceneLocationSchema, z } from "@midscene/core";
 import { createDefaultMobileActions, defineAction } from "@midscene/core/device";
 import { getTmpFile, sleep } from "@midscene/core/utils";
 import { MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_ANDROID_SCREENSHOT_STRATEGY, globalConfigManager, overrideAIConfig } from "@midscene/shared/env";
-import { createImgBase64ByFormat, validateScreenshotBuffer } from "@midscene/shared/img";
+import { createImgBase64ByFormat, imageInfoOfBase64, resizeBase64ImageToJpeg, validateScreenshotBuffer } from "@midscene/shared/img";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat } from "@midscene/shared/utils";
 import { ADB, getSdkRootFromEnv } from "appium-adb";
 import { Agent } from "@midscene/core/agent";
@@ -29,7 +29,6 @@ var __webpack_modules__ = {
         __webpack_require__.d(__webpack_exports__, {
             GJ: ()=>isScrcpyFreshFrameUnavailableError,
             ScrcpyScreenshotManager: ()=>ScrcpyScreenshotManager,
-            Xr: ()=>SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT,
             ov: ()=>DEFAULT_SCRCPY_CONFIG
         });
         var node_fs__rspack_import_0 = __webpack_require__("node:fs");
@@ -63,7 +62,6 @@ var __webpack_modules__ = {
         const FRESH_FRAME_TIMEOUT_MS = 300;
         const KEYFRAME_POLL_INTERVAL_MS = 200;
         const MAX_SCAN_BYTES = 1000;
-        const CONNECTION_WAIT_MS = 1000;
         const MAX_SERVER_OUTPUT_LINES = 100;
         const SERVER_OUTPUT_DRAIN_TIMEOUT_MS = 500;
         const MAX_FRAME_AGE_US = 500000n;
@@ -73,7 +71,12 @@ var __webpack_modules__ = {
             'dumpsys',
             'power'
         ];
-        const SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT = 'The appropriate scrcpy video bitrate depends on network conditions. For constrained remote links, consider setting scrcpyConfig.videoBitRate to 4_000_000 (4 Mbps) as a starting point, and lower it further if backlog persists.';
+        const SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT = 'The appropriate scrcpy video bitrate depends on network conditions. For constrained remote links, pass --scrcpy-video-bit-rate 4000000 in the Android CLI, or set scrcpyConfig.videoBitRate to 4_000_000 (4 Mbps) in SDK/YAML configuration. Lower it further if backlog persists.';
+        const CONSTRAINED_LINK_STARTING_VIDEO_BIT_RATE = 4000000;
+        function getScrcpyVideoBitRateNetworkHint(currentVideoBitRate) {
+            if (currentVideoBitRate <= CONSTRAINED_LINK_STARTING_VIDEO_BIT_RATE) return 'The current scrcpy video bitrate is already at or below 4 Mbps. Lowering it further is unlikely to help on a local USB connection; check whether the screen was static or the device encoder emitted no new frame.';
+            return SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT;
+        }
         const BUSY_LOOP_WINDOW_MS = 1000;
         const BUSY_LOOP_MAX_READS = 500;
         const BUSY_LOOP_COOLDOWN_MS = 50;
@@ -87,8 +90,9 @@ var __webpack_modules__ = {
         const SCRCPY_FRESH_FRAME_UNAVAILABLE_ERROR_CODE = 'ERR_SCRCPY_FRESH_FRAME_UNAVAILABLE';
         class ScrcpyFreshFrameUnavailableError extends Error {
             constructor(message, options){
-                super(message, options), _define_property(this, "code", SCRCPY_FRESH_FRAME_UNAVAILABLE_ERROR_CODE);
+                super(message, options), _define_property(this, "code", SCRCPY_FRESH_FRAME_UNAVAILABLE_ERROR_CODE), _define_property(this, "diagnosticMessage", void 0);
                 this.name = 'ScrcpyFreshFrameUnavailableError';
+                this.diagnosticMessage = options?.diagnosticMessage;
             }
         }
         function isScrcpyFreshFrameUnavailableError(error) {
@@ -121,26 +125,30 @@ var __webpack_modules__ = {
                 await this.ensureFfmpegAvailable();
             }
             async ensureConnected() {
+                if (this.disposed) throw new Error('Scrcpy manager has been disposed');
                 if (this.scrcpyClient && this.videoStream) {
                     debugScrcpy('Scrcpy already connected');
                     await this.ensureFrameClockCalibration();
                     this.resetIdleTimer();
                     return;
                 }
-                if (this.isConnecting) {
-                    debugScrcpy('Connection already in progress, waiting...');
-                    await new Promise((resolve)=>setTimeout(resolve, CONNECTION_WAIT_MS));
-                    if (this.scrcpyClient && this.videoStream) {
-                        await this.ensureFrameClockCalibration();
-                        this.resetIdleTimer();
-                        return;
-                    }
-                    throw new Error('Scrcpy connection failed: another connection attempt did not complete in time');
+                if (this.connectionPromise) {
+                    debugScrcpy('Connection already in progress, sharing the same attempt...');
+                    await this.connectionPromise;
+                    return;
                 }
+                const connectionPromise = this.connectScrcpy();
+                this.connectionPromise = connectionPromise;
+                try {
+                    await connectionPromise;
+                } finally{
+                    if (this.connectionPromise === connectionPromise) this.connectionPromise = null;
+                }
+            }
+            async connectScrcpy() {
                 const serverOutput = [];
                 let serverOutputTask = null;
                 try {
-                    this.isConnecting = true;
                     debugScrcpy('Starting scrcpy connection...');
                     const { AdbScrcpyClient } = await import("@yume-chan/adb-scrcpy");
                     const { ReadableStream } = await import("@yume-chan/stream-extra");
@@ -160,6 +168,8 @@ var __webpack_modules__ = {
                         height
                     };
                     await this.ensureFrameClockCalibration();
+                    this.streamBaselineFramePending = true;
+                    this.streamBaselineFrameDeadlineAt = Date.now() + MAX_KEYFRAME_WAIT_MS;
                     this.startFrameConsumer();
                     this.resetIdleTimer();
                     this.isInitialized = true;
@@ -172,8 +182,6 @@ var __webpack_modules__ = {
                         new Promise((resolve)=>setTimeout(resolve, SERVER_OUTPUT_DRAIN_TIMEOUT_MS))
                     ]);
                     throw this.createConnectionError(error, serverOutput);
-                } finally{
-                    this.isConnecting = false;
                 }
             }
             async createScrcpyOptions() {
@@ -358,24 +366,30 @@ var __webpack_modules__ = {
                     if (this.deviceClockCalibrationPromise === calibrationPromise) this.deviceClockCalibrationPromise = null;
                 }
             }
-            async setFreshnessBarrier(reason) {
+            async setFreshnessBarrier(reason, options = {}) {
+                const cachedFrame = this.getCachedKeyframeCandidate();
                 const generation = ++this.frameFreshnessBarrierGeneration;
                 this.frameFreshnessBarrierPending = true;
+                this.frameFreshnessBarrierAllowsOverAgeForNextCapture = false;
                 this.clearFrameCache();
                 try {
                     const calibration = this.deviceClockCalibration;
                     if (!calibration) throw new Error('Scrcpy frame clock is not calibrated for the current stream epoch');
-                    const hostMonotonicUs = this.monotonicTimeUs();
+                    const hostMonotonicUs = options.hostMonotonicUs ?? this.monotonicTimeUs();
                     const estimatedDeviceNowUs = this.estimateDeviceTimeUs(hostMonotonicUs, calibration);
                     const conservativeDeviceNowUs = estimatedDeviceNowUs + this.getCalibrationUncertaintyUs(calibration);
                     const barrierPtsUs = (conservativeDeviceNowUs / 1000n + 1n) * 1000n;
                     if (generation !== this.frameFreshnessBarrierGeneration) return this.frameFreshnessBarrierPtsUs ?? barrierPtsUs;
                     this.frameFreshnessBarrierPtsUs = null === this.frameFreshnessBarrierPtsUs || barrierPtsUs > this.frameFreshnessBarrierPtsUs ? barrierPtsUs : this.frameFreshnessBarrierPtsUs;
                     this.frameFreshnessBarrierReason = reason;
+                    this.frameFreshnessBarrierAllowsOverAgeForNextCapture = options.allowOverAgeForNextCapture ?? false;
                     this.frameFreshnessBarrierPending = false;
                     this.frameFreshnessError = null;
                     this.lastFramePtsUs = null;
-                    this.clearFrameCache();
+                    if (cachedFrame?.ptsUs !== void 0 && cachedFrame.ptsUs >= this.frameFreshnessBarrierPtsUs) {
+                        this.restoreFrameCache(cachedFrame);
+                        debugScrcpy(`Preserved cached frame PTS ${cachedFrame.ptsUs}µs because it crosses the newly armed ${reason} barrier`);
+                    } else this.clearFrameCache();
                     debugScrcpy(`Armed frame freshness barrier at PTS ${this.frameFreshnessBarrierPtsUs}µs (${reason}, projected from stream-epoch clock anchor, uncertainty<=${Number(this.getCalibrationUncertaintyUs(calibration)) / 1000}ms)`);
                     return this.frameFreshnessBarrierPtsUs;
                 } catch (error) {
@@ -396,6 +410,7 @@ var __webpack_modules__ = {
                         this.frameFreshnessBarrierPending = true;
                         this.frameFreshnessBarrierPtsUs = null;
                         this.frameFreshnessBarrierReason = null;
+                        this.frameFreshnessBarrierAllowsOverAgeForNextCapture = false;
                         this.deviceClockCalibration = null;
                         this.clearFrameCache();
                         this.warnFrameFreshness();
@@ -417,7 +432,7 @@ var __webpack_modules__ = {
                 const behindBarrierUs = this.frameFreshnessBarrierPtsUs - packetPtsUs;
                 this.frameFreshnessError = new Error(`Scrcpy frame predates the ${this.frameFreshnessBarrierReason ?? 'active'} freshness barrier by ${Number(behindBarrierUs) / 1000}ms; refusing to use it`);
                 this.clearFrameCache();
-                this.warnFrameFreshness();
+                debugScrcpy(this.frameFreshnessError.message);
                 return false;
             }
             estimateFrameAgeUs(packetPtsUs, hostMonotonicUs = this.monotonicTimeUs()) {
@@ -467,13 +482,18 @@ var __webpack_modules__ = {
                     this.lastFrameFreshnessWarningAt = now;
                 }
             }
-            warnTransportBacklog(error) {
-                const now = Date.now();
-                if (now - this.lastTransportBacklogWarningAt < TRANSPORT_BACKLOG_WARN_INTERVAL_MS) return;
+            transportBacklogMessage(error) {
                 const cause = this.frameFreshnessError ?? error;
                 const causeMessage = cause instanceof Error ? cause.message : String(cause);
+                if (this.streamBaselineFramePending && null === this.frameFreshnessBarrierPtsUs) return `The new scrcpy stream did not produce a usable baseline frame within its ${MAX_KEYFRAME_WAIT_MS}ms startup window; closing the stream epoch and falling back to ADB screenshot. This is a stream startup or encoder-readiness failure, not evidence that the configured video bitrate is too high.\nError: ${causeMessage}`;
                 const currentBitRateMbps = this.options.videoBitRate / 1000000;
-                warnScrcpy(`No usable scrcpy frame crossed the active freshness target within ${FRESH_FRAME_TIMEOUT_MS}ms; closing the stale stream epoch and falling back to ADB screenshot. This may indicate transport backlog or a static screen that emitted no new frame. ${SCRCPY_VIDEO_BIT_RATE_NETWORK_HINT} Current videoBitRate: ${this.options.videoBitRate} bps (${currentBitRateMbps} Mbps).\nError: ${causeMessage}`);
+                const networkHint = getScrcpyVideoBitRateNetworkHint(this.options.videoBitRate);
+                return `No usable scrcpy frame crossed the active freshness target within ${FRESH_FRAME_TIMEOUT_MS}ms; closing the stale stream epoch and falling back to ADB screenshot. This may indicate transport backlog or a static screen that emitted no new frame. ${networkHint} Current videoBitRate: ${this.options.videoBitRate} bps (${currentBitRateMbps} Mbps).\nError: ${causeMessage}`;
+            }
+            warnTransportBacklog(error) {
+                const now = Date.now();
+                if (now - this.lastTransportBacklogWarningAt < TRANSPORT_BACKLOG_WARN_INTERVAL_MS) return;
+                warnScrcpy(this.transportBacklogMessage(error));
                 this.lastTransportBacklogWarningAt = now;
             }
             estimateFrameTiming(packetPtsUs, receivedAtUs) {
@@ -495,12 +515,21 @@ var __webpack_modules__ = {
                 this.lastRawKeyframePtsUs = void 0;
                 this.lastRawKeyframeEstimatedAgeMs = void 0;
             }
+            restoreFrameCache(frame) {
+                this.lastRawKeyframe = frame.data;
+                this.lastRawKeyframeAt = frame.capturedAt;
+                this.lastRawKeyframePtsUs = frame.ptsUs;
+                this.lastRawKeyframeEstimatedAgeMs = frame.estimatedAgeMs;
+            }
             monotonicTimeUs() {
                 return process.hrtime.bigint() / 1000n;
             }
             resetFrameFreshnessState() {
                 this.frameFreshnessBarrierPtsUs = null;
                 this.frameFreshnessBarrierReason = null;
+                this.frameFreshnessBarrierAllowsOverAgeForNextCapture = false;
+                this.streamBaselineFramePending = false;
+                this.streamBaselineFrameDeadlineAt = 0;
                 this.frameFreshnessBarrierPending = false;
                 this.frameFreshnessBarrierGeneration = 0;
                 this.deviceClockCalibration = null;
@@ -532,35 +561,52 @@ var __webpack_modules__ = {
                     capturedAt: this.lastRawKeyframeAt
                 };
             }
+            canReuseFrameAcrossActionWait(frame) {
+                return this.frameFreshnessBarrierAllowsOverAgeForNextCapture && null !== this.frameFreshnessBarrierPtsUs && void 0 !== frame.ptsUs && frame.ptsUs >= this.frameFreshnessBarrierPtsUs;
+            }
+            canUseStreamBaseline(frame) {
+                return this.streamBaselineFramePending && !this.frameFreshnessBarrierPending && null === this.frameFreshnessBarrierPtsUs && Date.now() <= this.streamBaselineFrameDeadlineAt && void 0 !== frame.ptsUs;
+            }
+            consumeActionFreshnessBarrier(frame) {
+                if (!this.canReuseFrameAcrossActionWait(frame)) return;
+                this.frameFreshnessBarrierPtsUs = null;
+                this.frameFreshnessBarrierReason = null;
+                this.frameFreshnessBarrierAllowsOverAgeForNextCapture = false;
+                this.frameFreshnessError = null;
+            }
             async decodeRawKeyframeToJpeg(frame) {
                 return this.decodeH264ToJpeg(Buffer.concat([
                     frame.header,
                     frame.data
                 ]));
             }
-            async waitForUsableKeyframe(timeoutMs) {
-                const deadline = Date.now() + timeoutMs;
-                let candidate = this.getCachedKeyframeCandidate();
-                while(true){
-                    if (candidate && this.isFrameAgeAcceptable(candidate.ptsUs)) return candidate;
-                    const remainingMs = deadline - Date.now();
-                    if (remainingMs <= 0) throw new Error(`No fresh keyframe received within ${timeoutMs}ms`);
-                    candidate = await this.waitForNextKeyframe(remainingMs);
-                }
-            }
             async prepareFreshFrame() {
                 await this.ensureConnected();
                 await this.ensureFrameClockCalibration();
                 await this.waitForKeyframe();
-                await this.waitForUsableKeyframe(MAX_KEYFRAME_WAIT_MS);
+                await this.waitForPlanningFrame();
             }
             async waitForPlanningFrame() {
                 let planningBarrierArmed = false;
-                let deadline = Date.now() + FRESH_FRAME_TIMEOUT_MS;
+                const planningStartedAt = Date.now();
+                const startupWindowRemainingMs = this.streamBaselineFramePending ? this.streamBaselineFrameDeadlineAt - planningStartedAt : 0;
+                if (this.streamBaselineFramePending && startupWindowRemainingMs <= 0) {
+                    this.streamBaselineFramePending = false;
+                    this.streamBaselineFrameDeadlineAt = 0;
+                }
+                let deadline = planningStartedAt + (startupWindowRemainingMs > 0 ? startupWindowRemainingMs : FRESH_FRAME_TIMEOUT_MS);
                 let candidate = this.getCachedKeyframeCandidate();
                 while(true){
                     if (candidate) {
                         if (void 0 === candidate.ptsUs) throw new Error('Scrcpy frame has no PTS metadata; cannot prove planning freshness');
+                        if (this.canReuseFrameAcrossActionWait(candidate)) {
+                            debugScrcpy(`Using frame PTS ${candidate.ptsUs}µs that crossed the active input-action barrier; preserving the settled frame across wait-after-action`);
+                            return candidate;
+                        }
+                        if (this.canUseStreamBaseline(candidate)) {
+                            debugScrcpy(`Using frame PTS ${candidate.ptsUs}µs as the first planning baseline for the new scrcpy stream epoch`);
+                            return candidate;
+                        }
                         const age = this.estimateFrameAge(candidate.ptsUs);
                         if (null === age) throw new Error('Scrcpy frame clock is not calibrated; cannot prove planning freshness');
                         if (age.upperBoundUs <= MAX_FRAME_AGE_US) return candidate;
@@ -578,11 +624,12 @@ var __webpack_modules__ = {
                 }
             }
             async closeStaleStreamAndCreateFallbackError(error) {
-                this.warnTransportBacklog(error);
+                const diagnosticMessage = this.transportBacklogMessage(error);
                 const causeMessage = error instanceof Error ? error.message : String(error);
                 await this.disconnect();
-                return new ScrcpyFreshFrameUnavailableError(`Unable to obtain a fresh scrcpy frame; the stale stream epoch was closed so the caller can use ADB screenshot fallback. ${causeMessage}`, {
-                    cause: error
+                return new ScrcpyFreshFrameUnavailableError(`Unable to obtain a fresh scrcpy frame; the stale stream epoch was closed so the caller can restart it or use ADB screenshot fallback. ${causeMessage}`, {
+                    cause: error,
+                    diagnosticMessage
                 });
             }
             async getScreenshotJpeg() {
@@ -609,6 +656,9 @@ var __webpack_modules__ = {
                 const t5 = Date.now();
                 const result = await this.decodeH264ToJpeg(keyframeBuffer);
                 const decodeTime = Date.now() - t5;
+                this.consumeActionFreshnessBarrier(frame);
+                this.streamBaselineFramePending = false;
+                this.streamBaselineFrameDeadlineAt = 0;
                 const totalTime = Date.now() - perfStart;
                 debugScrcpy(`Performance: total=${totalTime}ms (connect=${connectTime}ms, frameWait=${frameWaitTime}ms, decode=${decodeTime}ms)`);
                 return result;
@@ -765,6 +815,13 @@ var __webpack_modules__ = {
                 }
                 debugScrcpy('Scrcpy disconnected');
             }
+            async dispose() {
+                if (this.disposed) return;
+                this.disposed = true;
+                if (this.connectionPromise) await this.connectionPromise.catch(()=>{});
+                await this.disconnect();
+                await this.adb.close();
+            }
             isConnected() {
                 return this.isInitialized && null !== this.scrcpyClient;
             }
@@ -774,7 +831,8 @@ var __webpack_modules__ = {
                 _define_property(this, "videoStream", null);
                 _define_property(this, "spsHeader", null);
                 _define_property(this, "idleTimer", null);
-                _define_property(this, "isConnecting", false);
+                _define_property(this, "connectionPromise", null);
+                _define_property(this, "disposed", false);
                 _define_property(this, "isInitialized", false);
                 _define_property(this, "options", void 0);
                 _define_property(this, "ffmpegAvailable", null);
@@ -788,6 +846,9 @@ var __webpack_modules__ = {
                 _define_property(this, "streamReader", null);
                 _define_property(this, "frameFreshnessBarrierPtsUs", null);
                 _define_property(this, "frameFreshnessBarrierReason", null);
+                _define_property(this, "frameFreshnessBarrierAllowsOverAgeForNextCapture", false);
+                _define_property(this, "streamBaselineFramePending", false);
+                _define_property(this, "streamBaselineFrameDeadlineAt", 0);
                 _define_property(this, "frameFreshnessBarrierPending", false);
                 _define_property(this, "frameFreshnessBarrierGeneration", 0);
                 _define_property(this, "deviceClockCalibration", null);
@@ -927,6 +988,9 @@ function _define_property(obj, key, value) {
     return obj;
 }
 const debugAdapter = (0, logger_.getDebug)('android:scrcpy-adapter');
+const warnAdapter = (0, logger_.getDebug)('android:scrcpy-adapter', {
+    console: true
+});
 const SCRCPY_RETRY_COOLDOWN_MS = 5000;
 const DEFAULT_ADB_SERVER_ENDPOINT = {
     host: '127.0.0.1',
@@ -980,10 +1044,11 @@ class ScrcpyDeviceAdapter {
         if (null === this.retryAfter || Date.now() >= this.retryAfter) return;
         throw new Error(`scrcpy retry is cooling down until ${new Date(this.retryAfter).toISOString()}. Last error: ${this.lastError}`);
     }
-    resolveConfig(deviceInfo) {
+    resolveConfig(_deviceInfo) {
         if (this.resolvedConfig) return this.resolvedConfig;
         const config = this.scrcpyConfig;
         const maxSize = config?.maxSize ?? scrcpy_manager.ov.maxSize;
+        if (!Number.isInteger(maxSize) || maxSize < 0) throw new Error(`Invalid scrcpyConfig.maxSize: expected a non-negative integer, received ${maxSize}`);
         const videoBitRate = config?.videoBitRate ?? scrcpy_manager.ov.videoBitRate;
         this.resolvedConfig = {
             enabled: this.isConfigured(),
@@ -993,31 +1058,68 @@ class ScrcpyDeviceAdapter {
         };
         return this.resolvedConfig;
     }
+    async prepareFallbackScreenshot(screenshotBase64) {
+        if (!this.isConfigured()) return screenshotBase64;
+        const { maxSize } = this.resolveConfig();
+        if (0 === maxSize) return screenshotBase64;
+        const sourceSize = await imageInfoOfBase64(screenshotBase64);
+        const largestDimension = Math.max(sourceSize.width, sourceSize.height);
+        if (largestDimension <= maxSize) return screenshotBase64;
+        const scale = maxSize / largestDimension;
+        const targetSize = {
+            width: Math.max(1, Math.round(sourceSize.width * scale)),
+            height: Math.max(1, Math.round(sourceSize.height * scale))
+        };
+        debugAdapter(`Applying scrcpy maxSize to fallback screenshot: ${sourceSize.width}x${sourceSize.height} -> ${targetSize.width}x${targetSize.height}`);
+        return resizeBase64ImageToJpeg(screenshotBase64, {
+            sourceSize,
+            targetSize
+        });
+    }
     async ensureManager(deviceInfo) {
         if (this.manager) return this.manager;
+        if (this.managerPromise) return this.managerPromise;
         debugAdapter('Initializing Scrcpy manager...');
+        const generation = this.lifecycleGeneration;
+        const managerPromise = (async ()=>{
+            let adb = null;
+            let manager = null;
+            try {
+                const { Adb, AdbServerClient } = await import("@yume-chan/adb");
+                const { AdbServerNodeTcpConnector } = await import("@yume-chan/adb-server-node-tcp");
+                const { ScrcpyScreenshotManager: ScrcpyManager } = await Promise.resolve().then(__webpack_require__.bind(__webpack_require__, "./src/scrcpy-manager.ts"));
+                const adbServerEndpoint = await this.resolveAdbServerEndpoint();
+                const adbClient = new AdbServerClient(new AdbServerNodeTcpConnector(adbServerEndpoint));
+                adb = new Adb(await adbClient.createTransport({
+                    serial: this.deviceId
+                }));
+                const config = this.resolveConfig(deviceInfo);
+                manager = new ScrcpyManager(adb, {
+                    maxSize: config.maxSize,
+                    videoBitRate: config.videoBitRate,
+                    idleTimeoutMs: config.idleTimeoutMs
+                });
+                await manager.validateEnvironment();
+                if (generation !== this.lifecycleGeneration) throw new Error('Scrcpy manager initialization was superseded by device cleanup');
+                this.manager = manager;
+                debugAdapter('Scrcpy manager initialized');
+                return manager;
+            } catch (error) {
+                try {
+                    if (manager) await manager.dispose();
+                    else await adb?.close();
+                } catch (cleanupError) {
+                    debugAdapter(`Failed to clean up Scrcpy manager initialization: ${cleanupError}`);
+                }
+                debugAdapter(`Failed to initialize Scrcpy manager: ${error}`);
+                throw new Error(`Failed to initialize Scrcpy for device ${this.deviceId}. Ensure ADB server is running and device is connected. Error: ${error}`);
+            }
+        })();
+        this.managerPromise = managerPromise;
         try {
-            const { Adb, AdbServerClient } = await import("@yume-chan/adb");
-            const { AdbServerNodeTcpConnector } = await import("@yume-chan/adb-server-node-tcp");
-            const { ScrcpyScreenshotManager: ScrcpyManager } = await Promise.resolve().then(__webpack_require__.bind(__webpack_require__, "./src/scrcpy-manager.ts"));
-            const adbServerEndpoint = await this.resolveAdbServerEndpoint();
-            const adbClient = new AdbServerClient(new AdbServerNodeTcpConnector(adbServerEndpoint));
-            const adb = new Adb(await adbClient.createTransport({
-                serial: this.deviceId
-            }));
-            const config = this.resolveConfig(deviceInfo);
-            const manager = new ScrcpyManager(adb, {
-                maxSize: config.maxSize,
-                videoBitRate: config.videoBitRate,
-                idleTimeoutMs: config.idleTimeoutMs
-            });
-            await manager.validateEnvironment();
-            this.manager = manager;
-            debugAdapter('Scrcpy manager initialized');
-            return this.manager;
-        } catch (error) {
-            debugAdapter(`Failed to initialize Scrcpy manager: ${error}`);
-            throw new Error(`Failed to initialize Scrcpy for device ${this.deviceId}. Ensure ADB server is running and device is connected. Error: ${error}`);
+            return await managerPromise;
+        } finally{
+            if (this.managerPromise === managerPromise) this.managerPromise = null;
         }
     }
     async screenshotBase64(deviceInfo) {
@@ -1029,16 +1131,54 @@ class ScrcpyDeviceAdapter {
             await this.applyPendingActionBarrier(manager);
             const screenshotBuffer = await manager.getScreenshotJpeg();
             this.clearFailure();
-            return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
+            return this.jpegBufferToBase64(screenshotBuffer);
         } catch (error) {
-            if ((0, scrcpy_manager.GJ)(error)) {
-                this.markFreshnessRecoveryPending(manager, error);
+            if (!(0, scrcpy_manager.GJ)(error)) {
+                this.recordFailure(error);
                 throw error;
             }
-            this.recordFailure(error);
-            throw error;
+            this.markFreshnessRecoveryPending(error);
+            debugAdapter(`Scrcpy freshness target was unavailable; restarting the stream once before ADB fallback: ${error}`);
+            try {
+                const screenshotBuffer = await this.restartAndCaptureOnce(deviceInfo);
+                manager = this.manager;
+                if (!manager) throw new Error('Scrcpy manager disappeared after freshness recovery');
+                this.attachKeyframeListeners(manager);
+                this.clearFailure();
+                debugAdapter('Scrcpy screenshot recovered on a new stream epoch');
+                return this.jpegBufferToBase64(screenshotBuffer);
+            } catch (retryError) {
+                if ((0, scrcpy_manager.GJ)(retryError)) this.markFreshnessRecoveryPending(retryError);
+                else this.recordFailure(retryError);
+                this.warnFreshnessFallback(error, retryError);
+                throw retryError;
+            }
         }
     }
+    async restartAndCaptureOnce(deviceInfo) {
+        if (this.freshnessRestartPromise) return this.freshnessRestartPromise;
+        const generation = this.lifecycleGeneration;
+        const restartPromise = (async ()=>{
+            const manager = await this.ensureManager(deviceInfo);
+            await manager.ensureConnected();
+            await this.applyPendingActionBarrier(manager);
+            if (generation !== this.lifecycleGeneration) throw new Error('Scrcpy freshness restart was cancelled by cleanup');
+            return manager.getScreenshotJpeg();
+        })();
+        this.freshnessRestartPromise = restartPromise;
+        try {
+            return await restartPromise;
+        } finally{
+            if (this.freshnessRestartPromise === restartPromise) this.freshnessRestartPromise = null;
+        }
+    }
+    jpegBufferToBase64(screenshotBuffer) {
+        return createImgBase64ByFormat('jpeg', screenshotBuffer.toString('base64'));
+    }
+    warnFreshnessFallback(firstError, retryError) {
+        const retryDiagnostic = (0, scrcpy_manager.GJ)(retryError) ? retryError.diagnosticMessage : void 0;
+        warnAdapter(retryDiagnostic ?? (firstError.diagnosticMessage ? `${firstError.diagnosticMessage}\nScrcpy stream restart error: ${retryError}` : void 0) ?? `Scrcpy stream restart failed; falling back to ADB screenshot. Error: ${retryError}`);
+    }
     async subscribeKeyframes(deviceInfo, listener) {
         this.ensureRetryReady();
         this.keyframeListeners.add(listener);
@@ -1071,17 +1211,26 @@ class ScrcpyDeviceAdapter {
         this.keyframeUnsubscribers.clear();
         for (const listener of this.keyframeListeners)this.attachKeyframeListener(manager, listener);
     }
-    markFreshnessRecoveryPending(manager, error) {
+    markFreshnessRecoveryPending(error) {
         this.lastError = error.message;
         this.retryAfter = null;
         this.freshnessRecoveryPending = true;
         this.keyframeUnsubscribers.clear();
-        if (manager && this.manager === manager) this.manager = null;
     }
     async applyPendingActionBarrier(manager) {
-        if (!this.pendingActionBarrier) return;
-        await manager.setFreshnessBarrier('completed input action while scrcpy was unavailable');
-        this.pendingActionBarrier = false;
+        const actionCompletedAtHostUs = this.pendingActionBarrierAtHostUs;
+        if (null === actionCompletedAtHostUs) return;
+        await manager.setFreshnessBarrier('completed input action while scrcpy was unavailable', {
+            allowOverAgeForNextCapture: true,
+            hostMonotonicUs: actionCompletedAtHostUs
+        });
+        if (this.pendingActionBarrierAtHostUs === actionCompletedAtHostUs) this.pendingActionBarrierAtHostUs = null;
+    }
+    monotonicTimeUs() {
+        return process.hrtime.bigint() / 1000n;
+    }
+    deferActionBarrier(actionCompletedAtHostUs) {
+        if (null === this.pendingActionBarrierAtHostUs || actionCompletedAtHostUs > this.pendingActionBarrierAtHostUs) this.pendingActionBarrierAtHostUs = actionCompletedAtHostUs;
     }
     recoverAfterAdbScreenshot(deviceInfo) {
         if (!this.freshnessRecoveryPending || this.recoveryPromise) return;
@@ -1094,7 +1243,7 @@ class ScrcpyDeviceAdapter {
                 await this.applyPendingActionBarrier(manager);
                 await manager.prepareFreshFrame();
                 if (generation !== this.lifecycleGeneration) {
-                    await manager.disconnect();
+                    await manager.dispose();
                     if (this.manager === manager) this.manager = null;
                     return;
                 }
@@ -1103,7 +1252,7 @@ class ScrcpyDeviceAdapter {
                 debugAdapter('Scrcpy freshness recovery completed in background');
             } catch (error) {
                 if (manager) {
-                    await manager.disconnect();
+                    await manager.dispose();
                     if (this.manager === manager) this.manager = null;
                 }
                 this.freshnessRecoveryPending = false;
@@ -1118,21 +1267,22 @@ class ScrcpyDeviceAdapter {
         });
     }
     async markActionBarrier() {
+        const actionCompletedAtHostUs = this.monotonicTimeUs();
         const manager = this.manager;
-        if (!manager?.isConnected()) {
-            this.pendingActionBarrier = true;
-            return;
-        }
+        if (!manager?.isConnected()) return void this.deferActionBarrier(actionCompletedAtHostUs);
         try {
-            await manager.setFreshnessBarrier('completed input action');
-            this.pendingActionBarrier = false;
+            await manager.setFreshnessBarrier('completed input action', {
+                allowOverAgeForNextCapture: true,
+                hostMonotonicUs: actionCompletedAtHostUs
+            });
+            if (null !== this.pendingActionBarrierAtHostUs && this.pendingActionBarrierAtHostUs <= actionCompletedAtHostUs) this.pendingActionBarrierAtHostUs = null;
             this.clearFailure();
         } catch (error) {
-            this.pendingActionBarrier = true;
+            this.deferActionBarrier(actionCompletedAtHostUs);
             this.recordFailure(error);
             debugAdapter(`Unable to mark scrcpy action barrier; disabling this stream: ${error}`);
             try {
-                await manager.disconnect();
+                await manager.dispose();
             } catch (disconnectError) {
                 debugAdapter(`Error disconnecting scrcpy after barrier failure: ${disconnectError}`);
             } finally{
@@ -1165,14 +1315,16 @@ class ScrcpyDeviceAdapter {
     async disconnect() {
         this.lifecycleGeneration += 1;
         this.freshnessRecoveryPending = false;
-        this.pendingActionBarrier = false;
+        this.pendingActionBarrierAtHostUs = null;
         for (const unsubscribe of this.keyframeUnsubscribers.values())unsubscribe();
         this.keyframeUnsubscribers.clear();
         this.keyframeListeners.clear();
         if (this.recoveryPromise) await this.recoveryPromise.catch(()=>{});
+        if (this.freshnessRestartPromise) await this.freshnessRestartPromise.catch(()=>{});
+        if (this.managerPromise) await this.managerPromise.catch(()=>{});
         if (this.manager) {
             try {
-                await this.manager.disconnect();
+                await this.manager.dispose();
             } catch (error) {
                 debugAdapter(`Error disconnecting scrcpy: ${error}`);
             }
@@ -1186,26 +1338,30 @@ class ScrcpyDeviceAdapter {
         _define_property(this, "scrcpyConfig", void 0);
         _define_property(this, "resolveAdbServerEndpoint", void 0);
         _define_property(this, "manager", void 0);
+        _define_property(this, "managerPromise", void 0);
         _define_property(this, "resolvedConfig", void 0);
         _define_property(this, "lastError", void 0);
         _define_property(this, "retryAfter", void 0);
         _define_property(this, "freshnessRecoveryPending", void 0);
+        _define_property(this, "freshnessRestartPromise", void 0);
         _define_property(this, "recoveryPromise", void 0);
         _define_property(this, "lifecycleGeneration", void 0);
-        _define_property(this, "pendingActionBarrier", void 0);
+        _define_property(this, "pendingActionBarrierAtHostUs", void 0);
         _define_property(this, "keyframeListeners", void 0);
         _define_property(this, "keyframeUnsubscribers", void 0);
         this.deviceId = deviceId;
         this.scrcpyConfig = scrcpyConfig;
         this.resolveAdbServerEndpoint = resolveAdbServerEndpoint;
         this.manager = null;
+        this.managerPromise = null;
         this.resolvedConfig = null;
         this.lastError = null;
         this.retryAfter = null;
         this.freshnessRecoveryPending = false;
+        this.freshnessRestartPromise = null;
         this.recoveryPromise = null;
         this.lifecycleGeneration = 0;
-        this.pendingActionBarrier = false;
+        this.pendingActionBarrierAtHostUs = null;
         this.keyframeListeners = new Set();
         this.keyframeUnsubscribers = new Map();
     }
@@ -2056,9 +2212,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     }
     async screenshotBase64() {
         debugDevice('screenshotBase64 begin');
-        const screenshotStrategy = this.options?.screenshotStrategy || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_SCREENSHOT_STRATEGY) || SCREENSHOT_STRATEGY_AUTO;
-        if (screenshotStrategy === SCREENSHOT_STRATEGY_ALWAYS_YADB) return this.screenshotBase64ViaYadb();
         const adapter = this.getScrcpyAdapter();
+        const screenshotStrategy = this.options?.screenshotStrategy || globalConfigManager.getEnvConfigValue(MIDSCENE_ANDROID_SCREENSHOT_STRATEGY) || SCREENSHOT_STRATEGY_AUTO;
+        if (screenshotStrategy === SCREENSHOT_STRATEGY_ALWAYS_YADB) return adapter.prepareFallbackScreenshot(await this.screenshotBase64ViaYadb());
         let scrcpyDeviceInfo = null;
         if (adapter.isEnabled()) try {
             debugDevice('Attempting scrcpy screenshot...');
@@ -2067,7 +2223,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             debugDevice('screenshotBase64 end (scrcpy mode)');
             return result;
         } catch (error) {
-            warnDevice(`Scrcpy screenshot failed, falling back to standard ADB method. This may be caused by transport backlog. ${scrcpy_manager.Xr}\nError: ${error}`);
+            warnDevice(`Scrcpy screenshot failed, falling back to standard ADB method.\nError: ${error}`);
         }
         const adb = await this.getAdb();
         let screenshotBuffer;
@@ -2109,14 +2265,14 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
             });
             debugDevice('screenshotBase64 end (fallback)');
             if (scrcpyDeviceInfo) adapter.recoverAfterAdbScreenshot(scrcpyDeviceInfo);
-            return result;
+            return adapter.prepareFallbackScreenshot(result);
         }
         if (!screenshotBuffer) throw new Error('Failed to capture screenshot: all methods failed');
         debugDevice('Converting to base64');
         const result = createImgBase64ByFormat('png', screenshotBuffer.toString('base64'));
         debugDevice('screenshotBase64 end');
         if (scrcpyDeviceInfo) adapter.recoverAfterAdbScreenshot(scrcpyDeviceInfo);
-        return result;
+        return adapter.prepareFallbackScreenshot(result);
     }
     async captureScreenshotBase64FromDeviceFile(label, capture) {
         const adb = await this.getAdb();
@@ -3134,12 +3290,18 @@ function agent_tools_define_property(obj, key, value) {
 const debug = (0, logger_.getDebug)('agent-tools:android');
 function adaptAndroidInitArgs(extracted) {
     if (!extracted) return;
+    const scrcpyVideoBitRate = 'number' == typeof extracted.scrcpyVideoBitRate ? extracted.scrcpyVideoBitRate : void 0;
+    const requestedUseScrcpy = 'boolean' == typeof extracted.useScrcpy ? extracted.useScrcpy : void 0;
+    const useScrcpy = void 0 !== scrcpyVideoBitRate ? true : requestedUseScrcpy;
     const initArgs = {
         ...'string' == typeof extracted.deviceId ? {
             deviceId: extracted.deviceId
         } : {},
-        ...'boolean' == typeof extracted.useScrcpy ? {
-            useScrcpy: extracted.useScrcpy
+        ...void 0 !== useScrcpy ? {
+            useScrcpy
+        } : {},
+        ...void 0 !== scrcpyVideoBitRate ? {
+            scrcpyVideoBitRate
         } : {},
         ...extractAgentBehaviorInitArgs(extracted) ?? {}
     };
@@ -3171,7 +3333,10 @@ class AndroidMidsceneTools extends BaseMidsceneTools {
             ...extractAgentBehaviorInitArgs(initArgs) ?? {},
             ...initArgs?.useScrcpy ? {
                 scrcpyConfig: {
-                    enabled: true
+                    enabled: true,
+                    ...void 0 !== initArgs.scrcpyVideoBitRate ? {
+                        videoBitRate: initArgs.scrcpyVideoBitRate
+                    } : {}
                 }
             } : {},
             ...reportOptions ?? {}
@@ -3229,6 +3394,7 @@ class AndroidMidsceneTools extends BaseMidsceneTools {
             shape: {
                 deviceId: z.string().optional().describe('Android device ID (from adb devices)'),
                 useScrcpy: z.boolean().optional().describe('Enable scrcpy accelerated screenshots'),
+                scrcpyVideoBitRate: z.number().int().positive().optional().describe('scrcpy H.264 video bitrate in bits per second; providing this option also enables scrcpy. Default with --use-scrcpy: 100000000 (100 Mbps). For constrained remote links, start with 4000000 (4 Mbps).'),
                 ...agentBehaviorInitArgShape
             },
             cli: {