Merge pull request #960 from kkarimi/fix/mac-node-bridge-tunnel-865

macOS: prefer bridge tunnel port in remote mode
2026-01-16 02:00:23 +00:00
parent 7c38b535f6 747277d914
commit 409e33d9c2
53 changed files with 409 additions and 345 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -86,7 +86,28 @@
 - UI: use application-defined WebSocket close code (browser compatibility). (#918) — thanks @rahthakor.
 - TUI: render picker overlays via the overlay stack so /models and /settings display. (#921) — thanks @grizzdank.
 - TUI: add a bright spinner + elapsed time in the status line for send/stream/run states.
+- TUI: show LLM error messages (rate limits, auth, etc.) instead of `(no output)`.
 - Gateway/Dev: ensure `pnpm gateway:dev` always uses the dev profile config + state (`~/.clawdbot-dev`).
+
+#### Agents / Auth / Tools / Sandbox
+- Agents: make user time zone and 24-hour time explicit in the system prompt. (#859) — thanks @CashWilliams.
+- Agents: strip downgraded tool call text without eating adjacent replies and filter thinking-tag leaks. (#905) — thanks @erikpr1994.
+- Agents: cap tool call IDs for OpenAI/OpenRouter to avoid request rejections. (#875) — thanks @j1philli.
+- Agents: scrub tuple `items` schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.
+- Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.
+- Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.
+- Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.
+- Logging: tolerate `EIO` from console writes to avoid gateway crashes. (#925, fixes #878) — thanks @grp06.
+- Sandbox: restore `docker.binds` config validation and preserve configured PATH for `docker exec`. (#873) — thanks @akonyer.
+- Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.
+
+#### macOS / Apps
+- macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.
+- macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75.
+- macOS: pass auth token/password to dashboard URL for authenticated access. (#918) — thanks @rahthakor.
+- macOS: reuse launchd gateway auth and skip wizard when gateway config already exists. (#917)
+- macOS: prefer the default bridge tunnel port in remote mode for node bridge connectivity; document macOS remote control + bridge tunnels. (#960, fixes #865) — thanks @kkarimi.
+- Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare `main` sessions.
 - macOS: fix cron preview/testing payload to use `channel` key. (#867) — thanks @wes-davis.
 - Telegram: honor `channels.telegram.timeoutSeconds` for grammY API requests. (#863) — thanks @Snaver.
 - Telegram: split long captions into media + follow-up text messages. (#907) - thanks @jalehman.
--- a/apps/macos/Sources/Clawdbot/AgentWorkspace.swift
+++ b/apps/macos/Sources/Clawdbot/AgentWorkspace.swift
@@ -307,8 +307,8 @@ enum AgentWorkspace {
        }
        let cwd = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
        urls.append(cwd.appendingPathComponent("docs")
-                        .appendingPathComponent(self.templateDirname)
-                        .appendingPathComponent(named))
+            .appendingPathComponent(self.templateDirname)
+            .appendingPathComponent(named))
        return urls
    }

--- a/apps/macos/Sources/Clawdbot/AnthropicAuthControls.swift
+++ b/apps/macos/Sources/Clawdbot/AnthropicAuthControls.swift
@@ -109,8 +109,8 @@ struct AnthropicAuthControls: View {
                    }
                    .buttonStyle(.bordered)
                    .disabled(self.busy || self.connectionMode != .local || self.code
-                                .trimmingCharacters(in: .whitespacesAndNewlines)
-                                .isEmpty)
+                        .trimmingCharacters(in: .whitespacesAndNewlines)
+                        .isEmpty)
                }
            }

--- a/apps/macos/Sources/Clawdbot/AnthropicOAuth.swift
+++ b/apps/macos/Sources/Clawdbot/AnthropicOAuth.swift
@@ -228,7 +228,7 @@ enum ClawdbotOAuthStore {
    static func oauthDir() -> URL {
        if let override = ProcessInfo.processInfo.environment[self.clawdbotOAuthDirEnv]?
            .trimmingCharacters(in: .whitespacesAndNewlines),
-           !override.isEmpty
+            !override.isEmpty
        {
            let expanded = NSString(string: override).expandingTildeInPath
            return URL(fileURLWithPath: expanded, isDirectory: true)
--- a/apps/macos/Sources/Clawdbot/AppState.swift
+++ b/apps/macos/Sources/Clawdbot/AppState.swift
@@ -264,8 +264,8 @@ final class AppState {
        }
        let configRemoteUrl = (configGateway?["remote"] as? [String: Any])?["url"] as? String
        let configHasRemoteUrl = !(configRemoteUrl?
-                                    .trimmingCharacters(in: .whitespacesAndNewlines)
-                                    .isEmpty ?? true)
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .isEmpty ?? true)

        let storedMode = UserDefaults.standard.string(forKey: connectionModeKey)
        let resolvedConnectionMode: ConnectionMode = if let configMode {
@@ -356,8 +356,8 @@ final class AppState {
        let modeRaw = (gateway?["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
        let remoteUrl = (gateway?["remote"] as? [String: Any])?["url"] as? String
        let hasRemoteUrl = !(remoteUrl?
-                                .trimmingCharacters(in: .whitespacesAndNewlines)
-                                .isEmpty ?? true)
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .isEmpty ?? true)

        let desiredMode: ConnectionMode? = switch modeRaw {
        case "local":
--- a/apps/macos/Sources/Clawdbot/Bridge/BridgeServer.swift
+++ b/apps/macos/Sources/Clawdbot/Bridge/BridgeServer.swift
@@ -182,12 +182,12 @@ actor BridgeServer {
                ?? "main"

            _ = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
-                                                            message: text,
-                                                            sessionKey: sessionKey,
-                                                            thinking: "low",
-                                                            deliver: false,
-                                                            to: nil,
-                                                            channel: .last))
+                message: text,
+                sessionKey: sessionKey,
+                thinking: "low",
+                deliver: false,
+                to: nil,
+                channel: .last))

        case "agent.request":
            guard let json = evt.payloadJSON, let data = json.data(using: .utf8) else {
@@ -208,12 +208,12 @@ actor BridgeServer {
            let channel = GatewayAgentChannel(raw: link.channel)

            _ = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
-                                                            message: message,
-                                                            sessionKey: sessionKey,
-                                                            thinking: thinking,
-                                                            deliver: link.deliver,
-                                                            to: to,
-                                                            channel: channel))
+                message: message,
+                sessionKey: sessionKey,
+                thinking: thinking,
+                deliver: link.deliver,
+                to: to,
+                channel: channel))

        default:
            break
--- a/apps/macos/Sources/Clawdbot/CanvasA2UIActionMessageHandler.swift
+++ b/apps/macos/Sources/Clawdbot/CanvasA2UIActionMessageHandler.swift
@@ -55,7 +55,7 @@ final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
        guard let name = ClawdbotCanvasA2UIAction.extractActionName(userAction) else { return }
        let actionId =
            (userAction["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
-            ?? UUID().uuidString
+                ?? UUID().uuidString

        canvasWindowLogger.info("A2UI action \(name, privacy: .public) session=\(self.sessionKey, privacy: .public)")

--- a/apps/macos/Sources/Clawdbot/CanvasFileWatcher.swift
+++ b/apps/macos/Sources/Clawdbot/CanvasFileWatcher.swift
@@ -39,13 +39,13 @@ final class CanvasFileWatcher: @unchecked Sendable {
                kFSEventStreamCreateFlagNoDefer)

        guard let stream = FSEventStreamCreate(
-                kCFAllocatorDefault,
-                Self.callback,
-                &context,
-                paths,
-                FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
-                0.05,
-                flags)
+            kCFAllocatorDefault,
+            Self.callback,
+            &context,
+            paths,
+            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+            0.05,
+            flags)
        else {
            retainedSelf.release()
            return
--- a/apps/macos/Sources/Clawdbot/CanvasWindowController.swift
+++ b/apps/macos/Sources/Clawdbot/CanvasWindowController.swift
@@ -242,8 +242,8 @@ final class CanvasWindowController: NSWindowController, WKNavigationDelegate, NS
        }

        guard let url = CanvasScheme.makeURL(
-                session: CanvasWindowController.sanitizeSessionKey(self.sessionKey),
-                path: trimmed)
+            session: CanvasWindowController.sanitizeSessionKey(self.sessionKey),
+            path: trimmed)
        else {
            canvasWindowLogger
                .error(
--- a/apps/macos/Sources/Clawdbot/CommandResolver.swift
+++ b/apps/macos/Sources/Clawdbot/CommandResolver.swift
@@ -125,13 +125,13 @@ enum CommandResolver {

        // fnm
        bins.append(contentsOf: self.versionedNodeBinPaths(
-                        base: home.appendingPathComponent(".local/share/fnm/node-versions"),
-                        suffix: "installation/bin"))
+            base: home.appendingPathComponent(".local/share/fnm/node-versions"),
+            suffix: "installation/bin"))

        // nvm
        bins.append(contentsOf: self.versionedNodeBinPaths(
-                        base: home.appendingPathComponent(".nvm/versions/node"),
-                        suffix: "bin"))
+            base: home.appendingPathComponent(".nvm/versions/node"),
+            suffix: "bin"))

        return bins
    }
--- a/apps/macos/Sources/Clawdbot/ConfigFileWatcher.swift
+++ b/apps/macos/Sources/Clawdbot/ConfigFileWatcher.swift
@@ -45,13 +45,13 @@ final class ConfigFileWatcher: @unchecked Sendable {
                kFSEventStreamCreateFlagNoDefer)

        guard let stream = FSEventStreamCreate(
-                kCFAllocatorDefault,
-                Self.callback,
-                &context,
-                paths,
-                FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
-                0.05,
-                flags)
+            kCFAllocatorDefault,
+            Self.callback,
+            &context,
+            paths,
+            FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+            0.05,
+            flags)
        else {
            retainedSelf.release()
            return
--- a/apps/macos/Sources/Clawdbot/ConfigSettings.swift
+++ b/apps/macos/Sources/Clawdbot/ConfigSettings.swift
@@ -10,7 +10,7 @@ struct ConfigSettings: View {
        "When enabled, the browser server will only connect if the clawd browser is already running."
    private static let browserProfileNote =
        "Clawd uses a separate Chrome profile and ports (default 18791/18792) "
-        + "so it won’t interfere with your daily browser."
+            + "so it won’t interfere with your daily browser."
    @State private var configModel: String = ""
    @State private var configSaving = false
    @State private var hasLoaded = false
@@ -97,8 +97,8 @@ extension ConfigSettings {
        Text("Clawdbot CLI config")
            .font(.title3.weight(.semibold))
        Text(self.isNixMode
-                ? "This tab is read-only in Nix mode. Edit config via Nix and rebuild."
-                : "Edit ~/.clawdbot/clawdbot.json (agent / session / routing / messages).")
+            ? "This tab is read-only in Nix mode. Edit config via Nix and rebuild."
+            : "Edit ~/.clawdbot/clawdbot.json (agent / session / routing / messages).")
            .font(.callout)
            .foregroundStyle(.secondary)
    }
@@ -753,9 +753,9 @@ extension ConfigSettings {
        do {
            let res: ModelsListResult =
                try await GatewayConnection.shared
-                .requestDecoded(
-                    method: .modelsList,
-                    timeoutMs: 15000)
+                    .requestDecoded(
+                        method: .modelsList,
+                        timeoutMs: 15000)
            self.models = res.models
            self.modelsSourceLabel = "gateway"
        } catch {
@@ -792,8 +792,8 @@ extension ConfigSettings {
                choice.provider,
                self.modelRef(for: choice),
            ]
-            .joined(separator: " ")
-            .lowercased()
+                .joined(separator: " ")
+                .lowercased()
            return tokens.allSatisfy { haystack.contains($0) }
        }
    }
--- a/apps/macos/Sources/Clawdbot/ConnectionModeCoordinator.swift
+++ b/apps/macos/Sources/Clawdbot/ConnectionModeCoordinator.swift
@@ -53,8 +53,8 @@ final class ConnectionModeCoordinator {
                _ = try await GatewayEndpointStore.shared.ensureRemoteControlTunnel()
                let settings = CommandResolver.connectionSettings()
                try await ControlChannel.shared.configure(mode: .remote(
-                                                            target: settings.target,
-                                                            identity: settings.identity))
+                    target: settings.target,
+                    identity: settings.identity))
            } catch {
                self.logger.error("remote tunnel/configure failed: \(error.localizedDescription, privacy: .public)")
            }
--- a/apps/macos/Sources/Clawdbot/ConnectionsSettings+ChannelState.swift
+++ b/apps/macos/Sources/Clawdbot/ConnectionsSettings+ChannelState.swift
@@ -377,18 +377,18 @@ extension ConnectionsSettings {
        case .telegram:
            return self
                .date(fromMs: self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)?
-                        .lastProbeAt)
+                    .lastProbeAt)
        case .discord:
            return self
                .date(fromMs: self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)?
-                        .lastProbeAt)
+                    .lastProbeAt)
        case .signal:
            return self
                .date(fromMs: self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)?.lastProbeAt)
        case .imessage:
            return self
                .date(fromMs: self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)?
-                        .lastProbeAt)
+                    .lastProbeAt)
        }
    }

--- a/apps/macos/Sources/Clawdbot/ConnectionsStore+Config.swift
+++ b/apps/macos/Sources/Clawdbot/ConnectionsStore+Config.swift
@@ -38,10 +38,10 @@ extension ConnectionsStore {
    private func applyUIConfig(_ snap: ConfigSnapshot) {
        let ui = snap.config?[
            "ui",
-            ]?.dictionaryValue
+        ]?.dictionaryValue
        let rawSeam = ui?[
            "seamColor",
-            ]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        ]?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
        AppStateStore.shared.seamColorHex = rawSeam.isEmpty ? nil : rawSeam
    }

--- a/apps/macos/Sources/Clawdbot/CritterIconRenderer.swift
+++ b/apps/macos/Sources/Clawdbot/CritterIconRenderer.swift
@@ -189,20 +189,20 @@ enum CritterIconRenderer {
        canvas.context.setFillColor(NSColor.labelColor.cgColor)

        canvas.context.addPath(CGPath(
-                                roundedRect: geometry.bodyRect,
-                                cornerWidth: geometry.bodyCorner,
-                                cornerHeight: geometry.bodyCorner,
-                                transform: nil))
+            roundedRect: geometry.bodyRect,
+            cornerWidth: geometry.bodyCorner,
+            cornerHeight: geometry.bodyCorner,
+            transform: nil))
        canvas.context.addPath(CGPath(
-                                roundedRect: geometry.leftEarRect,
-                                cornerWidth: geometry.earCorner,
-                                cornerHeight: geometry.earCorner,
-                                transform: nil))
+            roundedRect: geometry.leftEarRect,
+            cornerWidth: geometry.earCorner,
+            cornerHeight: geometry.earCorner,
+            transform: nil))
        canvas.context.addPath(CGPath(
-                                roundedRect: geometry.rightEarRect,
-                                cornerWidth: geometry.earCorner,
-                                cornerHeight: geometry.earCorner,
-                                transform: nil))
+            roundedRect: geometry.rightEarRect,
+            cornerWidth: geometry.earCorner,
+            cornerHeight: geometry.earCorner,
+            transform: nil))

        for i in 0..<4 {
            let x = geometry.legStartX + CGFloat(i) * (geometry.legW + geometry.legSpacing)
@@ -213,10 +213,10 @@ enum CritterIconRenderer {
                width: geometry.legW,
                height: geometry.legH * geometry.legHeightScale)
            canvas.context.addPath(CGPath(
-                                    roundedRect: rect,
-                                    cornerWidth: geometry.legW * 0.34,
-                                    cornerHeight: geometry.legW * 0.34,
-                                    transform: nil))
+                roundedRect: rect,
+                cornerWidth: geometry.legW * 0.34,
+                cornerHeight: geometry.legW * 0.34,
+                transform: nil))
        }
        canvas.context.fillPath()
    }
@@ -252,15 +252,15 @@ enum CritterIconRenderer {
                height: holeH)

            canvas.context.addPath(CGPath(
-                                    roundedRect: leftHoleRect,
-                                    cornerWidth: holeCorner,
-                                    cornerHeight: holeCorner,
-                                    transform: nil))
+                roundedRect: leftHoleRect,
+                cornerWidth: holeCorner,
+                cornerHeight: holeCorner,
+                transform: nil))
            canvas.context.addPath(CGPath(
-                                    roundedRect: rightHoleRect,
-                                    cornerWidth: holeCorner,
-                                    cornerHeight: holeCorner,
-                                    transform: nil))
+                roundedRect: rightHoleRect,
+                cornerWidth: holeCorner,
+                cornerHeight: holeCorner,
+                transform: nil))
        }

        if options.eyesClosedLines {
@@ -278,41 +278,41 @@ enum CritterIconRenderer {
                width: lineW,
                height: lineH)
            canvas.context.addPath(CGPath(
-                                    roundedRect: leftRect,
-                                    cornerWidth: corner,
-                                    cornerHeight: corner,
-                                    transform: nil))
+                roundedRect: leftRect,
+                cornerWidth: corner,
+                cornerHeight: corner,
+                transform: nil))
            canvas.context.addPath(CGPath(
-                                    roundedRect: rightRect,
-                                    cornerWidth: corner,
-                                    cornerHeight: corner,
-                                    transform: nil))
+                roundedRect: rightRect,
+                cornerWidth: corner,
+                cornerHeight: corner,
+                transform: nil))
        } else {
            let eyeOpen = max(0.05, 1 - options.blink)
            let eyeH = canvas.snapY(geometry.bodyRect.height * 0.26 * eyeOpen)

            let left = CGMutablePath()
            left.move(to: CGPoint(
-                        x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
-                        y: canvas.snapY(leftCenter.y - eyeH)))
+                x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y - eyeH)))
            left.addLine(to: CGPoint(
-                            x: canvas.snapX(leftCenter.x + geometry.eyeW / 2),
-                            y: canvas.snapY(leftCenter.y)))
+                x: canvas.snapX(leftCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y)))
            left.addLine(to: CGPoint(
-                            x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
-                            y: canvas.snapY(leftCenter.y + eyeH)))
+                x: canvas.snapX(leftCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(leftCenter.y + eyeH)))
            left.closeSubpath()

            let right = CGMutablePath()
            right.move(to: CGPoint(
-                        x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
-                        y: canvas.snapY(rightCenter.y - eyeH)))
+                x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y - eyeH)))
            right.addLine(to: CGPoint(
-                            x: canvas.snapX(rightCenter.x - geometry.eyeW / 2),
-                            y: canvas.snapY(rightCenter.y)))
+                x: canvas.snapX(rightCenter.x - geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y)))
            right.addLine(to: CGPoint(
-                            x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
-                            y: canvas.snapY(rightCenter.y + eyeH)))
+                x: canvas.snapX(rightCenter.x + geometry.eyeW / 2),
+                y: canvas.snapY(rightCenter.y + eyeH)))
            right.closeSubpath()

            canvas.context.addPath(left)
--- a/apps/macos/Sources/Clawdbot/CritterStatusLabel+Behavior.swift
+++ b/apps/macos/Sources/Clawdbot/CritterStatusLabel+Behavior.swift
@@ -121,12 +121,12 @@ extension CritterStatusLabel {
        }

        return Image(nsImage: CritterIconRenderer.makeIcon(
-                        blink: self.blinkAmount,
-                        legWiggle: max(self.legWiggle, self.isWorkingNow ? 0.6 : 0),
-                        earWiggle: self.earWiggle,
-                        earScale: self.earBoostActive ? 1.9 : 1.0,
-                        earHoles: self.earBoostActive,
-                        badge: badge))
+            blink: self.blinkAmount,
+            legWiggle: max(self.legWiggle, self.isWorkingNow ? 0.6 : 0),
+            earWiggle: self.earWiggle,
+            earScale: self.earBoostActive ? 1.9 : 1.0,
+            earHoles: self.earBoostActive,
+            badge: badge))
    }

    private func resetMotion() {
--- a/apps/macos/Sources/Clawdbot/CronJobEditor.swift
+++ b/apps/macos/Sources/Clawdbot/CronJobEditor.swift
@@ -11,15 +11,15 @@ struct CronJobEditor: View {
    let labelColumnWidth: CGFloat = 160
    static let introText =
        "Create a schedule that wakes clawd via the Gateway. "
-        + "Use an isolated session for agent turns so your main chat stays clean."
+            + "Use an isolated session for agent turns so your main chat stays clean."
    static let sessionTargetNote =
        "Main jobs post a system event into the current main session. "
-        + "Isolated jobs run clawd in a dedicated session and can deliver results (WhatsApp/Telegram/Discord/etc)."
+            + "Isolated jobs run clawd in a dedicated session and can deliver results (WhatsApp/Telegram/Discord/etc)."
    static let scheduleKindNote =
        "“At” runs once, “Every” repeats with a duration, “Cron” uses a 5-field Unix expression."
    static let isolatedPayloadNote =
        "Isolated jobs always run an agent turn. The result can be delivered to a channel, "
-        + "and a short summary is posted back to your main chat."
+            + "and a short summary is posted back to your main chat."
    static let mainPayloadNote =
        "System events are injected into the current main session. Agent turns require an isolated session target."
    static let mainSummaryNote =
--- a/apps/macos/Sources/Clawdbot/CronModels.swift
+++ b/apps/macos/Sources/Clawdbot/CronModels.swift
@@ -70,13 +70,13 @@ enum CronSchedule: Codable, Equatable {
 enum CronPayload: Codable, Equatable {
    case systemEvent(text: String)
    case agentTurn(
-            message: String,
-            thinking: String?,
-            timeoutSeconds: Int?,
-            deliver: Bool?,
-            channel: String?,
-            to: String?,
-            bestEffortDeliver: Bool?)
+        message: String,
+        thinking: String?,
+        timeoutSeconds: Int?,
+        deliver: Bool?,
+        channel: String?,
+        to: String?,
+        bestEffortDeliver: Bool?)

    enum CodingKeys: String, CodingKey {
        case kind, text, message, thinking, timeoutSeconds, deliver, channel, provider, to, bestEffortDeliver
--- a/apps/macos/Sources/Clawdbot/CronSettings+Layout.swift
+++ b/apps/macos/Sources/Clawdbot/CronSettings+Layout.swift
@@ -26,8 +26,8 @@ extension CronSettings {
                })
        }
        .alert("Delete cron job?", isPresented: Binding(
-                get: { self.confirmDelete != nil },
-                set: { if !$0 { self.confirmDelete = nil } }))
+            get: { self.confirmDelete != nil },
+            set: { if !$0 { self.confirmDelete = nil } }))
        {
            Button("Cancel", role: .cancel) { self.confirmDelete = nil }
            Button("Delete", role: .destructive) {
@@ -42,9 +42,9 @@ extension CronSettings {
            }
        }
        .onChange(of: self.store.selectedJobId) { _, newValue in
-            guard let newValue else { return }
-            Task { await self.store.refreshRuns(jobId: newValue) }
-        }
+                guard let newValue else { return }
+                Task { await self.store.refreshRuns(jobId: newValue) }
+            }
    }

    var schedulerBanner: some View {
--- a/apps/macos/Sources/Clawdbot/CronSettings+Rows.swift
+++ b/apps/macos/Sources/Clawdbot/CronSettings+Rows.swift
@@ -69,8 +69,8 @@ extension CronSettings {
            Spacer()
            HStack(spacing: 8) {
                Toggle("Enabled", isOn: Binding(
-                        get: { job.enabled },
-                        set: { enabled in Task { await self.store.setJobEnabled(id: job.id, enabled: enabled) } }))
+                    get: { job.enabled },
+                    set: { enabled in Task { await self.store.setJobEnabled(id: job.id, enabled: enabled) } }))
                    .toggleStyle(.switch)
                    .labelsHidden()
                Button("Run") { Task { await self.store.runJob(id: job.id, force: true) } }
--- a/apps/macos/Sources/Clawdbot/DebugActions.swift
+++ b/apps/macos/Sources/Clawdbot/DebugActions.swift
@@ -102,8 +102,8 @@ enum DebugActions {
                    _ = try await RemoteTunnelManager.shared.ensureControlTunnel()
                    let settings = CommandResolver.connectionSettings()
                    try await ControlChannel.shared.configure(mode: .remote(
-                                                                target: settings.target,
-                                                                identity: settings.identity))
+                        target: settings.target,
+                        identity: settings.identity))
                } catch {
                    // ControlChannel will surface a degraded state; also refresh health to update the menu text.
                    Task { await HealthStore.shared.refresh(onDemand: true) }
@@ -127,8 +127,8 @@ enum DebugActions {
            _ = try await RemoteTunnelManager.shared.ensureControlTunnel()
            let settings = CommandResolver.connectionSettings()
            try await ControlChannel.shared.configure(mode: .remote(
-                                                        target: settings.target,
-                                                        identity: settings.identity))
+                target: settings.target,
+                identity: settings.identity))
            await HealthStore.shared.refresh(onDemand: true)
            return .success("SSH tunnel reset.")
        } catch {
--- a/apps/macos/Sources/Clawdbot/DeviceModelCatalog.swift
+++ b/apps/macos/Sources/Clawdbot/DeviceModelCatalog.swift
@@ -107,9 +107,9 @@ enum DeviceModelCatalog {

    private static func loadMapping(resourceName: String) -> [String: String] {
        guard let url = self.resourceBundle?.url(
-                forResource: resourceName,
-                withExtension: "json",
-                subdirectory: self.resourceSubdirectory)
+            forResource: resourceName,
+            withExtension: "json",
+            subdirectory: self.resourceSubdirectory)
        else { return [:] }

        do {
--- a/apps/macos/Sources/Clawdbot/GatewayChannel.swift
+++ b/apps/macos/Sources/Clawdbot/GatewayChannel.swift
@@ -113,17 +113,17 @@ actor GatewayChannelActor {
        self.task = nil

        await self.failPending(NSError(
-                                domain: "Gateway",
-                                code: 0,
-                                userInfo: [NSLocalizedDescriptionKey: "gateway channel shutdown"]))
+            domain: "Gateway",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "gateway channel shutdown"]))

        let waiters = self.connectWaiters
        self.connectWaiters.removeAll()
        for waiter in waiters {
            waiter.resume(throwing: NSError(
-                            domain: "Gateway",
-                            code: 0,
-                            userInfo: [NSLocalizedDescriptionKey: "gateway channel shutdown"]))
+                domain: "Gateway",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "gateway channel shutdown"]))
        }
    }

--- a/apps/macos/Sources/Clawdbot/GatewayConnection.swift
+++ b/apps/macos/Sources/Clawdbot/GatewayConnection.swift
@@ -433,14 +433,14 @@ extension GatewayConnection {
        idempotencyKey: String = UUID().uuidString) async -> (ok: Bool, error: String?)
    {
        await self.sendAgent(GatewayAgentInvocation(
-                                message: message,
-                                sessionKey: sessionKey,
-                                thinking: thinking,
-                                deliver: deliver,
-                                to: to,
-                                channel: channel,
-                                timeoutSeconds: timeoutSeconds,
-                                idempotencyKey: idempotencyKey))
+            message: message,
+            sessionKey: sessionKey,
+            thinking: thinking,
+            deliver: deliver,
+            to: to,
+            channel: channel,
+            timeoutSeconds: timeoutSeconds,
+            idempotencyKey: idempotencyKey))
    }

    func sendSystemEvent(_ params: [String: AnyCodable]) async {
--- a/apps/macos/Sources/Clawdbot/GatewayDiscoveryMenu.swift
+++ b/apps/macos/Sources/Clawdbot/GatewayDiscoveryMenu.swift
@@ -27,7 +27,7 @@ struct GatewayDiscoveryInlineList: View {
                    ForEach(self.discovery.gateways.prefix(6)) { gateway in
                        let target = self.suggestedSSHTarget(gateway)
                        let selected = (target != nil && self.currentTarget?
-                                            .trimmingCharacters(in: .whitespacesAndNewlines) == target)
+                            .trimmingCharacters(in: .whitespacesAndNewlines) == target)

                        Button {
                            withAnimation(.spring(response: 0.25, dampingFraction: 0.9)) {
@@ -61,8 +61,8 @@ struct GatewayDiscoveryInlineList: View {
                            .background(
                                RoundedRectangle(cornerRadius: 10, style: .continuous)
                                    .fill(self.rowBackground(
-                                            selected: selected,
-                                            hovered: self.hoveredGatewayID == gateway.id)))
+                                        selected: selected,
+                                        hovered: self.hoveredGatewayID == gateway.id)))
                            .overlay(
                                RoundedRectangle(cornerRadius: 10, style: .continuous)
                                    .strokeBorder(
--- a/apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift
+++ b/apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift
@@ -206,10 +206,10 @@ actor GatewayEndpointStore {
            let port = self.deps.localPort()
            let host = await self.deps.localHost()
            self.setState(.ready(
-                            mode: .local,
-                            url: URL(string: "ws://\(host):\(port)")!,
-                            token: token,
-                            password: password))
+                mode: .local,
+                url: URL(string: "ws://\(host):\(port)")!,
+                token: token,
+                password: password))
        case .remote:
            let port = await self.deps.remotePortIfRunning()
            guard let port else {
@@ -219,10 +219,10 @@ actor GatewayEndpointStore {
            }
            self.cancelRemoteEnsure()
            self.setState(.ready(
-                            mode: .remote,
-                            url: URL(string: "ws://127.0.0.1:\(Int(port))")!,
-                            token: token,
-                            password: password))
+                mode: .remote,
+                url: URL(string: "ws://127.0.0.1:\(Int(port))")!,
+                token: token,
+                password: password))
        case .unconfigured:
            self.cancelRemoteEnsure()
            self.setState(.unavailable(mode: .unconfigured, reason: "Gateway not configured"))
--- a/apps/macos/Sources/Clawdbot/GatewayPayloadDecoding.swift
+++ b/apps/macos/Sources/Clawdbot/GatewayPayloadDecoding.swift
@@ -8,7 +8,7 @@ enum GatewayPayloadDecoding {
    }

    static func decodeIfPresent<T: Decodable>(_ payload: ClawdbotProtocol.AnyCodable?, as _: T.Type = T.self) throws
-    -> T?
+        -> T?
    {
        guard let payload else { return nil }
        return try self.decode(payload, as: T.self)
--- a/apps/macos/Sources/Clawdbot/GeneralSettings.swift
+++ b/apps/macos/Sources/Clawdbot/GeneralSettings.swift
@@ -238,7 +238,7 @@ struct GeneralSettings: View {
                }
                .buttonStyle(.borderedProminent)
                .disabled(self.remoteStatus == .checking || self.state.remoteTarget
-                            .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+                    .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
            }

            GatewayDiscoveryInlineList(
@@ -627,8 +627,8 @@ extension GeneralSettings {
        let originalMode = AppStateStore.shared.connectionMode
        do {
            try await ControlChannel.shared.configure(mode: .remote(
-                                                        target: settings.target,
-                                                        identity: settings.identity))
+                target: settings.target,
+                identity: settings.identity))
            let data = try await ControlChannel.shared.health(timeout: 10)
            if decodeHealthSnapshot(from: data) != nil {
                self.remoteStatus = .ok
--- a/apps/macos/Sources/Clawdbot/InstanceIdentity.swift
+++ b/apps/macos/Sources/Clawdbot/InstanceIdentity.swift
@@ -13,7 +13,7 @@ enum InstanceIdentity {
        let defaults = Self.defaults
        if let existing = defaults.string(forKey: instanceIdKey)?
            .trimmingCharacters(in: .whitespacesAndNewlines),
-           !existing.isEmpty
+            !existing.isEmpty
        {
            return existing
        }
--- a/apps/macos/Sources/Clawdbot/LogLocator.swift
+++ b/apps/macos/Sources/Clawdbot/LogLocator.swift
@@ -30,9 +30,9 @@ enum LogLocator {
        self.ensureLogDirExists()
        let fm = FileManager.default
        let files = (try? fm.contentsOfDirectory(
-                        at: self.logDir,
-                        includingPropertiesForKeys: [.contentModificationDateKey],
-                        options: [.skipsHiddenFiles])) ?? []
+            at: self.logDir,
+            includingPropertiesForKeys: [.contentModificationDateKey],
+            options: [.skipsHiddenFiles])) ?? []

        return files
            .filter { $0.lastPathComponent.hasPrefix("clawdbot") && $0.pathExtension == "log" }
--- a/apps/macos/Sources/Clawdbot/MenuContextCardInjector.swift
+++ b/apps/macos/Sources/Clawdbot/MenuContextCardInjector.swift
@@ -51,9 +51,9 @@ final class MenuContextCardInjector: NSObject, NSMenuDelegate {
        let initialWidth = self.initialCardWidth(for: menu)

        let initial = AnyView(ContextMenuCardView(
-                                rows: initialRows,
-                                statusText: initialStatusText,
-                                isLoading: initialIsLoading))
+            rows: initialRows,
+            statusText: initialStatusText,
+            isLoading: initialIsLoading))

        let hosting = NSHostingView(rootView: initial)
        hosting.frame.size.width = max(1, initialWidth)
--- a/apps/macos/Sources/Clawdbot/MenuSessionsInjector.swift
+++ b/apps/macos/Sources/Clawdbot/MenuSessionsInjector.swift
@@ -103,6 +103,7 @@ final class MenuSessionsInjector: NSObject, NSMenuDelegate {

 extension MenuSessionsInjector {
    // MARK: - Injection
+
    private var mainSessionKey: String { WorkActivityStore.shared.mainSessionKey }

    private func inject(into menu: NSMenu) {
@@ -138,8 +139,8 @@ extension MenuSessionsInjector {
            headerItem.isEnabled = false
            let hosted = self.makeHostedView(
                rootView: AnyView(MenuSessionsHeaderView(
-                                    count: rows.count,
-                                    statusText: isConnected ? nil : self.controlChannelStatusText(for: channelState))),
+                    count: rows.count,
+                    statusText: isConnected ? nil : self.controlChannelStatusText(for: channelState))),
                width: width,
                highlighted: false)
            headerItem.view = hosted
@@ -175,8 +176,8 @@ extension MenuSessionsInjector {
                : self.controlChannelStatusText(for: channelState)
            let hosted = self.makeHostedView(
                rootView: AnyView(MenuSessionsHeaderView(
-                                    count: 0,
-                                    statusText: statusText)),
+                    count: 0,
+                    statusText: statusText)),
                width: width,
                highlighted: false)
            headerItem.view = hosted
@@ -299,7 +300,7 @@ extension MenuSessionsInjector {
        headerItem.isEnabled = false
        headerItem.view = self.makeHostedView(
            rootView: AnyView(MenuUsageHeaderView(
-                                count: rows.count)),
+                count: rows.count)),
            width: width,
            highlighted: false)
        menu.insertItem(headerItem, at: cursor)
@@ -472,11 +473,11 @@ extension MenuSessionsInjector {
        item.tag = self.tag
        item.isEnabled = false
        let view = AnyView(SessionMenuPreviewView(
-                            sessionKey: sessionKey,
-                            width: width,
-                            maxItems: 10,
-                            maxLines: maxLines,
-                            title: title))
+            sessionKey: sessionKey,
+            width: width,
+            maxItems: 10,
+            maxLines: maxLines,
+            title: title))
        item.view = self.makeHostedView(rootView: view, width: width, highlighted: false)
        return item
    }
@@ -596,10 +597,10 @@ extension MenuSessionsInjector {
        let width = self.submenuWidth()

        menu.addItem(self.makeSessionPreviewItem(
-                        sessionKey: row.key,
-                        title: "Recent messages (last 10)",
-                        width: width,
-                        maxLines: 3))
+            sessionKey: row.key,
+            title: "Recent messages (last 10)",
+            width: width,
+            maxLines: 3))

        let morePreview = NSMenuItem(title: "More preview…", action: nil, keyEquivalent: "")
        morePreview.submenu = self.buildPreviewSubmenu(sessionKey: row.key, width: width)
@@ -703,10 +704,10 @@ extension MenuSessionsInjector {
    private func buildPreviewSubmenu(sessionKey: String, width: CGFloat) -> NSMenu {
        let menu = NSMenu()
        menu.addItem(self.makeSessionPreviewItem(
-                        sessionKey: sessionKey,
-                        title: "Recent messages (expanded)",
-                        width: width,
-                        maxLines: 8))
+            sessionKey: sessionKey,
+            title: "Recent messages (expanded)",
+            width: width,
+            maxLines: 8))
        return menu
    }

@@ -763,9 +764,9 @@ extension MenuSessionsInjector {
           !commands.isEmpty
        {
            menu.addItem(self.makeNodeMultilineItem(
-                            label: "Commands",
-                            value: commands.joined(separator: ", "),
-                            width: width))
+                label: "Commands",
+                value: commands.joined(separator: ", "),
+                width: width))
        }

        return menu
@@ -855,9 +856,9 @@ extension MenuSessionsInjector {
        guard let key = sender.representedObject as? String else { return }
        Task { @MainActor in
            guard SessionActions.confirmDestructiveAction(
-                    title: "Reset session?",
-                    message: "Starts a new session id for “\(key)”.",
-                    action: "Reset")
+                title: "Reset session?",
+                message: "Starts a new session id for “\(key)”.",
+                action: "Reset")
            else { return }

            do {
@@ -874,9 +875,9 @@ extension MenuSessionsInjector {
        guard let key = sender.representedObject as? String else { return }
        Task { @MainActor in
            guard SessionActions.confirmDestructiveAction(
-                    title: "Compact session log?",
-                    message: "Keeps the last 400 lines; archives the old file.",
-                    action: "Compact")
+                title: "Compact session log?",
+                message: "Keeps the last 400 lines; archives the old file.",
+                action: "Compact")
            else { return }

            do {
@@ -893,9 +894,9 @@ extension MenuSessionsInjector {
        guard let key = sender.representedObject as? String else { return }
        Task { @MainActor in
            guard SessionActions.confirmDestructiveAction(
-                    title: "Delete session?",
-                    message: "Deletes the “\(key)” entry and archives its transcript.",
-                    action: "Delete")
+                title: "Delete session?",
+                message: "Deletes the “\(key)” entry and archives its transcript.",
+                action: "Delete")
            else { return }

            do {
--- a/apps/macos/Sources/Clawdbot/NodeMode/MacNodeBridgeSession.swift
+++ b/apps/macos/Sources/Clawdbot/NodeMode/MacNodeBridgeSession.swift
@@ -39,7 +39,7 @@ actor MacNodeBridgeSession {
        onConnected: (@Sendable (String, String?) async -> Void)? = nil,
        onDisconnected: (@Sendable (String) async -> Void)? = nil,
        onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse)
-    async throws
+        async throws
    {
        await self.disconnect()
        self.disconnectHandler = onDisconnected
@@ -77,15 +77,15 @@ actor MacNodeBridgeSession {
            })

        guard let line = try await AsyncTimeout.withTimeout(
-                seconds: 6,
-                onTimeout: {
-                    TimeoutError(message: "operation timed out")
-                },
-                operation: {
-                    try await self.receiveLine()
-                }),
-              let data = line.data(using: .utf8),
-              let base = try? self.decoder.decode(BridgeBaseFrame.self, from: data)
+            seconds: 6,
+            onTimeout: {
+                TimeoutError(message: "operation timed out")
+            },
+            operation: {
+                try await self.receiveLine()
+            }),
+            let data = line.data(using: .utf8),
+            let base = try? self.decoder.decode(BridgeBaseFrame.self, from: data)
        else {
            self.logger.error("node bridge hello failed (unexpected response)")
            await self.disconnect()
--- a/apps/macos/Sources/Clawdbot/NodeMode/MacNodeModeCoordinator.swift
+++ b/apps/macos/Sources/Clawdbot/NodeMode/MacNodeModeCoordinator.swift
@@ -312,9 +312,23 @@ final class MacNodeModeCoordinator {
                }

                let remotePort = Self.remoteBridgePort()
+                let preferredLocalPort = Self.loopbackBridgePort()
+                if let preferredLocalPort {
+                    self.logger.info(
+                        "mac node bridge tunnel starting " +
+                            "preferredLocalPort=\(preferredLocalPort, privacy: .public) " +
+                            "remotePort=\(remotePort, privacy: .public)")
+                } else {
+                    self.logger.info(
+                        "mac node bridge tunnel starting " +
+                            "preferredLocalPort=none " +
+                            "remotePort=\(remotePort, privacy: .public)")
+                }
                self.tunnel = try await RemotePortTunnel.create(
                    remotePort: remotePort,
-                    allowRemoteUrlOverride: false)
+                    preferredLocalPort: preferredLocalPort,
+                    allowRemoteUrlOverride: false,
+                    allowRandomLocalPort: true)
                if let localPort = self.tunnel?.localPort,
                   let port = NWEndpoint.Port(rawValue: localPort)
                {
@@ -389,10 +403,10 @@ final class MacNodeModeCoordinator {
                    let preferred = BridgeDiscoveryPreferences.preferredStableID()
                    if let preferred,
                       let match = results.first(where: {
-                        if case .service = $0.endpoint {
-                            return BridgeEndpointID.stableID($0.endpoint) == preferred
-                        }
-                        return false
+                           if case .service = $0.endpoint {
+                               return BridgeEndpointID.stableID($0.endpoint) == preferred
+                           }
+                           return false
                       })
                    {
                        state.finish(match.endpoint)
--- a/apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift
+++ b/apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift
@@ -181,10 +181,10 @@ actor MacNodeRuntime {
                var height: Int
            }
            let payload = try Self.encodePayload(SnapPayload(
-                                                    format: (params.format ?? .jpg).rawValue,
-                                                    base64: res.data.base64EncodedString(),
-                                                    width: Int(res.size.width),
-                                                    height: Int(res.size.height)))
+                format: (params.format ?? .jpg).rawValue,
+                base64: res.data.base64EncodedString(),
+                width: Int(res.size.width),
+                height: Int(res.size.height)))
            return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
        case ClawdbotCameraCommand.clip.rawValue:
            let params = (try? Self.decodeParams(ClawdbotCameraClipParams.self, from: req.paramsJSON)) ??
@@ -204,10 +204,10 @@ actor MacNodeRuntime {
                var hasAudio: Bool
            }
            let payload = try Self.encodePayload(ClipPayload(
-                                                    format: (params.format ?? .mp4).rawValue,
-                                                    base64: data.base64EncodedString(),
-                                                    durationMs: res.durationMs,
-                                                    hasAudio: res.hasAudio))
+                format: (params.format ?? .mp4).rawValue,
+                base64: data.base64EncodedString(),
+                durationMs: res.durationMs,
+                hasAudio: res.hasAudio))
            return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
        case ClawdbotCameraCommand.list.rawValue:
            let devices = await self.cameraCapture.listDevices()
@@ -312,12 +312,12 @@ actor MacNodeRuntime {
            var hasAudio: Bool
        }
        let payload = try Self.encodePayload(ScreenPayload(
-                                                format: "mp4",
-                                                base64: data.base64EncodedString(),
-                                                durationMs: params.durationMs,
-                                                fps: params.fps,
-                                                screenIndex: params.screenIndex,
-                                                hasAudio: res.hasAudio))
+            format: "mp4",
+            base64: data.base64EncodedString(),
+            durationMs: params.durationMs,
+            fps: params.fps,
+            screenIndex: params.screenIndex,
+            hasAudio: res.hasAudio))
        return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
    }

@@ -454,12 +454,12 @@ actor MacNodeRuntime {
        }

        let payload = try Self.encodePayload(RunPayload(
-                                                exitCode: result.exitCode,
-                                                timedOut: result.timedOut,
-                                                success: result.success,
-                                                stdout: result.stdout,
-                                                stderr: result.stderr,
-                                                error: result.errorMessage))
+            exitCode: result.exitCode,
+            timedOut: result.timedOut,
+            success: result.success,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            error: result.errorMessage))
        return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
    }

@@ -576,8 +576,8 @@ actor MacNodeRuntime {
        case .jpeg:
            let clamped = min(1.0, max(0.05, quality))
            guard let data = rep.representation(
-                    using: .jpeg,
-                    properties: [.compressionFactor: clamped])
+                using: .jpeg,
+                properties: [.compressionFactor: clamped])
            else {
                throw NSError(domain: "Canvas", code: 24, userInfo: [
                    NSLocalizedDescriptionKey: "jpeg encode failed",
--- a/apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift
+++ b/apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift
@@ -454,7 +454,7 @@ final class NodePairingApprovalPrompter {
        let center = UNUserNotificationCenter.current()
        let settings = await center.notificationSettings()
        guard settings.authorizationStatus == .authorized ||
-                settings.authorizationStatus == .provisional
+            settings.authorizationStatus == .provisional
        else {
            return
        }
@@ -547,7 +547,7 @@ final class NodePairingApprovalPrompter {
        let gateway = model.gateways.first { $0.stableID == preferred } ?? model.gateways.first
        guard let gateway else { return nil }
        let host = (gateway.tailnetDns?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty ??
-                        gateway.lanHost?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty)
+            gateway.lanHost?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty)
        guard let host, !host.isEmpty else { return nil }
        let port = gateway.sshPort > 0 ? gateway.sshPort : 22
        return SSHTarget(host: host, port: port)
--- a/apps/macos/Sources/Clawdbot/PeekabooBridgeHostCoordinator.swift
+++ b/apps/macos/Sources/Clawdbot/PeekabooBridgeHostCoordinator.swift
@@ -77,10 +77,10 @@ final class PeekabooBridgeHostCoordinator {

        var infoCF: CFDictionary?
        guard SecCodeCopySigningInformation(
-                staticCode,
-                SecCSFlags(rawValue: kSecCSSigningInformation),
-                &infoCF) == errSecSuccess,
-              let info = infoCF as? [String: Any]
+            staticCode,
+            SecCSFlags(rawValue: kSecCSSigningInformation),
+            &infoCF) == errSecSuccess,
+            let info = infoCF as? [String: Any]
        else {
            return nil
        }
@@ -106,9 +106,9 @@ private final class ClawdbotPeekabooBridgeServices: PeekabooBridgeServiceProvidi
        let feedbackClient: any AutomationFeedbackClient = NoopAutomationFeedbackClient()

        let snapshots = InMemorySnapshotManager(options: .init(
-                                                    snapshotValidityWindow: 600,
-                                                    maxSnapshots: 50,
-                                                    deleteArtifactsOnCleanup: false))
+            snapshotValidityWindow: 600,
+            maxSnapshots: 50,
+            deleteArtifactsOnCleanup: false))
        let applications = ApplicationService(feedbackClient: feedbackClient)

        let screenCapture = ScreenCaptureService(loggingService: logging)
--- a/apps/macos/Sources/Clawdbot/PortGuardian.swift
+++ b/apps/macos/Sources/Clawdbot/PortGuardian.swift
@@ -158,10 +158,10 @@ actor PortGuardian {
                mode: mode,
                listeners: listeners)
            reports.append(Self.buildReport(
-                            port: port,
-                            listeners: listeners,
-                            mode: mode,
-                            tunnelHealthy: tunnelHealthy))
+                port: port,
+                listeners: listeners,
+                mode: mode,
+                tunnelHealthy: tunnelHealthy))
        }

        return reports
--- a/apps/macos/Sources/Clawdbot/RemotePortTunnel.swift
+++ b/apps/macos/Sources/Clawdbot/RemotePortTunnel.swift
@@ -105,8 +105,8 @@ final class RemotePortTunnel {
                return
            }
            guard let line = String(data: data, encoding: .utf8)?
-                    .trimmingCharacters(in: .whitespacesAndNewlines),
-                  !line.isEmpty
+                .trimmingCharacters(in: .whitespacesAndNewlines),
+                !line.isEmpty
            else { return }
            Self.logger.error("ssh tunnel stderr: \(line, privacy: .public)")
        }
--- a/apps/macos/Sources/Clawdbot/RuntimeLocator.swift
+++ b/apps/macos/Sources/Clawdbot/RuntimeLocator.swift
@@ -42,11 +42,11 @@ struct RuntimeResolution {
 enum RuntimeResolutionError: Error {
    case notFound(searchPaths: [String])
    case unsupported(
-            kind: RuntimeKind,
-            found: RuntimeVersion,
-            required: RuntimeVersion,
-            path: String,
-            searchPaths: [String])
+        kind: RuntimeKind,
+        found: RuntimeVersion,
+        required: RuntimeVersion,
+        path: String,
+        searchPaths: [String])
    case versionParse(kind: RuntimeKind, raw: String, path: String, searchPaths: [String])
 }

@@ -65,21 +65,21 @@ enum RuntimeLocator {
        }
        guard let rawVersion = readVersion(of: binary, pathEnv: pathEnv) else {
            return .failure(.versionParse(
-                                kind: runtime,
-                                raw: "(unreadable)",
-                                path: binary,
-                                searchPaths: searchPaths))
+                kind: runtime,
+                raw: "(unreadable)",
+                path: binary,
+                searchPaths: searchPaths))
        }
        guard let parsed = RuntimeVersion.from(string: rawVersion) else {
            return .failure(.versionParse(kind: runtime, raw: rawVersion, path: binary, searchPaths: searchPaths))
        }
        guard parsed >= self.minNode else {
            return .failure(.unsupported(
-                                kind: runtime,
-                                found: parsed,
-                                required: self.minNode,
-                                path: binary,
-                                searchPaths: searchPaths))
+                kind: runtime,
+                found: parsed,
+                required: self.minNode,
+                path: binary,
+                searchPaths: searchPaths))
        }

        return .success(RuntimeResolution(kind: runtime, path: binary, version: parsed))
--- a/apps/macos/Sources/Clawdbot/ScreenRecordService.swift
+++ b/apps/macos/Sources/Clawdbot/ScreenRecordService.swift
@@ -251,11 +251,11 @@ private final class StreamRecorder: NSObject, SCStreamOutput, SCStreamDelegate,
                    if let err = self.writer.error {
                        cont
                            .resume(throwing: ScreenRecordService.ScreenRecordError
-                                        .writeFailed(err.localizedDescription))
+                                .writeFailed(err.localizedDescription))
                    } else if self.writer.status != .completed {
                        cont
                            .resume(throwing: ScreenRecordService.ScreenRecordError
-                                        .writeFailed("Failed to finalize video"))
+                                .writeFailed("Failed to finalize video"))
                    } else {
                        cont.resume()
                    }
--- a/apps/macos/Sources/Clawdbot/SoundEffects.swift
+++ b/apps/macos/Sources/Clawdbot/SoundEffects.swift
@@ -54,9 +54,9 @@ enum SoundEffectCatalog {
        var map: [String: URL] = [:]
        for root in Self.searchRoots {
            guard let contents = try? FileManager.default.contentsOfDirectory(
-                    at: root,
-                    includingPropertiesForKeys: nil,
-                    options: [.skipsHiddenFiles])
+                at: root,
+                includingPropertiesForKeys: nil,
+                options: [.skipsHiddenFiles])
            else { continue }

            for url in contents where Self.allowedExtensions.contains(url.pathExtension.lowercased()) {
@@ -88,9 +88,9 @@ enum SoundEffectPlayer {
    static func sound(from bookmark: Data) -> NSSound? {
        var stale = false
        guard let url = try? URL(
-                resolvingBookmarkData: bookmark,
-                options: [.withoutUI, .withSecurityScope],
-                bookmarkDataIsStale: &stale)
+            resolvingBookmarkData: bookmark,
+            options: [.withoutUI, .withSecurityScope],
+            bookmarkDataIsStale: &stale)
        else { return nil }

        let scoped = url.startAccessingSecurityScopedResource()
--- a/apps/macos/Sources/Clawdbot/TalkModeRuntime.swift
+++ b/apps/macos/Sources/Clawdbot/TalkModeRuntime.swift
@@ -354,9 +354,9 @@ actor TalkModeRuntime {
                    "session=\(sessionKey, privacy: .public)")

            guard let assistantText = await self.waitForAssistantText(
-                    sessionKey: sessionKey,
-                    since: startedAt,
-                    timeoutSeconds: 45)
+                sessionKey: sessionKey,
+                since: startedAt,
+                timeoutSeconds: 45)
            else {
                self.logger.warning("talk assistant text missing after timeout")
                await self.startListening()
--- a/apps/macos/Sources/Clawdbot/VoiceWakeForwarder.swift
+++ b/apps/macos/Sources/Clawdbot/VoiceWakeForwarder.swift
@@ -48,12 +48,12 @@ enum VoiceWakeForwarder {
        let payload = Self.prefixedTranscript(transcript)
        let deliver = options.channel.shouldDeliver(options.deliver)
        let result = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
-                                                                message: payload,
-                                                                sessionKey: options.sessionKey,
-                                                                thinking: options.thinking,
-                                                                deliver: deliver,
-                                                                to: options.to,
-                                                                channel: options.channel))
+            message: payload,
+            sessionKey: options.sessionKey,
+            thinking: options.thinking,
+            deliver: deliver,
+            to: options.to,
+            channel: options.channel))

        if result.ok {
            self.logger.info("voice wake forward ok")
--- a/apps/macos/Sources/Clawdbot/VoiceWakeRuntime.swift
+++ b/apps/macos/Sources/Clawdbot/VoiceWakeRuntime.swift
@@ -493,10 +493,10 @@ actor VoiceWakeRuntime {
        config: WakeWordGateConfig) -> WakeWordGateMatch?
    {
        guard let command = VoiceWakeTextUtils.textOnlyCommand(
-                transcript: transcript,
-                triggers: triggers,
-                minCommandLength: config.minCommandLength,
-                trimWake: Self.trimmedAfterTrigger)
+            transcript: transcript,
+            triggers: triggers,
+            minCommandLength: config.minCommandLength,
+            trimWake: Self.trimmedAfterTrigger)
        else { return nil }
        return WakeWordGateMatch(triggerEndTime: 0, postGap: 0, command: command)
    }
@@ -519,9 +519,9 @@ actor VoiceWakeRuntime {
        guard let lastSeenAt, let lastText else { return }
        guard self.lastTranscriptAt == lastSeenAt, self.lastTranscript == lastText else { return }
        guard let match = self.textOnlyFallbackMatch(
-                transcript: lastText,
-                triggers: triggers,
-                config: gateConfig)
+            transcript: lastText,
+            triggers: triggers,
+            config: gateConfig)
        else { return }
        if let cooldown = self.cooldownUntil, Date() < cooldown {
            return
--- a/apps/macos/Sources/Clawdbot/VoiceWakeSettings.swift
+++ b/apps/macos/Sources/Clawdbot/VoiceWakeSettings.swift
@@ -155,7 +155,7 @@ struct VoiceWakeSettings: View {
                    Label("Add word", systemImage: "plus")
                }
                .disabled(self.state.swabbleTriggerWords
-                            .contains(where: { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }))
+                    .contains(where: { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }))

                Button("Reset defaults") { self.state.swabbleTriggerWords = defaultVoiceWakeTriggers }
            }
@@ -440,21 +440,21 @@ struct VoiceWakeSettings: View {
                    { idx, localeID in
                        HStack(spacing: 8) {
                            Picker("Extra \(idx + 1)", selection: Binding(
-                                    get: { localeID },
-                                    set: { newValue in
-                                        guard self.state
-                                                .voiceWakeAdditionalLocaleIDs.indices
-                                                .contains(idx) else { return }
-                                        self.state
-                                            .voiceWakeAdditionalLocaleIDs[idx] =
-                                            newValue
-                                    })) {
-                                ForEach(self.availableLocales.map(\.identifier), id: \.self) { id in
-                                    Text(self.friendlyName(for: Locale(identifier: id))).tag(id)
+                                get: { localeID },
+                                set: { newValue in
+                                    guard self.state
+                                        .voiceWakeAdditionalLocaleIDs.indices
+                                        .contains(idx) else { return }
+                                    self.state
+                                        .voiceWakeAdditionalLocaleIDs[idx] =
+                                        newValue
+                                })) {
+                                    ForEach(self.availableLocales.map(\.identifier), id: \.self) { id in
+                                        Text(self.friendlyName(for: Locale(identifier: id))).tag(id)
+                                    }
                                }
-                            }
-                            .labelsHidden()
-                            .frame(width: 220)
+                                .labelsHidden()
+                                    .frame(width: 220)

                            Button {
                                guard self.state.voiceWakeAdditionalLocaleIDs.indices.contains(idx) else { return }
--- a/apps/macos/Sources/Clawdbot/VoiceWakeTester.swift
+++ b/apps/macos/Sources/Clawdbot/VoiceWakeTester.swift
@@ -360,10 +360,10 @@ final class VoiceWakeTester {
        config: WakeWordGateConfig) -> WakeWordGateMatch?
    {
        guard let command = VoiceWakeTextUtils.textOnlyCommand(
-                transcript: transcript,
-                triggers: triggers,
-                minCommandLength: config.minCommandLength,
-                trimWake: { WakeWordGate.stripWake(text: $0, triggers: $1) })
+            transcript: transcript,
+            triggers: triggers,
+            minCommandLength: config.minCommandLength,
+            trimWake: { WakeWordGate.stripWake(text: $0, triggers: $1) })
        else { return nil }
        return WakeWordGateMatch(triggerEndTime: 0, postGap: 0, command: command)
    }
@@ -408,9 +408,9 @@ final class VoiceWakeTester {
            guard let lastSeenAt, let lastText else { return }
            guard self.lastTranscriptAt == lastSeenAt, self.lastTranscript == lastText else { return }
            guard let match = self.textOnlyFallbackMatch(
-                    transcript: lastText,
-                    triggers: triggers,
-                    config: WakeWordGateConfig(triggers: triggers)) else { return }
+                transcript: lastText,
+                triggers: triggers,
+                config: WakeWordGateConfig(triggers: triggers)) else { return }
            self.holdingAfterDetect = true
            self.detectedText = match.command
            self.logger.info("voice wake detected (test, silence) (len=\(match.command.count))")
--- a/apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift
+++ b/apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift
@@ -92,8 +92,8 @@ struct MacGatewayChatTransport: ClawdbotChatTransport, Sendable {
        switch push {
        case let .snapshot(hello):
            let ok = (try? JSONDecoder().decode(
-                        ClawdbotGatewayHealthOK.self,
-                        from: JSONEncoder().encode(hello.snapshot.health)))?.ok ?? true
+                ClawdbotGatewayHealthOK.self,
+                from: JSONEncoder().encode(hello.snapshot.health)))?.ok ?? true
            return .health(ok: ok)

        case let .event(evt):
@@ -101,16 +101,16 @@ struct MacGatewayChatTransport: ClawdbotChatTransport, Sendable {
            case "health":
                guard let payload = evt.payload else { return nil }
                let ok = (try? JSONDecoder().decode(
-                            ClawdbotGatewayHealthOK.self,
-                            from: JSONEncoder().encode(payload)))?.ok ?? true
+                    ClawdbotGatewayHealthOK.self,
+                    from: JSONEncoder().encode(payload)))?.ok ?? true
                return .health(ok: ok)
            case "tick":
                return .tick
            case "chat":
                guard let payload = evt.payload else { return nil }
                guard let chat = try? JSONDecoder().decode(
-                        ClawdbotChatEventPayload.self,
-                        from: JSONEncoder().encode(payload))
+                    ClawdbotChatEventPayload.self,
+                    from: JSONEncoder().encode(payload))
                else {
                    return nil
                }
@@ -118,8 +118,8 @@ struct MacGatewayChatTransport: ClawdbotChatTransport, Sendable {
            case "agent":
                guard let payload = evt.payload else { return nil }
                guard let agent = try? JSONDecoder().decode(
-                        ClawdbotAgentEventPayload.self,
-                        from: JSONEncoder().encode(payload))
+                    ClawdbotAgentEventPayload.self,
+                    from: JSONEncoder().encode(payload))
                else {
                    return nil
                }
@@ -157,9 +157,9 @@ final class WebChatSwiftUIWindowController {
        let vm = ClawdbotChatViewModel(sessionKey: sessionKey, transport: transport)
        let accent = Self.color(fromHex: AppStateStore.shared.seamColorHex)
        self.hosting = NSHostingController(rootView: ClawdbotChatView(
-                                            viewModel: vm,
-                                            showsSessionSwitcher: true,
-                                            userAccent: accent))
+            viewModel: vm,
+            showsSessionSwitcher: true,
+            userAccent: accent))
        self.contentController = Self.makeContentController(for: presentation, hosting: self.hosting)
        self.window = Self.makeWindow(for: presentation, contentViewController: self.contentController)
    }
--- a/apps/macos/Sources/ClawdbotDiscovery/WideAreaGatewayDiscovery.swift
+++ b/apps/macos/Sources/ClawdbotDiscovery/WideAreaGatewayDiscovery.swift
@@ -41,12 +41,12 @@ enum WideAreaGatewayDiscovery {
        }

        guard let ips = collectTailnetIPv4s(
-                statusJson: context.tailscaleStatus()).nonEmpty else { return [] }
+            statusJson: context.tailscaleStatus()).nonEmpty else { return [] }
        var candidates = Array(ips.prefix(self.maxCandidates))
        guard let nameserver = findNameserver(
-                candidates: &candidates,
-                remaining: remaining,
-                dig: context.dig)
+            candidates: &candidates,
+            remaining: remaining,
+            dig: context.dig)
        else {
            return []
        }
@@ -55,9 +55,9 @@ enum WideAreaGatewayDiscovery {
        let domainTrimmed = domain.trimmingCharacters(in: CharacterSet(charactersIn: "."))
        let probeName = "_clawdbot-bridge._tcp.\(domainTrimmed)"
        guard let ptrLines = context.dig(
-                ["+short", "+time=1", "+tries=1", "@\(nameserver)", probeName, "PTR"],
-                min(defaultTimeoutSeconds, remaining()))?.split(whereSeparator: \.isNewline),
-              !ptrLines.isEmpty
+            ["+short", "+time=1", "+tries=1", "@\(nameserver)", probeName, "PTR"],
+            min(defaultTimeoutSeconds, remaining()))?.split(whereSeparator: \.isNewline),
+            !ptrLines.isEmpty
        else {
            return []
        }
@@ -74,8 +74,8 @@ enum WideAreaGatewayDiscovery {
            let instanceName = self.decodeDnsSdEscapes(rawInstanceName)

            guard let srv = context.dig(
-                    ["+short", "+time=1", "+tries=1", "@\(nameserver)", ptrName, "SRV"],
-                    min(defaultTimeoutSeconds, remaining()))
+                ["+short", "+time=1", "+tries=1", "@\(nameserver)", ptrName, "SRV"],
+                min(defaultTimeoutSeconds, remaining()))
            else { continue }
            guard let (host, port) = parseSrv(srv) else { continue }

@@ -198,7 +198,7 @@ enum WideAreaGatewayDiscovery {
                    if let stdout = dig(
                        ["+short", "+time=1", "+tries=1", "@\(ip)", probeName, "PTR"],
                        min(defaultTimeoutSeconds, budget)),
-                       stdout.split(whereSeparator: \.isNewline).isEmpty == false
+                        stdout.split(whereSeparator: \.isNewline).isEmpty == false
                    {
                        state.lock.lock()
                        if state.found == nil {
--- a/apps/macos/Sources/ClawdbotIPC/IPC.swift
+++ b/apps/macos/Sources/ClawdbotIPC/IPC.swift
@@ -107,18 +107,18 @@ public enum CanvasA2UICommand: String, Codable, Sendable {

 public enum Request: Sendable {
    case notify(
-            title: String,
-            body: String,
-            sound: String?,
-            priority: NotificationPriority?,
-            delivery: NotificationDelivery?)
+        title: String,
+        body: String,
+        sound: String?,
+        priority: NotificationPriority?,
+        delivery: NotificationDelivery?)
    case ensurePermissions([Capability], interactive: Bool)
    case runShell(
-            command: [String],
-            cwd: String?,
-            env: [String: String]?,
-            timeoutSec: Double?,
-            needsScreenRecording: Bool)
+        command: [String],
+        cwd: String?,
+        env: [String: String]?,
+        timeoutSec: Double?,
+        needsScreenRecording: Bool)
    case status
    case agent(message: String, thinking: String?, session: String?, deliver: Bool, to: String?)
    case rpcStatus
@@ -410,6 +410,6 @@ extension Request: Codable {
 // Shared transport settings
 public let controlSocketPath =
    FileManager.default
-    .homeDirectoryForCurrentUser
-    .appendingPathComponent("Library/Application Support/clawdbot/control.sock")
-    .path
+        .homeDirectoryForCurrentUser
+        .appendingPathComponent("Library/Application Support/clawdbot/control.sock")
+        .path
--- a/docs/platforms/macos.md
+++ b/docs/platforms/macos.md
@@ -110,6 +110,32 @@ Tip: compare against `pnpm clawdbot gateway discover --json` to see whether the
 macOS app’s discovery pipeline (NWBrowser + tailnet DNS‑SD fallback) differs from
 the Node CLI’s `dns-sd` based discovery.

+## Remote connection plumbing (SSH tunnels)
+
+When the macOS app runs in **Remote** mode, it opens SSH tunnels so local UI
+components can talk to a remote Gateway as if it were on localhost. There are
+two independent tunnels:
+
+### Control tunnel (Gateway control/WebSocket port)
+- **Purpose:** health checks, status, Web Chat, config, and other control-plane calls.
+- **Local port:** the Gateway port (default `18789`), always stable.
+- **Remote port:** the same Gateway port on the remote host.
+- **Behavior:** no random local port; the app reuses an existing healthy tunnel
+  or restarts it if needed.
+- **SSH shape:** `ssh -N -L <local>:127.0.0.1:<remote>` with BatchMode +
+  ExitOnForwardFailure + keepalive options.
+
+### Node bridge tunnel (macOS node mode)
+- **Purpose:** connect the macOS node to the Gateway **Bridge** protocol (TCP JSONL).
+- **Remote port:** `gatewayPort + 1` (default `18790`), derived from the Gateway port.
+- **Local port preference:** `CLAWDBOT_BRIDGE_PORT` or the default `18790`.
+- **Behavior:** prefer the default bridge port for consistency; fall back to a
+  random local port if the preferred one is busy. The node then connects to the
+  resolved local port.
+
+For setup steps, see [macOS remote access](/platforms/mac/remote). For protocol
+details, see [Bridge protocol](/gateway/bridge-protocol).
+
 ## Related docs

 - [Gateway runbook](/gateway)
--- a/src/infra/bridge/server.enables-keepalive-sockets.test.ts
+++ b/src/infra/bridge/server.enables-keepalive-sockets.test.ts
@@ -9,6 +9,9 @@ import { pollUntil } from "../../../test/helpers/poll.js";
 import { approveNodePairing, listNodePairing } from "../node-pairing.js";
 import { configureNodeBridgeSocket, startNodeBridgeServer } from "./server.js";

+const pairingTimeoutMs = process.platform === "win32" ? 8000 : 3000;
+const suiteTimeoutMs = process.platform === "win32" ? 20000 : 10000;
+
 function createLineReader(socket: net.Socket) {
  let buffer = "";
  const pending: Array<(line: string) => void> = [];
@@ -55,9 +58,8 @@ async function waitForSocketConnect(socket: net.Socket) {
  });
 }

-describe("node bridge server", () => {
+describe("node bridge server", { timeout: suiteTimeoutMs }, () => {
  let baseDir = "";
-  const pairingTimeoutMs = process.platform === "win32" ? 8000 : 3000;

  const pickNonLoopbackIPv4 = () => {
    const ifaces = os.networkInterfaces();