Fix wedged browser automation recovery

CLI/cmux.swift

@@ -13997,7 +13997,12 @@ struct CMUXCLI {
             let (outPathOpt, _) = parseOption(subArgs, name: "--out")
             let localJSONOutput = hasFlag(subArgs, name: "--json")
             let outputAsJSON = effectiveJSONOutput || localJSONOutput
-            var payload = try client.sendV2(method: "browser.screenshot", params: ["surface_id": sid])
+            // Leave room beyond the app's capture deadline for its liveness probe and recovery reply.
+            var payload = try client.sendV2(
+                method: "browser.screenshot",
+                params: ["surface_id": sid],
+                responseTimeout: 25
+            )
 
             func fileURL(fromPath rawPath: String) -> URL {
                 let resolvedPath = resolvePath(rawPath)

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/Control/BrowserAutomationRecoveryOutcome.swift

@@ -0,0 +1,14 @@
+/// Result of checking whether a browser automation callback pipeline is alive.
+public enum BrowserAutomationRecoveryOutcome: Sendable, Equatable {
+    /// The liveness callback arrived before the deadline, so the current WebView remains authoritative.
+    case responsive
+
+    /// The callback missed its deadline and the owning browser surface replaced the unresponsive WebView.
+    case recovered
+
+    /// The callback missed its deadline, but another lifecycle path had already replaced the observed WebView.
+    case superseded
+
+    /// The check was cancelled before liveness or timeout produced an outcome.
+    case cancelled
+}

Packages/macOS/CmuxBrowser/Sources/CmuxBrowser/Control/BrowserAutomationWatchdog.swift

@@ -0,0 +1,92 @@
+import Foundation
+
+/// Applies one bounded liveness deadline before asking a browser surface to replace an unresponsive WebView.
+///
+/// The watchdog owns no WebKit state. Its caller supplies the callback-based liveness probe and the
+/// synchronous recovery mutation, keeping the package testable without launching AppKit or WebKit.
+/// A completed probe always wins over recovery, while a missing callback reaches the injected deadline.
+@MainActor
+public final class BrowserAutomationWatchdog {
+    /// Starts a liveness probe and invokes its completion when the browser automation pipeline responds.
+    public typealias Probe = @MainActor (
+        _ completion: @escaping @MainActor @Sendable () -> Void
+    ) -> Void
+
+    /// Replaces the observed WebView, returning `false` when another lifecycle path already superseded it.
+    public typealias Recovery = @MainActor () -> Bool
+
+    /// Cancellable timing source used for the liveness deadline.
+    public typealias Sleep = @Sendable (_ duration: Duration) async throws -> Void
+
+    private enum ProbeSignal: Sendable {
+        case responsive
+        case timedOut
+        case cancelled
+    }
+
+    private let probeTimeout: Duration
+    private let sleep: Sleep
+
+    /// Creates a browser automation watchdog.
+    /// - Parameters:
+    ///   - probeTimeout: Maximum time to wait for a liveness callback before recovery. Defaults to one second.
+    ///   - sleep: Cancellable timing source. Tests can inject an immediate or controlled deadline.
+    public init(
+        probeTimeout: Duration = .seconds(1),
+        sleep: @escaping Sleep = { try await ContinuousClock().sleep(for: $0) }
+    ) {
+        self.probeTimeout = probeTimeout
+        self.sleep = sleep
+    }
+
+    /// Probes the browser automation pipeline once and recovers only when that callback misses its deadline.
+    /// - Parameters:
+    ///   - probe: Starts a cheap, side-effect-free liveness operation.
+    ///   - recover: Replaces the WebView if it is still the instance observed by the failed operation.
+    /// - Returns: The liveness or recovery outcome.
+    public func recoverIfUnresponsive(
+        probe: Probe,
+        recover: Recovery
+    ) async -> BrowserAutomationRecoveryOutcome {
+        guard !Task.isCancelled else { return .cancelled }
+
+        let (signals, continuation) = AsyncStream.makeStream(
+            of: ProbeSignal.self,
+            bufferingPolicy: .bufferingOldest(1)
+        )
+        probe {
+            continuation.yield(.responsive)
+            continuation.finish()
+        }
+
+        let signal = await withTaskGroup(of: ProbeSignal.self, returning: ProbeSignal.self) { group in
+            group.addTask {
+                var iterator = signals.makeAsyncIterator()
+                return await iterator.next() ?? .cancelled
+            }
+            group.addTask { [probeTimeout, sleep] in
+                do {
+                    try await sleep(probeTimeout)
+                } catch {
+                    return .cancelled
+                }
+                return Task.isCancelled ? .cancelled : .timedOut
+            }
+
+            let first = await group.next() ?? .cancelled
+            group.cancelAll()
+            continuation.finish()
+            return first
+        }
+
+        guard !Task.isCancelled else { return .cancelled }
+        switch signal {
+        case .responsive:
+            return .responsive
+        case .timedOut:
+            return recover() ? .recovered : .superseded
+        case .cancelled:
+            return .cancelled
+        }
+    }
+}

Packages/macOS/CmuxBrowser/Tests/CmuxBrowserTests/Control/BrowserAutomationWatchdogTests.swift

@@ -0,0 +1,62 @@
+import Testing
+
+@testable import CmuxBrowser
+
+@MainActor
+@Suite("Browser automation watchdog")
+struct BrowserAutomationWatchdogTests {
+    @Test("A completed liveness probe preserves the current browser process")
+    func responsiveProbeDoesNotRecover() async {
+        var recoveryCount = 0
+        let watchdog = BrowserAutomationWatchdog(
+            sleep: { duration in
+                try await ContinuousClock().sleep(for: duration)
+            }
+        )
+
+        let outcome = await watchdog.recoverIfUnresponsive(
+            probe: { finish in finish() },
+            recover: {
+                recoveryCount += 1
+                return true
+            }
+        )
+
+        #expect(outcome == .responsive)
+        #expect(recoveryCount == 0)
+    }
+
+    @Test("A missing liveness callback replaces the unresponsive browser process")
+    func timedOutProbeRecovers() async {
+        var recoveryCount = 0
+        let watchdog = BrowserAutomationWatchdog(sleep: { _ in })
+
+        let outcome = await watchdog.recoverIfUnresponsive(
+            probe: { _ in },
+            recover: {
+                recoveryCount += 1
+                return true
+            }
+        )
+
+        #expect(outcome == .recovered)
+        #expect(recoveryCount == 1)
+    }
+
+    @Test("A WebView replaced during the probe is not replaced a second time")
+    func supersededProbeDoesNotRecoverAgain() async {
+        var recoveryCount = 0
+        let watchdog = BrowserAutomationWatchdog(sleep: { _ in })
+
+        let outcome = await watchdog.recoverIfUnresponsive(
+            probe: { _ in },
+            recover: {
+                recoveryCount += 1
+                return false
+            }
+        )
+
+        #expect(outcome == .superseded)
+        #expect(recoveryCount == 1)
+    }
+}