@midscene/android 1.12.0 → 1.12.1-beta-20260824081858.0

package/dist/lib/cli.js

@@ -17,7 +17,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");
@@ -52,7 +51,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;
@@ -62,7 +60,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;
@@ -76,8 +79,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) {
@@ -110,26 +114,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");
@@ -149,6 +157,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;
@@ -161,8 +171,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() {
@@ -347,24 +355,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) {
@@ -385,6 +399,7 @@ var __webpack_modules__ = {
                         this.frameFreshnessBarrierPending = true;
                         this.frameFreshnessBarrierPtsUs = null;
                         this.frameFreshnessBarrierReason = null;
+                        this.frameFreshnessBarrierAllowsOverAgeForNextCapture = false;
                         this.deviceClockCalibration = null;
                         this.clearFrameCache();
                         this.warnFrameFreshness();
@@ -406,7 +421,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()) {
@@ -456,13 +471,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) {
@@ -484,12 +504,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;
@@ -521,35 +550,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;
@@ -567,11 +613,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() {
@@ -598,6 +645,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;
@@ -754,6 +804,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;
             }
@@ -763,7 +820,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);
@@ -777,6 +835,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);
@@ -1039,6 +1100,9 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         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',
@@ -1092,10 +1156,11 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             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(),
@@ -1105,31 +1170,68 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             };
             return this.resolvedConfig;
         }
+        async prepareFallbackScreenshot(screenshotBase64) {
+            if (!this.isConfigured()) return screenshotBase64;
+            const { maxSize } = this.resolveConfig();
+            if (0 === maxSize) return screenshotBase64;
+            const sourceSize = await (0, img_namespaceObject.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 (0, img_namespaceObject.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) {
@@ -1141,16 +1243,54 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                 await this.applyPendingActionBarrier(manager);
                 const screenshotBuffer = await manager.getScreenshotJpeg();
                 this.clearFailure();
-                return (0, img_namespaceObject.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 (0, img_namespaceObject.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);
@@ -1183,17 +1323,26 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             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;
@@ -1206,7 +1355,7 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                     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;
                     }
@@ -1215,7 +1364,7 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
                     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;
@@ -1230,21 +1379,22 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             });
         }
         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{
@@ -1277,14 +1427,16 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
         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}`);
                 }
@@ -1298,26 +1450,30 @@ ${stdout ? truncateAdbShellStream(stdout, 'stdout') : EMPTY_ADB_SHELL_STDOUT}`;
             _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();
         }
@@ -2168,9 +2324,9 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
         }
         async screenshotBase64() {
             debugDevice('screenshotBase64 begin');
-            const screenshotStrategy = this.options?.screenshotStrategy || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.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 || env_namespaceObject.globalConfigManager.getEnvConfigValue(env_namespaceObject.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...');
@@ -2179,7 +2335,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;
@@ -2221,14 +2377,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 = (0, img_namespaceObject.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();
@@ -3082,12 +3238,18 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     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
             } : {},
             ...(0, agent_behavior_init_args_namespaceObject.extractAgentBehaviorInitArgs)(extracted) ?? {}
         };
@@ -3119,7 +3281,10 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 ...(0, agent_behavior_init_args_namespaceObject.extractAgentBehaviorInitArgs)(initArgs) ?? {},
                 ...initArgs?.useScrcpy ? {
                     scrcpyConfig: {
-                        enabled: true
+                        enabled: true,
+                        ...void 0 !== initArgs.scrcpyVideoBitRate ? {
+                            videoBitRate: initArgs.scrcpyVideoBitRate
+                        } : {}
                     }
                 } : {},
                 ...reportOptions ?? {}
@@ -3177,6 +3342,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
                 shape: {
                     deviceId: core_namespaceObject.z.string().optional().describe('Android device ID (from adb devices)'),
                     useScrcpy: core_namespaceObject.z.boolean().optional().describe('Enable scrcpy accelerated screenshots'),
+                    scrcpyVideoBitRate: core_namespaceObject.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).'),
                     ...agent_behavior_init_args_namespaceObject.agentBehaviorInitArgShape
                 },
                 cli: {
@@ -3189,7 +3355,7 @@ ${Object.keys(size).filter((key)=>size[key]).map((key)=>`  ${key} size: ${size[k
     const tools = new AndroidMidsceneTools();
     (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-android', {
         stripPrefix: 'android_',
-        version: "1.12.0",
+        version: "1.12.1-beta-20260824081858.0",
         extraCommands: (0, core_namespaceObject.createReportCliCommands)()
     }).catch((e)=>{
         process.exit((0, cli_namespaceObject.reportCLIError)(e));