test: restore Ollama provider tests (#1606 ) (thanks @abhaymundhara)

fix: Make Ollama provider opt-in to avoid breaking existing tests
**Root Cause:** The Ollama provider was being added to ALL configurations by default (with a fallback API key of 'ollama-local'), which broke tests that expected NO providers when no API keys were configured. **Solution:** - Removed the default fallback API key for Ollama - Ollama provider now requires explicit configuration via: - OLLAMA_API_KEY environment variable, OR - Ollama profile in auth store - Updated documentation to reflect the explicit configuration requirement - Added a test to verify Ollama is not added by default This fixes all 4 failing test suites: - checks (node, test, pnpm test) - checks (bun, test, bunx vitest run) - checks-windows (node, test, pnpm test) - checks-macos (test, pnpm test) Closes #1531
2026-01-24 22:38:21 +00:00 · 2026-01-24 22:37:44 +00:00 · 2026-01-24 22:37:19 +00:00 · 2026-01-24 22:35:17 +00:00 · 2026-01-24 22:23:49 +00:00 · 2026-01-24 22:09:24 +00:00
83 changed files with 3897 additions and 738 deletions
@@ -41,8 +41,12 @@ jobs:
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
            type=semver,pattern={{version}},suffix=-amd64
+            type=semver,pattern={{version}},suffix=-arm64
            type=ref,event=branch,suffix=-amd64
+            type=ref,event=branch,suffix=-arm64

      - name: Build and push amd64 image
        id: build
@@ -86,7 +90,11 @@ jobs:
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{version}},suffix=-amd64
            type=semver,pattern={{version}},suffix=-arm64
+            type=ref,event=branch,suffix=-amd64
            type=ref,event=branch,suffix=-arm64

      - name: Build and push arm64 image
@@ -110,9 +118,6 @@ jobs:
      contents: read
    needs: [build-amd64, build-arm64]
    steps:
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
@@ -128,12 +133,11 @@ jobs:
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
-            type=raw,value=latest,enable={{is_tag}}

      - name: Create and push manifest
        run: |
          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build-amd64.outputs.image-digest }} \
-            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build-arm64.outputs.image-digest }}
+            ${{ needs.build-amd64.outputs.image-digest }} \
+            ${{ needs.build-arm64.outputs.image-digest }}
        env:
          DOCKER_METADATA_OUTPUT_JSON: ${{ steps.meta.outputs.json }}
@@ -8,16 +8,24 @@ Docs: https://docs.clawd.bot
 - Docs: expand FAQ (migration, scheduling, concurrency, model recommendations, OpenAI subscription auth, Pi sizing, hackable install, docs SSL workaround).
 - Docs: add verbose installer troubleshooting guidance.
 - Docs: update Fly.io guide notes.
+- Docs: add Bedrock EC2 instance role setup + IAM steps. (#1625) Thanks @sergical. https://docs.clawd.bot/bedrock
+- Exec approvals: forward approval prompts to chat with `/approve` for all channels (including plugins). (#1621) Thanks @czekaj. https://docs.clawd.bot/tools/exec-approvals https://docs.clawd.bot/tools/slash-commands
+- Models: add Ollama provider discovery + docs. (#1606) Thanks @abhaymundhara. https://docs.clawd.bot/providers/ollama

 ### Fixes
 - Web UI: hide internal `message_id` hints in chat bubbles.
 - Heartbeat: normalize target identifiers for consistent routing.
+- Telegram: use wrapped fetch for long-polling on Node to normalize AbortSignal handling. (#1639)
+- Exec: keep approvals for elevated ask unless full mode. (#1616) Thanks @ivancasco.
+- Agents: auto-compact on context overflow prompt errors before failing. (#1627) Thanks @rodrigouroz.
+- Agents: use the active auth profile for auto-compaction recovery.
+- Gateway: reduce log noise for late invokes + remote node probes; debounce skills refresh. (#1607) Thanks @petter-b.
+- macOS: default direct-transport `ws://` URLs to port 18789; document `gateway.remote.transport`. (#1603) Thanks @ngutman.

 ## 2026.1.23-1

 ### Fixes
 - Packaging: include dist/tts output in npm tarball (fixes missing dist/tts/tts.js).
- CI: publish multi-arch Docker images on main and release tags. (#1602) Thanks @denysvitali.

 ## 2026.1.23

@@ -24,6 +24,11 @@ final class AppState {
        case remote
    }

+    enum RemoteTransport: String {
+        case ssh
+        case direct
+    }
+
    var isPaused: Bool {
        didSet { self.ifNotPreview { UserDefaults.standard.set(self.isPaused, forKey: pauseDefaultsKey) } }
    }
@@ -166,6 +171,10 @@ final class AppState {
        }
    }

+    var remoteTransport: RemoteTransport {
+        didSet { self.syncGatewayConfigIfNeeded() }
+    }
+
    var canvasEnabled: Bool {
        didSet { self.ifNotPreview { UserDefaults.standard.set(self.canvasEnabled, forKey: canvasEnabledKey) } }
    }
@@ -200,6 +209,10 @@ final class AppState {
        }
    }

+    var remoteUrl: String {
+        didSet { self.syncGatewayConfigIfNeeded() }
+    }
+
    var remoteIdentity: String {
        didSet { self.ifNotPreview { UserDefaults.standard.set(self.remoteIdentity, forKey: remoteIdentityKey) } }
    }
@@ -263,13 +276,15 @@ final class AppState {
        }

        let configRoot = ClawdbotConfigFile.loadDict()
-        let configGateway = configRoot["gateway"] as? [String: Any]
-        let configRemoteUrl = (configGateway?["remote"] as? [String: Any])?["url"] as? String
+        let configRemoteUrl = GatewayRemoteConfig.resolveUrlString(root: configRoot)
+        let configRemoteTransport = GatewayRemoteConfig.resolveTransport(root: configRoot)
        let resolvedConnectionMode = ConnectionModeResolver.resolve(root: configRoot).mode
+        self.remoteTransport = configRemoteTransport
        self.connectionMode = resolvedConnectionMode

        let storedRemoteTarget = UserDefaults.standard.string(forKey: remoteTargetKey) ?? ""
        if resolvedConnectionMode == .remote,
+           configRemoteTransport != .direct,
           storedRemoteTarget.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty,
           let host = AppState.remoteHost(from: configRemoteUrl)
        {
@@ -277,6 +292,7 @@ final class AppState {
        } else {
            self.remoteTarget = storedRemoteTarget
        }
+        self.remoteUrl = configRemoteUrl ?? ""
        self.remoteIdentity = UserDefaults.standard.string(forKey: remoteIdentityKey) ?? ""
        self.remoteProjectRoot = UserDefaults.standard.string(forKey: remoteProjectRootKey) ?? ""
        self.remoteCliPath = UserDefaults.standard.string(forKey: remoteCliPathKey) ?? ""
@@ -354,10 +370,11 @@ final class AppState {
    private func applyConfigOverrides(_ root: [String: Any]) {
        let gateway = root["gateway"] as? [String: Any]
        let modeRaw = (gateway?["mode"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
-        let remoteUrl = (gateway?["remote"] as? [String: Any])?["url"] as? String
+        let remoteUrl = GatewayRemoteConfig.resolveUrlString(root: root)
        let hasRemoteUrl = !(remoteUrl?
            .trimmingCharacters(in: .whitespacesAndNewlines)
            .isEmpty ?? true)
+        let remoteTransport = GatewayRemoteConfig.resolveTransport(root: root)

        let desiredMode: ConnectionMode? = switch modeRaw {
        case "local":
@@ -378,8 +395,17 @@ final class AppState {
            self.connectionMode = .remote
        }

+        if remoteTransport != self.remoteTransport {
+            self.remoteTransport = remoteTransport
+        }
+        let remoteUrlText = remoteUrl ?? ""
+        if remoteUrlText != self.remoteUrl {
+            self.remoteUrl = remoteUrlText
+        }
+
        let targetMode = desiredMode ?? self.connectionMode
        if targetMode == .remote,
+           remoteTransport != .direct,
           let host = AppState.remoteHost(from: remoteUrl)
        {
            self.updateRemoteTarget(host: host)
@@ -402,6 +428,8 @@ final class AppState {
        let connectionMode = self.connectionMode
        let remoteTarget = self.remoteTarget
        let remoteIdentity = self.remoteIdentity
+        let remoteTransport = self.remoteTransport
+        let remoteUrl = self.remoteUrl
        let desiredMode: String? = switch connectionMode {
        case .local:
            "local"
@@ -435,39 +463,63 @@ final class AppState {
                var remote = gateway["remote"] as? [String: Any] ?? [:]
                var remoteChanged = false

-                if let host = remoteHost {
-                    let existingUrl = (remote["url"] as? String)?
-                        .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-                    let parsedExisting = existingUrl.isEmpty ? nil : URL(string: existingUrl)
-                    let scheme = parsedExisting?.scheme?.isEmpty == false ? parsedExisting?.scheme : "ws"
-                    let port = parsedExisting?.port ?? 18789
-                    let desiredUrl = "\(scheme ?? "ws")://\(host):\(port)"
-                    if existingUrl != desiredUrl {
-                        remote["url"] = desiredUrl
+                if remoteTransport == .direct {
+                    let trimmedUrl = remoteUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+                    if trimmedUrl.isEmpty {
+                        if remote["url"] != nil {
+                            remote.removeValue(forKey: "url")
+                            remoteChanged = true
+                        }
+                    } else {
+                        let normalizedUrl = GatewayRemoteConfig.normalizeGatewayUrlString(trimmedUrl) ?? trimmedUrl
+                        if (remote["url"] as? String) != normalizedUrl {
+                            remote["url"] = normalizedUrl
+                            remoteChanged = true
+                        }
+                    }
+                    if (remote["transport"] as? String) != RemoteTransport.direct.rawValue {
+                        remote["transport"] = RemoteTransport.direct.rawValue
                        remoteChanged = true
                    }
-                }
+                } else {
+                    if remote["transport"] != nil {
+                        remote.removeValue(forKey: "transport")
+                        remoteChanged = true
+                    }
+                    if let host = remoteHost {
+                        let existingUrl = (remote["url"] as? String)?
+                            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+                        let parsedExisting = existingUrl.isEmpty ? nil : URL(string: existingUrl)
+                        let scheme = parsedExisting?.scheme?.isEmpty == false ? parsedExisting?.scheme : "ws"
+                        let port = parsedExisting?.port ?? 18789
+                        let desiredUrl = "\(scheme ?? "ws")://\(host):\(port)"
+                        if existingUrl != desiredUrl {
+                            remote["url"] = desiredUrl
+                            remoteChanged = true
+                        }
+                    }

-                let sanitizedTarget = Self.sanitizeSSHTarget(remoteTarget)
-                if !sanitizedTarget.isEmpty {
-                    if (remote["sshTarget"] as? String) != sanitizedTarget {
-                        remote["sshTarget"] = sanitizedTarget
+                    let sanitizedTarget = Self.sanitizeSSHTarget(remoteTarget)
+                    if !sanitizedTarget.isEmpty {
+                        if (remote["sshTarget"] as? String) != sanitizedTarget {
+                            remote["sshTarget"] = sanitizedTarget
+                            remoteChanged = true
+                        }
+                    } else if remote["sshTarget"] != nil {
+                        remote.removeValue(forKey: "sshTarget")
                        remoteChanged = true
                    }
-                } else if remote["sshTarget"] != nil {
-                    remote.removeValue(forKey: "sshTarget")
-                    remoteChanged = true
-                }

-                let trimmedIdentity = remoteIdentity.trimmingCharacters(in: .whitespacesAndNewlines)
-                if !trimmedIdentity.isEmpty {
-                    if (remote["sshIdentity"] as? String) != trimmedIdentity {
-                        remote["sshIdentity"] = trimmedIdentity
+                    let trimmedIdentity = remoteIdentity.trimmingCharacters(in: .whitespacesAndNewlines)
+                    if !trimmedIdentity.isEmpty {
+                        if (remote["sshIdentity"] as? String) != trimmedIdentity {
+                            remote["sshIdentity"] = trimmedIdentity
+                            remoteChanged = true
+                        }
+                    } else if remote["sshIdentity"] != nil {
+                        remote.removeValue(forKey: "sshIdentity")
                        remoteChanged = true
                    }
-                } else if remote["sshIdentity"] != nil {
-                    remote.removeValue(forKey: "sshIdentity")
-                    remoteChanged = true
                }

                if remoteChanged {
@@ -621,8 +673,10 @@ extension AppState {
        state.iconOverride = .system
        state.heartbeatsEnabled = true
        state.connectionMode = .local
+        state.remoteTransport = .ssh
        state.canvasEnabled = true
        state.remoteTarget = "user@example.com"
+        state.remoteUrl = "wss://gateway.example.ts.net"
        state.remoteIdentity = "~/.ssh/id_ed25519"
        state.remoteProjectRoot = "~/Projects/clawdbot"
        state.remoteCliPath = ""
@@ -0,0 +1,47 @@
+import ClawdbotDiscovery
+import Foundation
+
+enum GatewayDiscoveryHelpers {
+    static func sshTarget(for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
+        let host = self.sanitizedTailnetHost(gateway.tailnetDns) ?? gateway.lanHost
+        guard let host = self.trimmed(host), !host.isEmpty else { return nil }
+        let user = NSUserName()
+        var target = "\(user)@\(host)"
+        if gateway.sshPort != 22 {
+            target += ":\(gateway.sshPort)"
+        }
+        return target
+    }
+
+    static func directUrl(for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
+        self.directGatewayUrl(
+            tailnetDns: gateway.tailnetDns,
+            lanHost: gateway.lanHost,
+            gatewayPort: gateway.gatewayPort)
+    }
+
+    static func directGatewayUrl(
+        tailnetDns: String?,
+        lanHost: String?,
+        gatewayPort: Int?) -> String?
+    {
+        if let tailnetDns = self.sanitizedTailnetHost(tailnetDns) {
+            return "wss://\(tailnetDns)"
+        }
+        guard let lanHost = self.trimmed(lanHost), !lanHost.isEmpty else { return nil }
+        let port = gatewayPort ?? 18789
+        return "ws://\(lanHost):\(port)"
+    }
+
+    static func sanitizedTailnetHost(_ host: String?) -> String? {
+        guard let host = self.trimmed(host), !host.isEmpty else { return nil }
+        if host.hasSuffix(".internal.") || host.hasSuffix(".internal") {
+            return nil
+        }
+        return host
+    }
+
+    private static func trimmed(_ value: String?) -> String? {
+        value?.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
@@ -4,6 +4,8 @@ import SwiftUI
 struct GatewayDiscoveryInlineList: View {
    var discovery: GatewayDiscoveryModel
    var currentTarget: String?
+    var currentUrl: String?
+    var transport: AppState.RemoteTransport
    var onSelect: (GatewayDiscoveryModel.DiscoveredGateway) -> Void
    @State private var hoveredGatewayID: GatewayDiscoveryModel.DiscoveredGateway.ID?

@@ -25,9 +27,8 @@ struct GatewayDiscoveryInlineList: View {
            } else {
                VStack(alignment: .leading, spacing: 6) {
                    ForEach(self.discovery.gateways.prefix(6)) { gateway in
-                        let target = self.suggestedSSHTarget(gateway)
-                        let selected = (target != nil && self.currentTarget?
-                            .trimmingCharacters(in: .whitespacesAndNewlines) == target)
+                        let display = self.displayInfo(for: gateway)
+                        let selected = display.selected

                        Button {
                            withAnimation(.spring(response: 0.25, dampingFraction: 0.9)) {
@@ -40,7 +41,7 @@ struct GatewayDiscoveryInlineList: View {
                                        .font(.callout.weight(.semibold))
                                        .lineLimit(1)
                                        .truncationMode(.tail)
-                                    Text(target ?? "Gateway pairing only")
+                                    Text(display.label)
                                        .font(.caption.monospaced())
                                        .foregroundStyle(.secondary)
                                        .lineLimit(1)
@@ -83,27 +84,26 @@ struct GatewayDiscoveryInlineList: View {
                        .fill(Color(NSColor.controlBackgroundColor)))
            }
        }
-        .help("Click a discovered gateway to fill the SSH target.")
+        .help(self.transport == .direct
+            ? "Click a discovered gateway to fill the gateway URL."
+            : "Click a discovered gateway to fill the SSH target.")
    }

-    private func suggestedSSHTarget(_ gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
-        let host = self.sanitizedTailnetHost(gateway.tailnetDns) ?? gateway.lanHost
-        guard let host else { return nil }
-        let user = NSUserName()
-        return GatewayDiscoveryModel.buildSSHTarget(
-            user: user,
-            host: host,
-            port: gateway.sshPort)
-    }
-
-    private func sanitizedTailnetHost(_ host: String?) -> String? {
-        guard let host else { return nil }
-        let trimmed = host.trimmingCharacters(in: .whitespacesAndNewlines)
-        if trimmed.isEmpty { return nil }
-        if trimmed.hasSuffix(".internal.") || trimmed.hasSuffix(".internal") {
-            return nil
+    private func displayInfo(
+        for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> (label: String, selected: Bool)
+    {
+        switch self.transport {
+        case .direct:
+            let url = GatewayDiscoveryHelpers.directUrl(for: gateway)
+            let label = url ?? "Gateway pairing only"
+            let selected = url != nil && self.trimmed(self.currentUrl) == url
+            return (label, selected)
+        case .ssh:
+            let target = GatewayDiscoveryHelpers.sshTarget(for: gateway)
+            let label = target ?? "Gateway pairing only"
+            let selected = target != nil && self.trimmed(self.currentTarget) == target
+            return (label, selected)
        }
-        return trimmed
    }

    private func rowBackground(selected: Bool, hovered: Bool) -> Color {
@@ -111,6 +111,10 @@ struct GatewayDiscoveryInlineList: View {
        if hovered { return Color.secondary.opacity(0.08) }
        return Color.clear
    }
+
+    private func trimmed(_ value: String?) -> String {
+        value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    }
 }

 struct GatewayDiscoveryMenu: View {
@@ -311,6 +311,19 @@ actor GatewayEndpointStore {
                token: token,
                password: password))
        case .remote:
+            let root = ClawdbotConfigFile.loadDict()
+            if GatewayRemoteConfig.resolveTransport(root: root) == .direct {
+                guard let url = GatewayRemoteConfig.resolveGatewayUrl(root: root) else {
+                    self.cancelRemoteEnsure()
+                    self.setState(.unavailable(
+                        mode: .remote,
+                        reason: "gateway.remote.url missing or invalid for direct transport"))
+                    return
+                }
+                self.cancelRemoteEnsure()
+                self.setState(.ready(mode: .remote, url: url, token: token, password: password))
+                return
+            }
            let port = await self.deps.remotePortIfRunning()
            guard let port else {
                self.setState(.connecting(mode: .remote, detail: Self.remoteConnectingDetail))
@@ -341,6 +354,25 @@ actor GatewayEndpointStore {
                code: 1,
                userInfo: [NSLocalizedDescriptionKey: "Remote mode is not enabled"])
        }
+        let root = ClawdbotConfigFile.loadDict()
+        if GatewayRemoteConfig.resolveTransport(root: root) == .direct {
+            guard let url = GatewayRemoteConfig.resolveGatewayUrl(root: root) else {
+                throw NSError(
+                    domain: "GatewayEndpoint",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "gateway.remote.url missing or invalid"])
+            }
+            guard let port = GatewayRemoteConfig.defaultPort(for: url),
+                  let portInt = UInt16(exactly: port)
+            else {
+                throw NSError(
+                    domain: "GatewayEndpoint",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "Invalid gateway.remote.url port"])
+            }
+            self.logger.info("remote transport direct; skipping SSH tunnel")
+            return portInt
+        }
        let config = try await self.ensureRemoteConfig(detail: Self.remoteConnectingDetail)
        guard let portInt = config.0.port, let port = UInt16(exactly: portInt) else {
            throw NSError(
@@ -401,6 +433,21 @@ actor GatewayEndpointStore {
                userInfo: [NSLocalizedDescriptionKey: "Remote mode is not enabled"])
        }

+        let root = ClawdbotConfigFile.loadDict()
+        if GatewayRemoteConfig.resolveTransport(root: root) == .direct {
+            guard let url = GatewayRemoteConfig.resolveGatewayUrl(root: root) else {
+                throw NSError(
+                    domain: "GatewayEndpoint",
+                    code: 1,
+                    userInfo: [NSLocalizedDescriptionKey: "gateway.remote.url missing or invalid"])
+            }
+            let token = self.deps.token()
+            let password = self.deps.password()
+            self.cancelRemoteEnsure()
+            self.setState(.ready(mode: .remote, url: url, token: token, password: password))
+            return (url, token, password)
+        }
+
        self.kickRemoteEnsureIfNeeded(detail: detail)
        guard let ensure = self.remoteEnsure else {
            throw NSError(domain: "GatewayEndpoint", code: 1, userInfo: [NSLocalizedDescriptionKey: "Connecting…"])
@@ -0,0 +1,64 @@
+import Foundation
+
+enum GatewayRemoteConfig {
+    static func resolveTransport(root: [String: Any]) -> AppState.RemoteTransport {
+        guard let gateway = root["gateway"] as? [String: Any],
+              let remote = gateway["remote"] as? [String: Any],
+              let raw = remote["transport"] as? String
+        else {
+            return .ssh
+        }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed == AppState.RemoteTransport.direct.rawValue ? .direct : .ssh
+    }
+
+    static func resolveUrlString(root: [String: Any]) -> String? {
+        guard let gateway = root["gateway"] as? [String: Any],
+              let remote = gateway["remote"] as? [String: Any],
+              let urlRaw = remote["url"] as? String
+        else {
+            return nil
+        }
+        let trimmed = urlRaw.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    static func resolveGatewayUrl(root: [String: Any]) -> URL? {
+        guard let raw = self.resolveUrlString(root: root) else { return nil }
+        return self.normalizeGatewayUrl(raw)
+    }
+
+    static func normalizeGatewayUrlString(_ raw: String) -> String? {
+        self.normalizeGatewayUrl(raw)?.absoluteString
+    }
+
+    static func normalizeGatewayUrl(_ raw: String) -> URL? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, let url = URL(string: trimmed) else { return nil }
+        let scheme = url.scheme?.lowercased() ?? ""
+        guard scheme == "ws" || scheme == "wss" else { return nil }
+        let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !host.isEmpty else { return nil }
+        if scheme == "ws", url.port == nil {
+            guard var components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
+                return url
+            }
+            components.port = 18789
+            return components.url
+        }
+        return url
+    }
+
+    static func defaultPort(for url: URL) -> Int? {
+        if let port = url.port { return port }
+        let scheme = url.scheme?.lowercased() ?? ""
+        switch scheme {
+        case "wss":
+            return 443
+        case "ws":
+            return 18789
+        default:
+            return nil
+        }
+    }
+}
@@ -17,6 +17,7 @@ struct GeneralSettings: View {
    @State private var showRemoteAdvanced = false
    private let isPreview = ProcessInfo.processInfo.isPreview
    private var isNixMode: Bool { ProcessInfo.processInfo.isNixMode }
+    private var remoteLabelWidth: CGFloat { 88 }

    var body: some View {
        ScrollView(.vertical) {
@@ -104,7 +105,7 @@ struct GeneralSettings: View {
            Picker("Mode", selection: self.$state.connectionMode) {
                Text("Not configured").tag(AppState.ConnectionMode.unconfigured)
                Text("Local (this Mac)").tag(AppState.ConnectionMode.local)
-                Text("Remote over SSH").tag(AppState.ConnectionMode.remote)
+                Text("Remote (another host)").tag(AppState.ConnectionMode.remote)
            }
            .pickerStyle(.menu)
            .labelsHidden()
@@ -136,60 +137,51 @@ struct GeneralSettings: View {

    private var remoteCard: some View {
        VStack(alignment: .leading, spacing: 10) {
-            HStack(alignment: .center, spacing: 10) {
-                Text("SSH")
-                    .font(.callout.weight(.semibold))
-                    .frame(width: 48, alignment: .leading)
-                TextField("user@host[:22]", text: self.$state.remoteTarget)
-                    .textFieldStyle(.roundedBorder)
-                    .frame(maxWidth: .infinity)
-                Button {
-                    Task { await self.testRemote() }
-                } label: {
-                    if self.remoteStatus == .checking {
-                        ProgressView().controlSize(.small)
-                    } else {
-                        Text("Test remote")
-                    }
-                }
-                .buttonStyle(.borderedProminent)
-                .disabled(self.remoteStatus == .checking || self.state.remoteTarget
-                    .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+            self.remoteTransportRow
+
+            if self.state.remoteTransport == .ssh {
+                self.remoteSshRow
+            } else {
+                self.remoteDirectRow
            }

            GatewayDiscoveryInlineList(
                discovery: self.gatewayDiscovery,
-                currentTarget: self.state.remoteTarget)
+                currentTarget: self.state.remoteTarget,
+                currentUrl: self.state.remoteUrl,
+                transport: self.state.remoteTransport)
            { gateway in
                self.applyDiscoveredGateway(gateway)
            }
-            .padding(.leading, 58)
+            .padding(.leading, self.remoteLabelWidth + 10)

            self.remoteStatusView
-                .padding(.leading, 58)
+                .padding(.leading, self.remoteLabelWidth + 10)

-            DisclosureGroup(isExpanded: self.$showRemoteAdvanced) {
-                VStack(alignment: .leading, spacing: 8) {
-                    LabeledContent("Identity file") {
-                        TextField("/Users/you/.ssh/id_ed25519", text: self.$state.remoteIdentity)
-                            .textFieldStyle(.roundedBorder)
-                            .frame(width: 280)
-                    }
-                    LabeledContent("Project root") {
-                        TextField("/home/you/Projects/clawdbot", text: self.$state.remoteProjectRoot)
-                            .textFieldStyle(.roundedBorder)
-                            .frame(width: 280)
-                    }
-                    LabeledContent("CLI path") {
-                        TextField("/Applications/Clawdbot.app/.../clawdbot", text: self.$state.remoteCliPath)
-                            .textFieldStyle(.roundedBorder)
-                            .frame(width: 280)
+            if self.state.remoteTransport == .ssh {
+                DisclosureGroup(isExpanded: self.$showRemoteAdvanced) {
+                    VStack(alignment: .leading, spacing: 8) {
+                        LabeledContent("Identity file") {
+                            TextField("/Users/you/.ssh/id_ed25519", text: self.$state.remoteIdentity)
+                                .textFieldStyle(.roundedBorder)
+                                .frame(width: 280)
+                        }
+                        LabeledContent("Project root") {
+                            TextField("/home/you/Projects/clawdbot", text: self.$state.remoteProjectRoot)
+                                .textFieldStyle(.roundedBorder)
+                                .frame(width: 280)
+                        }
+                        LabeledContent("CLI path") {
+                            TextField("/Applications/Clawdbot.app/.../clawdbot", text: self.$state.remoteCliPath)
+                                .textFieldStyle(.roundedBorder)
+                                .frame(width: 280)
+                        }
                    }
+                    .padding(.top, 4)
+                } label: {
+                    Text("Advanced")
+                        .font(.callout.weight(.semibold))
                }
-                .padding(.top, 4)
-            } label: {
-                Text("Advanced")
-                    .font(.callout.weight(.semibold))
            }

            // Diagnostics
@@ -219,16 +211,89 @@ struct GeneralSettings: View {
                }
            }

-            Text("Tip: enable Tailscale for stable remote access.")
-                .font(.footnote)
-                .foregroundStyle(.secondary)
-                .lineLimit(1)
+            if self.state.remoteTransport == .ssh {
+                Text("Tip: enable Tailscale for stable remote access.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+            } else {
+                Text("Tip: use Tailscale Serve so the gateway has a valid HTTPS cert.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(2)
+            }
        }
        .transition(.opacity)
        .onAppear { self.gatewayDiscovery.start() }
        .onDisappear { self.gatewayDiscovery.stop() }
    }

+    private var remoteTransportRow: some View {
+        HStack(alignment: .center, spacing: 10) {
+            Text("Transport")
+                .font(.callout.weight(.semibold))
+                .frame(width: self.remoteLabelWidth, alignment: .leading)
+            Picker("Transport", selection: self.$state.remoteTransport) {
+                Text("SSH tunnel").tag(AppState.RemoteTransport.ssh)
+                Text("Direct (ws/wss)").tag(AppState.RemoteTransport.direct)
+            }
+            .pickerStyle(.segmented)
+            .frame(maxWidth: 320)
+        }
+    }
+
+    private var remoteSshRow: some View {
+        HStack(alignment: .center, spacing: 10) {
+            Text("SSH target")
+                .font(.callout.weight(.semibold))
+                .frame(width: self.remoteLabelWidth, alignment: .leading)
+            TextField("user@host[:22]", text: self.$state.remoteTarget)
+                .textFieldStyle(.roundedBorder)
+                .frame(maxWidth: .infinity)
+            Button {
+                Task { await self.testRemote() }
+            } label: {
+                if self.remoteStatus == .checking {
+                    ProgressView().controlSize(.small)
+                } else {
+                    Text("Test remote")
+                }
+            }
+            .buttonStyle(.borderedProminent)
+            .disabled(self.remoteStatus == .checking || self.state.remoteTarget
+                .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+        }
+    }
+
+    private var remoteDirectRow: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .center, spacing: 10) {
+                Text("Gateway")
+                    .font(.callout.weight(.semibold))
+                    .frame(width: self.remoteLabelWidth, alignment: .leading)
+                TextField("wss://gateway.example.ts.net", text: self.$state.remoteUrl)
+                    .textFieldStyle(.roundedBorder)
+                    .frame(maxWidth: .infinity)
+                Button {
+                    Task { await self.testRemote() }
+                } label: {
+                    if self.remoteStatus == .checking {
+                        ProgressView().controlSize(.small)
+                    } else {
+                        Text("Test remote")
+                    }
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(self.remoteStatus == .checking || self.state.remoteUrl
+                    .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+            }
+            Text("Direct mode requires a ws:// or wss:// URL (Tailscale Serve uses wss://<magicdns>).")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .padding(.leading, self.remoteLabelWidth + 10)
+        }
+    }
+
    private var controlStatusLine: String {
        switch ControlChannel.shared.state {
        case .connected: "Connected"
@@ -458,24 +523,36 @@ extension GeneralSettings {
    func testRemote() async {
        self.remoteStatus = .checking
        let settings = CommandResolver.connectionSettings()
-        guard !settings.target.isEmpty else {
-            self.remoteStatus = .failed("Set an SSH target first")
-            return
+        if self.state.remoteTransport == .direct {
+            let trimmedUrl = self.state.remoteUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmedUrl.isEmpty else {
+                self.remoteStatus = .failed("Set a gateway URL first")
+                return
+            }
+            guard Self.isValidWsUrl(trimmedUrl) else {
+                self.remoteStatus = .failed("Gateway URL must start with ws:// or wss://")
+                return
+            }
+        } else {
+            guard !settings.target.isEmpty else {
+                self.remoteStatus = .failed("Set an SSH target first")
+                return
+            }
+
+            // Step 1: basic SSH reachability check
+            let sshResult = await ShellExecutor.run(
+                command: Self.sshCheckCommand(target: settings.target, identity: settings.identity),
+                cwd: nil,
+                env: nil,
+                timeout: 8)
+
+            guard sshResult.ok else {
+                self.remoteStatus = .failed(self.formatSSHFailure(sshResult, target: settings.target))
+                return
+            }
        }

-        // Step 1: basic SSH reachability check
-        let sshResult = await ShellExecutor.run(
-            command: Self.sshCheckCommand(target: settings.target, identity: settings.identity),
-            cwd: nil,
-            env: nil,
-            timeout: 8)
-
-        guard sshResult.ok else {
-            self.remoteStatus = .failed(self.formatSSHFailure(sshResult, target: settings.target))
-            return
-        }
-
-        // Step 2: control channel health over tunnel
+        // Step 2: control channel health check
        let originalMode = AppStateStore.shared.connectionMode
        do {
            try await ControlChannel.shared.configure(mode: .remote(
@@ -502,6 +579,14 @@ extension GeneralSettings {
        }
    }

+    private static func isValidWsUrl(_ raw: String) -> Bool {
+        guard let url = URL(string: raw.trimmingCharacters(in: .whitespacesAndNewlines)) else { return false }
+        let scheme = url.scheme?.lowercased() ?? ""
+        guard scheme == "ws" || scheme == "wss" else { return false }
+        let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return !host.isEmpty
+    }
+
    private static func sshCheckCommand(target: String, identity: String) -> [String] {
        var args: [String] = [
            "/usr/bin/ssh",
@@ -570,12 +655,18 @@ extension GeneralSettings {
        let host = gateway.tailnetDns ?? gateway.lanHost
        guard let host else { return }
        let user = NSUserName()
-        self.state.remoteTarget = GatewayDiscoveryModel.buildSSHTarget(
-            user: user,
-            host: host,
-            port: gateway.sshPort)
-        self.state.remoteCliPath = gateway.cliPath ?? ""
-        ClawdbotConfigFile.setRemoteGatewayUrl(host: host, port: gateway.gatewayPort)
+        if self.state.remoteTransport == .direct {
+            if let url = GatewayDiscoveryHelpers.directUrl(for: gateway) {
+                self.state.remoteUrl = url
+            }
+        } else {
+            self.state.remoteTarget = GatewayDiscoveryModel.buildSSHTarget(
+                user: user,
+                host: host,
+                port: gateway.sshPort)
+            self.state.remoteCliPath = gateway.cliPath ?? ""
+            ClawdbotConfigFile.setRemoteGatewayUrl(host: host, port: gateway.gatewayPort)
+        }
    }
 }

@@ -598,7 +689,9 @@ extension GeneralSettings {
    static func exerciseForTesting() {
        let state = AppState(preview: true)
        state.connectionMode = .remote
+        state.remoteTransport = .ssh
        state.remoteTarget = "user@host:2222"
+        state.remoteUrl = "wss://gateway.example.ts.net"
        state.remoteIdentity = "/tmp/id_ed25519"
        state.remoteProjectRoot = "/tmp/clawdbot"
        state.remoteCliPath = "/tmp/clawdbot"
@@ -1,4 +1,5 @@
 import AppKit
+import Foundation
 import Observation
 import SwiftUI

@@ -517,11 +518,25 @@ extension MenuSessionsInjector {
        switch mode {
        case .remote:
            platform = "remote"
-            let target = AppStateStore.shared.remoteTarget
-            if let parsed = CommandResolver.parseSSHTarget(target) {
-                host = parsed.port == 22 ? parsed.host : "\(parsed.host):\(parsed.port)"
+            if AppStateStore.shared.remoteTransport == .direct {
+                let trimmedUrl = AppStateStore.shared.remoteUrl
+                    .trimmingCharacters(in: .whitespacesAndNewlines)
+                if let url = URL(string: trimmedUrl), let urlHost = url.host, !urlHost.isEmpty {
+                    if let port = url.port {
+                        host = "\(urlHost):\(port)"
+                    } else {
+                        host = urlHost
+                    }
+                } else {
+                    host = trimmedUrl.nonEmpty
+                }
            } else {
-                host = target.nonEmpty
+                let target = AppStateStore.shared.remoteTarget
+                if let parsed = CommandResolver.parseSSHTarget(target) {
+                    host = parsed.port == 22 ? parsed.host : "\(parsed.host):\(parsed.port)"
+                } else {
+                    host = target.nonEmpty
+                }
            }
        case .local:
            platform = "local"
@@ -25,7 +25,11 @@ extension OnboardingView {
        self.preferredGatewayID = gateway.stableID
        GatewayDiscoveryPreferences.setPreferredStableID(gateway.stableID)

-        if let host = gateway.tailnetDns ?? gateway.lanHost {
+        if self.state.remoteTransport == .direct {
+            if let url = GatewayDiscoveryHelpers.directUrl(for: gateway) {
+                self.state.remoteUrl = url
+            }
+        } else if let host = GatewayDiscoveryHelpers.sanitizedTailnetHost(gateway.tailnetDns) ?? gateway.lanHost {
            let user = NSUserName()
            self.state.remoteTarget = GatewayDiscoveryModel.buildSSHTarget(
                user: user,
@@ -177,42 +177,67 @@ extension OnboardingView {
                        VStack(alignment: .leading, spacing: 10) {
                            Grid(alignment: .leading, horizontalSpacing: 12, verticalSpacing: 8) {
                                GridRow {
-                                    Text("SSH target")
+                                    Text("Transport")
                                        .font(.callout.weight(.semibold))
                                        .frame(width: labelWidth, alignment: .leading)
-                                    TextField("user@host[:port]", text: self.$state.remoteTarget)
-                                        .textFieldStyle(.roundedBorder)
-                                        .frame(width: fieldWidth)
+                                    Picker("Transport", selection: self.$state.remoteTransport) {
+                                        Text("SSH tunnel").tag(AppState.RemoteTransport.ssh)
+                                        Text("Direct (ws/wss)").tag(AppState.RemoteTransport.direct)
+                                    }
+                                    .pickerStyle(.segmented)
+                                    .frame(width: fieldWidth)
                                }
-                                GridRow {
-                                    Text("Identity file")
-                                        .font(.callout.weight(.semibold))
-                                        .frame(width: labelWidth, alignment: .leading)
-                                    TextField("/Users/you/.ssh/id_ed25519", text: self.$state.remoteIdentity)
-                                        .textFieldStyle(.roundedBorder)
-                                        .frame(width: fieldWidth)
+                                if self.state.remoteTransport == .direct {
+                                    GridRow {
+                                        Text("Gateway URL")
+                                            .font(.callout.weight(.semibold))
+                                            .frame(width: labelWidth, alignment: .leading)
+                                        TextField("wss://gateway.example.ts.net", text: self.$state.remoteUrl)
+                                            .textFieldStyle(.roundedBorder)
+                                            .frame(width: fieldWidth)
+                                    }
                                }
-                                GridRow {
-                                    Text("Project root")
-                                        .font(.callout.weight(.semibold))
-                                        .frame(width: labelWidth, alignment: .leading)
-                                    TextField("/home/you/Projects/clawdbot", text: self.$state.remoteProjectRoot)
-                                        .textFieldStyle(.roundedBorder)
-                                        .frame(width: fieldWidth)
-                                }
-                                GridRow {
-                                    Text("CLI path")
-                                        .font(.callout.weight(.semibold))
-                                        .frame(width: labelWidth, alignment: .leading)
-                                    TextField(
-                                        "/Applications/Clawdbot.app/.../clawdbot",
-                                        text: self.$state.remoteCliPath)
-                                        .textFieldStyle(.roundedBorder)
-                                        .frame(width: fieldWidth)
+                                if self.state.remoteTransport == .ssh {
+                                    GridRow {
+                                        Text("SSH target")
+                                            .font(.callout.weight(.semibold))
+                                            .frame(width: labelWidth, alignment: .leading)
+                                        TextField("user@host[:port]", text: self.$state.remoteTarget)
+                                            .textFieldStyle(.roundedBorder)
+                                            .frame(width: fieldWidth)
+                                    }
+                                    GridRow {
+                                        Text("Identity file")
+                                            .font(.callout.weight(.semibold))
+                                            .frame(width: labelWidth, alignment: .leading)
+                                        TextField("/Users/you/.ssh/id_ed25519", text: self.$state.remoteIdentity)
+                                            .textFieldStyle(.roundedBorder)
+                                            .frame(width: fieldWidth)
+                                    }
+                                    GridRow {
+                                        Text("Project root")
+                                            .font(.callout.weight(.semibold))
+                                            .frame(width: labelWidth, alignment: .leading)
+                                        TextField("/home/you/Projects/clawdbot", text: self.$state.remoteProjectRoot)
+                                            .textFieldStyle(.roundedBorder)
+                                            .frame(width: fieldWidth)
+                                    }
+                                    GridRow {
+                                        Text("CLI path")
+                                            .font(.callout.weight(.semibold))
+                                            .frame(width: labelWidth, alignment: .leading)
+                                        TextField(
+                                            "/Applications/Clawdbot.app/.../clawdbot",
+                                            text: self.$state.remoteCliPath)
+                                            .textFieldStyle(.roundedBorder)
+                                            .frame(width: fieldWidth)
+                                    }
                                }
                            }

-                            Text("Tip: keep Tailscale enabled so your gateway stays reachable.")
+                            Text(self.state.remoteTransport == .direct
+                                ? "Tip: use Tailscale Serve so the gateway has a valid HTTPS cert."
+                                : "Tip: keep Tailscale enabled so your gateway stays reachable.")
                                .font(.footnote)
                                .foregroundStyle(.secondary)
                                .lineLimit(1)
@@ -225,7 +250,10 @@ extension OnboardingView {
    }

    func gatewaySubtitle(for gateway: GatewayDiscoveryModel.DiscoveredGateway) -> String? {
-        if let host = gateway.tailnetDns ?? gateway.lanHost {
+        if self.state.remoteTransport == .direct {
+            return GatewayDiscoveryHelpers.directUrl(for: gateway) ?? "Gateway pairing only"
+        }
+        if let host = GatewayDiscoveryHelpers.sanitizedTailnetHost(gateway.tailnetDns) ?? gateway.lanHost {
            let portSuffix = gateway.sshPort != 22 ? " · ssh \(gateway.sshPort)" : ""
            return "\(host)\(portSuffix)"
        }
@@ -175,4 +175,10 @@ import Testing
            customBindHost: "192.168.1.10")
        #expect(host == "192.168.1.10")
    }
+
+    @Test func normalizeGatewayUrlAddsDefaultPortForWs() {
+        let url = GatewayRemoteConfig.normalizeGatewayUrl("ws://gateway")
+        #expect(url?.port == 18789)
+        #expect(url?.absoluteString == "ws://gateway:18789")
+    }
 }
@@ -75,10 +75,10 @@ export AWS_BEARER_TOKEN_BEDROCK="..."
        auth: "aws-sdk",
        models: [
          {
-            id: "anthropic.claude-3-7-sonnet-20250219-v1:0",
-            name: "Claude 3.7 Sonnet (Bedrock)",
+            id: "anthropic.claude-opus-4-5-20251101-v1:0",
+            name: "Claude Opus 4.5 (Bedrock)",
            reasoning: true,
-            input: ["text"],
+            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192
@@ -89,12 +89,75 @@ export AWS_BEARER_TOKEN_BEDROCK="..."
  },
  agents: {
    defaults: {
-      model: { primary: "amazon-bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0" }
+      model: { primary: "amazon-bedrock/anthropic.claude-opus-4-5-20251101-v1:0" }
    }
  }
 }
 ```

+## EC2 Instance Roles
+
+When running Clawdbot on an EC2 instance with an IAM role attached, the AWS SDK
+will automatically use the instance metadata service (IMDS) for authentication.
+However, Clawdbot's credential detection currently only checks for environment
+variables, not IMDS credentials.
+
+**Workaround:** Set `AWS_PROFILE=default` to signal that AWS credentials are
+available. The actual authentication still uses the instance role via IMDS.
+
+```bash
+# Add to ~/.bashrc or your shell profile
+export AWS_PROFILE=default
+export AWS_REGION=us-east-1
+```
+
+**Required IAM permissions** for the EC2 instance role:
+- `bedrock:InvokeModel`
+- `bedrock:InvokeModelWithResponseStream`
+- `bedrock:ListFoundationModels` (for automatic discovery)
+
+Or attach the managed policy `AmazonBedrockFullAccess`.
+
+**Quick setup:**
+
+```bash
+# 1. Create IAM role and instance profile
+aws iam create-role --role-name EC2-Bedrock-Access \
+  --assume-role-policy-document '{
+    "Version": "2012-10-17",
+    "Statement": [{
+      "Effect": "Allow",
+      "Principal": {"Service": "ec2.amazonaws.com"},
+      "Action": "sts:AssumeRole"
+    }]
+  }'
+
+aws iam attach-role-policy --role-name EC2-Bedrock-Access \
+  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess
+
+aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
+aws iam add-role-to-instance-profile \
+  --instance-profile-name EC2-Bedrock-Access \
+  --role-name EC2-Bedrock-Access
+
+# 2. Attach to your EC2 instance
+aws ec2 associate-iam-instance-profile \
+  --instance-id i-xxxxx \
+  --iam-instance-profile Name=EC2-Bedrock-Access
+
+# 3. On the EC2 instance, enable discovery
+clawdbot config set models.bedrockDiscovery.enabled true
+clawdbot config set models.bedrockDiscovery.region us-east-1
+
+# 4. Set the workaround env vars
+echo 'export AWS_PROFILE=default' >> ~/.bashrc
+echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
+source ~/.bashrc
+
+# 5. Verify models are discovered
+clawdbot models list
+```
+
 ## Notes

 - Bedrock requires **model access** enabled in your AWS account/region.
@@ -236,6 +236,30 @@ MiniMax is configured via `models.providers` because it uses custom endpoints:

 See [/providers/minimax](/providers/minimax) for setup details, model options, and config snippets.

+### Ollama
+
+Ollama is a local LLM runtime that provides an OpenAI-compatible API:
+
+- Provider: `ollama`
+- Auth: `OLLAMA_API_KEY` (any value; Ollama runs locally)
+- Example model: `ollama/llama3.3`
+- Installation: https://ollama.ai
+
+```bash
+# Install Ollama, then pull a model:
+ollama pull llama3.3
+```
+
+```json5
+{
+  agents: {
+    defaults: { model: { primary: "ollama/llama3.3" } }
+  }
+}
+```
+
+Ollama is auto-discovered when `OLLAMA_API_KEY` (or an auth profile) is set and no explicit `models.providers.ollama` entry exists. Discovery probes `http://127.0.0.1:11434` and filters to tool-capable models. See [/providers/ollama](/providers/ollama) for model recommendations and custom configuration.
+
 ### Local proxies (LM Studio, vLLM, LiteLLM, etc.)

 Example (OpenAI‑compatible):
@@ -2825,13 +2825,14 @@ Auth and Tailscale:

 Remote client defaults (CLI):
 - `gateway.remote.url` sets the default Gateway WebSocket URL for CLI calls when `gateway.mode = "remote"`.
+- `gateway.remote.transport` selects the macOS remote transport (`ssh` default, `direct` for ws/wss). When `direct`, `gateway.remote.url` must be `ws://` or `wss://`. `ws://host` defaults to port `18789`.
 - `gateway.remote.token` supplies the token for remote calls (leave unset for no auth).
 - `gateway.remote.password` supplies the password for remote calls (leave unset for no auth).

 macOS app behavior:
 - Clawdbot.app watches `~/.clawdbot/clawdbot.json` and switches modes live when `gateway.mode` or `gateway.remote.url` changes.
 - If `gateway.mode` is unset but `gateway.remote.url` is set, the macOS app treats it as remote mode.
- When you change connection mode in the macOS app, it writes `gateway.mode` (and `gateway.remote.url` in remote mode) back to the config file.
+- When you change connection mode in the macOS app, it writes `gateway.mode` (and `gateway.remote.url` + `gateway.remote.transport` in remote mode) back to the config file.

 ```json5
 {
@@ -2846,6 +2847,21 @@ macOS app behavior:
 }
 ```

+Direct transport example (macOS app):
+
+```json5
+{
+  gateway: {
+    mode: "remote",
+    remote: {
+      transport: "direct",
+      url: "wss://gateway.example.ts.net",
+      token: "your-token"
+    }
+  }
+}
+```
+
 ### `gateway.reload` (Config hot reload)

 The Gateway watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`) and applies changes automatically.
@@ -9,6 +9,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,

 - [What is Clawdbot?](#what-is-clawdbot)
  - [What is Clawdbot, in one paragraph?](#what-is-clawdbot-in-one-paragraph)
+  - [What’s the value proposition?](#whats-the-value-proposition)
 - [Quick start and first-run setup](#quick-start-and-first-run-setup)
  - [What’s the recommended way to install and set up Clawdbot?](#whats-the-recommended-way-to-install-and-set-up-clawdbot)
  - [How do I open the dashboard after onboarding?](#how-do-i-open-the-dashboard-after-onboarding)
@@ -18,10 +19,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Can I migrate my setup to a new machine (Mac mini) without redoing onboarding?](#can-i-migrate-my-setup-to-a-new-machine-mac-mini-without-redoing-onboarding)
  - [Where do I see what’s new in the latest version?](#where-do-i-see-whats-new-in-the-latest-version)
  - [I can't access docs.clawd.bot (SSL error). What now?](#i-cant-access-docsclawdbot-ssl-error-what-now)
+  - [What’s the difference between stable and beta?](#whats-the-difference-between-stable-and-beta)
  - [How do I install the beta version, and what’s the difference between beta and dev?](#how-do-i-install-the-beta-version-and-whats-the-difference-between-beta-and-dev)
  - [The docs didn’t answer my question — how do I get a better answer?](#the-docs-didnt-answer-my-question--how-do-i-get-a-better-answer)
+  - [How do I install Clawdbot on Linux?](#how-do-i-install-clawdbot-on-linux)
  - [How do I install Clawdbot on a VPS?](#how-do-i-install-clawdbot-on-a-vps)
+  - [Can I ask Clawd to update itself?](#can-i-ask-clawd-to-update-itself)
  - [What does the onboarding wizard actually do?](#what-does-the-onboarding-wizard-actually-do)
+  - [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this)
  - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setup-token-auth-work)
  - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setup-token)
  - [Do you support Claude subscription auth (Claude Code OAuth)?](#do-you-support-claude-subscription-auth-claude-code-oauth)
@@ -32,11 +37,13 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Is a local model OK for casual chats?](#is-a-local-model-ok-for-casual-chats)
  - [How do I keep hosted model traffic in a specific region?](#how-do-i-keep-hosted-model-traffic-in-a-specific-region)
  - [Do I have to buy a Mac Mini to install this?](#do-i-have-to-buy-a-mac-mini-to-install-this)
+  - [Do I need a Mac mini for iMessage support?](#do-i-need-a-mac-mini-for-imessage-support)
  - [Can I use Bun?](#can-i-use-bun)
  - [Telegram: what goes in `allowFrom`?](#telegram-what-goes-in-allowfrom)
  - [Can multiple people use one WhatsApp number with different Clawdbots?](#can-multiple-people-use-one-whatsapp-number-with-different-clawdbots)
  - [Can I run a "fast chat" agent and an "Opus for coding" agent?](#can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent)
  - [Does Homebrew work on Linux?](#does-homebrew-work-on-linux)
+  - [What’s the difference between the hackable (git) install and npm install?](#whats-the-difference-between-the-hackable-git-install-and-npm-install)
  - [Can I switch between npm and git installs later?](#can-i-switch-between-npm-and-git-installs-later)
  - [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps)
 - [Skills and automation](#skills-and-automation)
@@ -56,6 +63,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
 - [Where things live on disk](#where-things-live-on-disk)
  - [Where does Clawdbot store its data?](#where-does-clawdbot-store-its-data)
  - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd--soulmd--usermd--memorymd-live)
+  - [What’s the recommended backup strategy?](#whats-the-recommended-backup-strategy)
  - [How do I completely uninstall Clawdbot?](#how-do-i-completely-uninstall-clawdbot)
  - [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace)
  - [I’m in remote mode — where is the session store?](#im-in-remote-mode-where-is-the-session-store)
@@ -96,6 +104,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
 - [Models: defaults, selection, aliases, switching](#models-defaults-selection-aliases-switching)
  - [What is the “default model”?](#what-is-the-default-model)
  - [What model do you recommend?](#what-model-do-you-recommend)
+  - [What do Clawd, Flawd, and Krill use for models?](#what-do-clawd-flawd-and-krill-use-for-models)
  - [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting)
  - [Why do I see “Model … is not allowed” and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply)
  - [Why do I see “Unknown model: minimax/MiniMax-M2.1”?](#why-do-i-see-unknown-model-minimaxminimax-m21)
@@ -196,6 +205,28 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,

 Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product.

+### What’s the value proposition?
+
+Clawdbot is not “just a Claude wrapper.” It’s a **local-first control plane** that lets you run a
+capable assistant on **your own hardware**, reachable from the chat apps you already use, with
+stateful sessions, memory, and tools — without handing control of your workflows to a hosted
+SaaS.
+
+Highlights:
+- **Your devices, your data:** run the Gateway wherever you want (Mac, Linux, VPS) and keep the
+  workspace + session history local.  
+- **Real channels, not a web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc,
+  plus mobile voice and Canvas on supported platforms.  
+- **Model-agnostic:** use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per‑agent routing
+  and failover.  
+- **Local-only option:** run local models so **all data can stay on your device** if you want.
+- **Multi-agent routing:** separate agents per channel, account, or task, each with its own
+  workspace and defaults.  
+- **Open source and hackable:** inspect, extend, and self-host without vendor lock‑in.
+
+Docs: [Gateway](/gateway), [Channels](/channels), [Multi‑agent](/concepts/multi-agent),
+[Memory](/concepts/memory).
+
 ## Quick start and first-run setup

 ### What’s the recommended way to install and set up Clawdbot?
@@ -254,7 +285,9 @@ not a hard minimum.

 ### Can I migrate my setup to a new machine (Mac mini) without redoing onboarding?

-Yes. Copy the **state directory** and **workspace**, then run Doctor once:
+Yes. Copy the **state directory** and **workspace**, then run Doctor once. This
+keeps your bot “exactly the same” (memory, session history, auth, and channel
+state) as long as you copy **both** locations:

 1) Install Clawdbot on the new machine.
 2) Copy `$CLAWDBOT_STATE_DIR` (default: `~/.clawdbot`) from the old machine.
@@ -264,6 +297,10 @@ Yes. Copy the **state directory** and **workspace**, then run Doctor once:
 That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you’re in
 remote mode, remember the gateway host owns the session store and workspace.

+**Important:** if you only commit/push your workspace to GitHub, you’re backing
+up **memory + bootstrap files**, but **not** session history or auth. Those live
+under `~/.clawdbot/` (for example `~/.clawdbot/agents/<agentId>/sessions/`).
+
 Related: [Where things live on disk](/help/faq#where-does-clawdbot-store-its-data),
 [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor),
 [Remote mode](/gateway/remote).
@@ -282,13 +319,27 @@ section is the latest shipped version. Entries are grouped by **Highlights**, **
 Some Comcast/Xfinity connections incorrectly block `docs.clawd.bot` via Xfinity
 Advanced Security. Disable it or allowlist `docs.clawd.bot`, then retry. More
 detail: [Troubleshooting](/help/troubleshooting#docsclawdbot-shows-an-ssl-error-comcastxfinity).
+Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_status.

 If you still can't reach the site, the docs are mirrored on GitHub:
 https://github.com/clawdbot/clawdbot/tree/main/docs

+### What’s the difference between stable and beta?
+
+**Stable** and **beta** are **npm dist‑tags**, not separate code lines:
+- `latest` = stable
+- `beta` = early build for testing
+
+We ship builds to **beta**, test them, and once a build is solid we **promote
+that same version to `latest`**. That’s why beta and stable can point at the
+**same version**.
+
+See what changed:  
+https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md
+
 ### How do I install the beta version, and what’s the difference between beta and dev?

-**Beta** is a prerelease tag (`vYYYY.M.D-beta.N`) published to the npm dist‑tag `beta`.  
+**Beta** is the npm dist‑tag `beta` (may match `latest`).  
 **Dev** is the moving head of `main` (git); when published, it uses the npm dist‑tag `dev`.

 One‑liners (macOS/Linux):
@@ -317,6 +368,14 @@ curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git

 More detail: [Install](/install) and [Installer flags](/install/installer).

+### How do I install Clawdbot on Linux?
+
+Short answer: follow the Linux guide, then run the onboarding wizard.
+
+- Linux quick path + service install: [Linux](/platforms/linux).
+- Full walkthrough: [Getting Started](/start/getting-started).
+- Installer + updates: [Install & updates](/install/updating).
+
 ### How do I install Clawdbot on a VPS?

 Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.
@@ -324,6 +383,31 @@ Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the
 Guides: [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [Fly.io](/platforms/fly).  
 Remote access: [Gateway remote](/gateway/remote).

+### Can I ask Clawd to update itself?
+
+Short answer: **possible, not recommended**. The update flow can restart the
+Gateway (which drops the active session), may need a clean git checkout, and
+can prompt for confirmation. Safer: run updates from a shell as the operator.
+
+Use the CLI:
+
+```bash
+clawdbot update
+clawdbot update status
+clawdbot update --channel stable|beta|dev
+clawdbot update --tag <dist-tag|version>
+clawdbot update --no-restart
+```
+
+If you must automate from an agent:
+
+```bash
+clawdbot update --yes --no-restart
+clawdbot gateway restart
+```
+
+Docs: [Update](/cli/update), [Updating](/install/updating).
+
 ### What does the onboarding wizard actually do?

 `clawdbot onboard` is the recommended setup path. In **local mode** it walks you through:
@@ -337,6 +421,15 @@ Remote access: [Gateway remote](/gateway/remote).

 It also warns if your configured model is unknown or missing auth.

+### Do I need a Claude or OpenAI subscription to run this?
+
+No. You can run Clawdbot with **API keys** (Anthropic/OpenAI/others) or with
+**local‑only models** so your data stays on your device. Subscriptions (Claude
+Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
+
+Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),
+[Local models](/gateway/local-models), [Models](/concepts/models).
+
 ### How does Anthropic "setup-token" auth work?

 `claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. If Claude Code CLI credentials are present on the gateway host, Clawdbot can reuse them; otherwise choose **Anthropic token (paste setup-token)** and paste the string. The token is stored as an auth profile for the **anthropic** provider and used like an API key or OAuth profile. More detail: [OAuth](/concepts/oauth).
@@ -406,6 +499,20 @@ If you want other macOS‑only tools, run the Gateway on a Mac or pair a macOS n

 Docs: [iMessage](/channels/imessage), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).

+### Do I need a Mac mini for iMessage support?
+
+You need **some macOS device** signed into Messages. It does **not** have to be a Mac mini —
+any Mac works. Clawdbot’s iMessage integrations run on macOS (BlueBubbles or `imsg`), while
+the Gateway can run elsewhere.
+
+Common setups:
+- Run the Gateway on Linux/VPS, and point `channels.imessage.cliPath` at an SSH wrapper that
+  runs `imsg` on the Mac.
+- Run everything on the Mac if you want the simplest single‑machine setup.
+
+Docs: [iMessage](/channels/imessage), [BlueBubbles](/channels/bluebubbles),
+[Mac remote mode](/platforms/mac/remote).
+
 ### Can I use Bun?

 Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.
@@ -451,6 +558,15 @@ brew install <formula>
 If you run Clawdbot via systemd, ensure the service PATH includes `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools resolve in non‑login shells.
 Recent builds also prepend common user bin dirs on Linux systemd services (for example `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set.

+### What’s the difference between the hackable (git) install and npm install?
+
+- **Hackable (git) install:** full source checkout, editable, best for contributors.
+  You run builds locally and can patch code/docs.
+- **npm install:** global CLI install, no repo, best for “just run it.”
+  Updates come from npm dist‑tags.
+
+Docs: [Getting started](/start/getting-started), [Updating](/install/updating).
+
 ### Can I switch between npm and git installs later?

 Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.
@@ -706,6 +822,18 @@ workspace, not your local laptop).

 See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory).

+### What’s the recommended backup strategy?
+
+Put your **agent workspace** in a **private** git repo and back it up somewhere
+private (for example GitHub private). This captures memory + AGENTS/SOUL/USER
+files, and lets you restore the assistant’s “mind” later.
+
+Do **not** commit anything under `~/.clawdbot` (credentials, sessions, tokens).
+If you need a full restore, back up both the workspace and the state directory
+separately (see the migration question above).
+
+Docs: [Agent workspace](/concepts/agent-workspace).
+
 ### How do I completely uninstall Clawdbot?

 See the dedicated guide: [Uninstall](/install/uninstall).
@@ -1220,6 +1348,11 @@ injection and unsafe behavior. See [Security](/gateway/security).

 More context: [Models](/concepts/models).

+### What do Clawd, Flawd, and Krill use for models?
+
+- **Clawd + Flawd:** Anthropic Opus (`anthropic/claude-opus-4-5`) — see [Anthropic](/providers/anthropic).
+- **Krill:** MiniMax M2.1 (`minimax/MiniMax-M2.1`) — see [MiniMax](/providers/minimax).
+
 ### How do I switch models on the fly (without restarting)?

 Use the `/model` command as a standalone message:
@@ -11,10 +11,13 @@ Last updated: 2026-01-21

 Clawdbot ships three update channels:

- **stable**: tagged releases (`vYYYY.M.D` or `vYYYY.M.D-<patch>`). npm dist-tag: `latest`.
- **beta**: prerelease tags (`vYYYY.M.D-beta.N`). npm dist-tag: `beta`.
+- **stable**: npm dist-tag `latest`.
+- **beta**: npm dist-tag `beta` (builds under test).
 - **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).

+We ship builds to **beta**, test them, then **promote a vetted build to `latest`**
+without changing the version number — dist-tags are the source of truth for npm installs.
+
 ## Switching channels

 Git checkout:
@@ -25,7 +28,7 @@ clawdbot update --channel beta
 clawdbot update --channel dev
 ```

- `stable`/`beta` check out the latest matching tag.
+- `stable`/`beta` check out the latest matching tag (often the same tag).
 - `dev` switches to `main` and rebases on the upstream.

 npm/pnpm global install:
@@ -56,12 +59,11 @@ When you switch channels with `clawdbot update`, Clawdbot also syncs plugin sour

 ## Tagging best practices

- Stable: tag each release (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).
- Beta: use `vYYYY.M.D-beta.N` (increment `N`).
+- Tag releases you want git checkouts to land on (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).
 - Keep tags immutable: never move or reuse a tag.
- Publish dist-tags alongside git tags:
+- npm dist-tags remain the source of truth for npm installs:
  - `latest` → stable
-  - `beta` → prerelease
+  - `beta` → candidate build
  - `dev` → main snapshot (optional)

 ## macOS app availability
@@ -35,6 +35,7 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi
 - [Z.AI](/providers/zai)
 - [GLM models](/providers/glm)
 - [MiniMax](/providers/minimax)
+- [Ollama (local models)](/providers/ollama)

 ## Transcription providers

@@ -0,0 +1,171 @@
+---
+summary: "Run Clawdbot with Ollama (local LLM runtime)"
+read_when:
+  - You want to run Clawdbot with local models via Ollama
+  - You need Ollama setup and configuration guidance
+---
+# Ollama
+
+Ollama is a local LLM runtime that makes it easy to run open-source models on your machine. Clawdbot integrates with Ollama's OpenAI-compatible API and can **auto-discover tool-capable models** when enabled via `OLLAMA_API_KEY` (or an auth profile) and no explicit `models.providers.ollama` config is set.
+
+## Quick start
+
+1) Install Ollama: https://ollama.ai
+
+2) Pull a model:
+
+```bash
+ollama pull llama3.3
+# or
+ollama pull qwen2.5-coder:32b
+# or
+ollama pull deepseek-r1:32b
+```
+
+3) Enable Ollama for Clawdbot (any value works; Ollama doesn't require a real key):
+
+```bash
+# Set environment variable
+export OLLAMA_API_KEY="ollama-local"
+
+# Or configure in your config file
+clawdbot config set models.providers.ollama.apiKey "ollama-local"
+```
+
+4) Use Ollama models:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "ollama/llama3.3" }
+    }
+  }
+}
+```
+
+## Model Discovery
+
+When Ollama is enabled via `OLLAMA_API_KEY` (or an auth profile) and no explicit `models.providers.ollama` entry exists, Clawdbot automatically detects models installed on your Ollama instance by querying `/api/tags` and `/api/show` at `http://localhost:11434`. It only keeps models that report tool support, so you don't need to manually configure them.
+
+To see what models are available:
+
+```bash
+ollama list
+clawdbot models list
+```
+
+To add a new model, simply pull it with Ollama:
+
+```bash
+ollama pull mistral
+```
+
+The new model will be automatically discovered and available to use.
+
+If you set `models.providers.ollama` explicitly, auto-discovery is skipped. Define your models manually in that case.
+
+## Configuration
+
+### Basic Setup
+
+The simplest way to enable Ollama is via environment variable:
+
+```bash
+export OLLAMA_API_KEY="ollama-local"
+```
+
+### Custom Base URL
+
+If Ollama is running on a different host or port (note: explicit config skips auto-discovery, so define models manually):
+
+```json5
+{
+  models: {
+    providers: {
+      ollama: {
+        apiKey: "ollama-local",
+        baseUrl: "http://192.168.1.100:11434/v1"
+      }
+    }
+  }
+}
+```
+
+### Model Selection
+
+Once configured, all your Ollama models are available:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: {
+        primary: "ollama/llama3.3",
+        fallback: ["ollama/qwen2.5-coder:32b"]
+      }
+    }
+  }
+}
+```
+
+## Advanced
+
+### Reasoning Models
+
+Models with "r1" or "reasoning" in their name are automatically detected as reasoning models and will use extended thinking features:
+
+```bash
+ollama pull deepseek-r1:32b
+```
+
+### Model Costs
+
+Ollama is free and runs locally, so all model costs are set to $0.
+
+### Context Windows
+
+Ollama models use default context windows. You can customize these in your provider configuration if needed.
+
+## Troubleshooting
+
+### Ollama not detected
+
+Make sure Ollama is running:
+
+```bash
+ollama serve
+```
+
+And that the API is accessible:
+
+```bash
+curl http://localhost:11434/api/tags
+```
+
+### No models available
+
+Pull at least one model:
+
+```bash
+ollama list  # See what's installed
+ollama pull llama3.3  # Pull a model
+```
+
+### Connection refused
+
+Check that Ollama is running on the correct port:
+
+```bash
+# Check if Ollama is running
+ps aux | grep ollama
+
+# Or restart Ollama
+ollama serve
+```
+
+## See Also
+
+- [Model Providers](/concepts/model-providers) - Overview of all providers
+- [Model Selection](/agents/model-selection) - How to choose models
+- [Configuration](/configuration) - Full config reference
@@ -6,9 +6,10 @@ read_when:
 # Elevated Mode (/elevated directives)

 ## What it does
- `/elevated on` is a **shortcut** for `exec.host=gateway` + `exec.security=full` (approvals still apply).
+- `/elevated on` runs on the gateway host and keeps exec approvals (same as `/elevated ask`).
 - `/elevated full` runs on the gateway host **and** auto-approves exec (skips exec approvals).
 - `/elevated ask` runs on the gateway host but keeps exec approvals (same as `/elevated on`).
+- `on`/`ask` do **not** force `exec.security=full`; configured security/ask policy still applies.
 - Only changes behavior when the agent is **sandboxed** (otherwise exec already runs on the host).
 - Directive forms: `/elevated on|off|ask|full`, `/elev on|off|ask|full`.
 - Only `on|off|ask|full` are accepted; anything else returns a hint and does not change state.
@@ -18,8 +19,8 @@ read_when:
 - **Per-session state**: `/elevated on|off|ask|full` sets the elevated level for the current session key.
 - **Inline directive**: `/elevated on|ask|full` inside a message applies to that message only.
 - **Groups**: In group chats, elevated directives are only honored when the agent is mentioned. Command-only messages that bypass mention requirements are treated as mentioned.
- **Host execution**: elevated forces `exec` onto the gateway host with full security.
- **Approvals**: `full` skips exec approvals; `on`/`ask` still honor them.
+- **Host execution**: elevated forces `exec` onto the gateway host; `full` also sets `security=full`.
+- **Approvals**: `full` skips exec approvals; `on`/`ask` honor them when allowlist/ask rules require.
 - **Unsandboxed agents**: no-op for location; only affects gating, logging, and status.
 - **Tool policy still applies**: if `exec` is denied by tool policy, elevated cannot be used.

@@ -157,6 +157,36 @@ Actions:
 - **Always allow** → add to allowlist + run
 - **Deny** → block

+## Approval forwarding to chat channels
+
+You can forward exec approval prompts to any chat channel (including plugin channels) and approve
+them with `/approve`. This uses the normal outbound delivery pipeline.
+
+Config:
+```json5
+{
+  approvals: {
+    exec: {
+      enabled: true,
+      mode: "session", // "session" | "targets" | "both"
+      agentFilter: ["main"],
+      sessionFilter: ["discord"], // substring or regex
+      targets: [
+        { channel: "slack", to: "U12345678" },
+        { channel: "telegram", to: "123456789" }
+      ]
+    }
+  }
+}
+```
+
+Reply in chat:
+```
+/approve <id> allow-once
+/approve <id> allow-always
+/approve <id> deny
+```
+
 ### macOS IPC flow
 ```
 Gateway -> Node Service (WS)
@@ -24,7 +24,7 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 - `security` (`deny | allowlist | full`): enforcement mode for `gateway`/`node`
 - `ask` (`off | on-miss | always`): approval prompts for `gateway`/`node`
 - `node` (string): node id/name for `host=node`
- `elevated` (bool): alias for `host=gateway` + `security=full` when sandboxed and allowed
+- `elevated` (bool): request elevated mode (gateway host); `security=full` is only forced when elevated resolves to `full`

 Notes:
 - `host` defaults to `sandbox`.
@@ -61,6 +61,7 @@ Text + native (when enabled):
 - `/skill <name> [input]` (run a skill by name)
 - `/status` (show current status; includes provider usage/quota for the current model provider when available)
 - `/allowlist` (list/add/remove allowlist entries)
+- `/approve <id> allow-once|allow-always|deny` (resolve exec approval prompts)
 - `/context [list|detail|json]` (explain “context”; `detail` shows per-file + per-tool + per-skill + system prompt size)
 - `/whoami` (show your sender id; alias: `/id`)
 - `/subagents list|stop|log|info|send` (inspect, stop, log, or message sub-agent runs for the current session)
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { TlonAuthorizationSchema, TlonConfigSchema } from "./config-schema.js";
+
+describe("Tlon config schema", () => {
+  it("accepts channelRules with string keys", () => {
+    const parsed = TlonAuthorizationSchema.parse({
+      channelRules: {
+        "chat/~zod/test": {
+          mode: "open",
+          allowedShips: ["~zod"],
+        },
+      },
+    });
+
+    expect(parsed.channelRules?.["chat/~zod/test"]?.mode).toBe("open");
+  });
+
+  it("accepts accounts with string keys", () => {
+    const parsed = TlonConfigSchema.parse({
+      accounts: {
+        primary: {
+          ship: "~zod",
+          url: "https://example.com",
+          code: "code-123",
+        },
+      },
+    });
+
+    expect(parsed.accounts?.primary?.ship).toBe("~zod");
+  });
+});
@@ -10,7 +10,7 @@ export const TlonChannelRuleSchema = z.object({
 });

 export const TlonAuthorizationSchema = z.object({
-  channelRules: z.record(TlonChannelRuleSchema).optional(),
+  channelRules: z.record(z.string(), TlonChannelRuleSchema).optional(),
 });

 export const TlonAccountSchema = z.object({
@@ -37,7 +37,7 @@ export const TlonConfigSchema = z.object({
  showModelSignature: z.boolean().optional(),
  authorization: TlonAuthorizationSchema.optional(),
  defaultAuthorizedShips: z.array(ShipSchema).optional(),
-  accounts: z.record(TlonAccountSchema).optional(),
+  accounts: z.record(z.string(), TlonAccountSchema).optional(),
 });

 export const tlonChannelConfigSchema = buildChannelConfigSchema(TlonConfigSchema);
@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@urbit/aura", () => ({
+  scot: vi.fn(() => "mocked-ud"),
+  da: {
+    fromUnix: vi.fn(() => 123n),
+  },
+}));
+
+describe("sendDm", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("uses aura v3 helpers for the DM id", async () => {
+    const { sendDm } = await import("./send.js");
+    const aura = await import("@urbit/aura");
+    const scot = vi.mocked(aura.scot);
+    const fromUnix = vi.mocked(aura.da.fromUnix);
+
+    const sentAt = 1_700_000_000_000;
+    vi.spyOn(Date, "now").mockReturnValue(sentAt);
+
+    const poke = vi.fn(async () => ({}));
+
+    const result = await sendDm({
+      api: { poke },
+      fromShip: "~zod",
+      toShip: "~nec",
+      text: "hi",
+    });
+
+    expect(fromUnix).toHaveBeenCalledWith(sentAt);
+    expect(scot).toHaveBeenCalledWith("ud", 123n);
+    expect(poke).toHaveBeenCalledTimes(1);
+    expect(result.messageId).toBe("~zod/mocked-ud");
+  });
+});
@@ -1,4 +1,4 @@
-import { unixToDa, formatUd } from "@urbit/aura";
+import { scot, da } from "@urbit/aura";

 export type TlonPokeApi = {
  poke: (params: { app: string; mark: string; json: unknown }) => Promise<unknown>;
@@ -14,7 +14,7 @@ type SendTextParams = {
 export async function sendDm({ api, fromShip, toShip, text }: SendTextParams) {
  const story = [{ inline: [text] }];
  const sentAt = Date.now();
-  const idUd = formatUd(unixToDa(sentAt));
+  const idUd = scot('ud', da.fromUnix(sentAt));
  const id = `${fromShip}/${idUd}`;

  const delta = {
@@ -150,4 +150,35 @@ describe("exec approvals", () => {
    expect(result.details.status).toBe("completed");
    expect(calls).not.toContain("exec.approval.request");
  });
+
+  it("requires approval for elevated ask when allowlist misses", async () => {
+    const { callGatewayTool } = await import("./tools/gateway.js");
+    const calls: string[] = [];
+    let resolveApproval: (() => void) | undefined;
+    const approvalSeen = new Promise<void>((resolve) => {
+      resolveApproval = resolve;
+    });
+
+    vi.mocked(callGatewayTool).mockImplementation(async (method) => {
+      calls.push(method);
+      if (method === "exec.approval.request") {
+        resolveApproval?.();
+        return { decision: "deny" };
+      }
+      return { ok: true };
+    });
+
+    const { createExecTool } = await import("./bash-tools.exec.js");
+    const tool = createExecTool({
+      ask: "on-miss",
+      security: "allowlist",
+      approvalRunningNoticeMs: 0,
+      elevated: { enabled: true, allowed: true, defaultLevel: "ask" },
+    });
+
+    const result = await tool.execute("call4", { command: "echo ok", elevated: true });
+    expect(result.details.status).toBe("approval-pending");
+    await approvalSeen;
+    expect(calls).toContain("exec.approval.request");
+  });
 });
@@ -791,7 +791,7 @@ export function createExecTool(
      const configuredSecurity = defaults?.security ?? (host === "sandbox" ? "deny" : "allowlist");
      const requestedSecurity = normalizeExecSecurity(params.security);
      let security = minSecurity(configuredSecurity, requestedSecurity ?? configuredSecurity);
-      if (elevatedRequested) {
+      if (elevatedRequested && elevatedMode === "full") {
        security = "full";
      }
      const configuredAsk = defaults?.ask ?? "on-miss";
@@ -284,6 +284,7 @@ export function resolveEnvApiKey(provider: string): EnvApiKeyResult | null {
    synthetic: "SYNTHETIC_API_KEY",
    mistral: "MISTRAL_API_KEY",
    opencode: "OPENCODE_API_KEY",
+    ollama: "OLLAMA_API_KEY",
  };
  const envVar = envMap[normalized];
  if (!envVar) return null;
@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveImplicitProviders } from "./models-config.providers.js";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+describe("Ollama provider", () => {
+  const previousEnv = { ...process.env };
+
+  afterEach(() => {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in previousEnv)) delete process.env[key];
+    }
+    for (const [key, value] of Object.entries(previousEnv)) {
+      process.env[key] = value;
+    }
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("should not include ollama when no API key is configured", async () => {
+    const agentDir = mkdtempSync(join(tmpdir(), "clawd-test-"));
+    const providers = await resolveImplicitProviders({ agentDir });
+
+    // Ollama requires explicit configuration via OLLAMA_API_KEY env var or profile
+    expect(providers?.ollama).toBeUndefined();
+  });
+
+  it("discovers tool-capable models when OLLAMA_API_KEY is set", async () => {
+    process.env.OLLAMA_API_KEY = "ollama-local";
+    delete process.env.VITEST;
+    process.env.NODE_ENV = "development";
+
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          models: [{ name: "llama3.3" }, { name: "no-tools-model" }],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          capabilities: ["tools", "thinking"],
+          model_info: {
+            "general.architecture": "llama",
+            "llama.context_length": "4096",
+          },
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          capabilities: ["thinking"],
+          model_info: {
+            "general.architecture": "llama",
+            "llama.context_length": "2048",
+          },
+        }),
+      });
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const agentDir = mkdtempSync(join(tmpdir(), "clawd-test-"));
+    const providers = await resolveImplicitProviders({ agentDir });
+
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("http://127.0.0.1:11434/api/tags");
+    expect(fetchMock.mock.calls[1]?.[0]).toBe("http://127.0.0.1:11434/api/show");
+
+    const provider = providers?.ollama;
+    expect(provider?.baseUrl).toBe("http://127.0.0.1:11434/v1");
+    expect(provider?.models).toHaveLength(1);
+    expect(provider?.models?.[0]?.id).toBe("llama3.3");
+    expect(provider?.models?.[0]?.reasoning).toBe(true);
+    expect(provider?.models?.[0]?.contextWindow).toBe(4096);
+    expect(provider?.models?.[0]?.maxTokens).toBe(4096 * 10);
+  });
+
+  it("skips discovery when ollama is explicitly configured", async () => {
+    process.env.OLLAMA_API_KEY = "ollama-local";
+    delete process.env.VITEST;
+    process.env.NODE_ENV = "development";
+
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const agentDir = mkdtempSync(join(tmpdir(), "clawd-test-"));
+    const providers = await resolveImplicitProviders({
+      agentDir,
+      explicitProviders: {
+        ollama: {
+          baseUrl: "http://example.com/v1",
+          api: "openai-completions",
+          models: [],
+        },
+      },
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(providers?.ollama).toBeUndefined();
+  });
+});
@@ -1,9 +1,11 @@
 import type { ClawdbotConfig } from "../config/config.js";
+import type { ModelDefinitionConfig } from "../config/types.models.js";
 import {
  DEFAULT_COPILOT_API_BASE_URL,
  resolveCopilotApiToken,
 } from "../providers/github-copilot-token.js";
 import { ensureAuthProfileStore, listProfilesForProvider } from "./auth-profiles.js";
+import { normalizeProviderId } from "./model-selection.js";
 import { resolveAwsSdkEnvVarName, resolveEnvApiKey } from "./model-auth.js";
 import { discoverBedrockModels } from "./bedrock-discovery.js";
 import {
@@ -62,6 +64,127 @@ const QWEN_PORTAL_DEFAULT_COST = {
  cacheWrite: 0,
 };

+const OLLAMA_HOST_BASE_URL = "http://127.0.0.1:11434";
+const OLLAMA_DEFAULT_CONTEXT_WINDOW = 8192;
+const OLLAMA_MAX_TOKENS_MULTIPLIER = 10;
+const OLLAMA_DISCOVERY_TIMEOUT_MS = 5000;
+const OLLAMA_DEFAULT_COST = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+};
+
+interface OllamaModel {
+  name: string;
+  modified_at: string;
+  size: number;
+  digest: string;
+  details?: {
+    family?: string;
+    parameter_size?: string;
+  };
+}
+
+interface OllamaTagsResponse {
+  models: OllamaModel[];
+}
+
+interface OllamaShowResponse {
+  capabilities?: string[];
+  model_info?: Record<string, string | number>;
+}
+
+function parseOllamaNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function resolveOllamaContextWindow(
+  modelInfo: Record<string, string | number> | undefined,
+): number {
+  if (!modelInfo) return OLLAMA_DEFAULT_CONTEXT_WINDOW;
+  const architecture = String(modelInfo["general.architecture"] ?? "").trim();
+  const contextKey = architecture ? `${architecture}.context_length` : "";
+  const contextWindow =
+    (contextKey ? parseOllamaNumber(modelInfo[contextKey]) : undefined) ??
+    parseOllamaNumber(modelInfo["context_length"]);
+  return contextWindow ?? OLLAMA_DEFAULT_CONTEXT_WINDOW;
+}
+
+function normalizeOllamaHostBaseUrl(baseUrl: string): string {
+  const trimmed = baseUrl.trim().replace(/\/+$/, "");
+  return trimmed.endsWith("/v1") ? trimmed.slice(0, -3) : trimmed;
+}
+
+async function discoverOllamaModels(baseUrl: string): Promise<ModelDefinitionConfig[]> {
+  // Skip Ollama discovery in test environments
+  if (process.env.VITEST || process.env.NODE_ENV === "test") {
+    return [];
+  }
+  try {
+    const response = await fetch(`${baseUrl}/api/tags`, {
+      signal: AbortSignal.timeout(OLLAMA_DISCOVERY_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      console.warn(`Failed to discover Ollama models: ${response.status}`);
+      return [];
+    }
+    const data = (await response.json()) as OllamaTagsResponse;
+    if (!data.models || data.models.length === 0) {
+      console.warn("No Ollama models found on local instance");
+      return [];
+    }
+    const models = await Promise.all(
+      data.models.map(async (model) => {
+        try {
+          const detailsResponse = await fetch(`${baseUrl}/api/show`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ name: model.name }),
+            signal: AbortSignal.timeout(OLLAMA_DISCOVERY_TIMEOUT_MS),
+          });
+          if (!detailsResponse.ok) {
+            console.warn(
+              `Failed to fetch Ollama model details for ${model.name}: ${detailsResponse.status}`,
+            );
+            return null;
+          }
+          const details = (await detailsResponse.json()) as OllamaShowResponse;
+          const capabilities = Array.isArray(details.capabilities) ? details.capabilities : [];
+          if (!capabilities.includes("tools")) {
+            console.debug(`Skipping Ollama model ${model.name}: does not support tools`);
+            return null;
+          }
+          const contextWindow = resolveOllamaContextWindow(details.model_info);
+          return {
+            id: model.name,
+            name: model.name,
+            reasoning: capabilities.includes("thinking"),
+            input: ["text"],
+            cost: OLLAMA_DEFAULT_COST,
+            contextWindow,
+            maxTokens: contextWindow * OLLAMA_MAX_TOKENS_MULTIPLIER,
+          };
+        } catch (error) {
+          console.warn(`Failed to fetch Ollama model details for ${model.name}: ${String(error)}`);
+          return null;
+        }
+      }),
+    );
+    return models.filter((model): model is ModelDefinitionConfig => Boolean(model));
+  } catch (error) {
+    console.warn(`Failed to discover Ollama models: ${String(error)}`);
+    return [];
+  }
+}
+
 function normalizeApiKeyConfig(value: string): string {
  const trimmed = value.trim();
  const match = /^\$\{([A-Z0-9_]+)\}$/.exec(trimmed);
@@ -275,11 +398,28 @@ function buildSyntheticProvider(): ProviderConfig {
  };
 }

-export function resolveImplicitProviders(params: { agentDir: string }): ModelsConfig["providers"] {
+async function buildOllamaProvider(baseUrl: string): Promise<ProviderConfig> {
+  const hostBaseUrl = normalizeOllamaHostBaseUrl(baseUrl);
+  const models = await discoverOllamaModels(hostBaseUrl);
+  return {
+    baseUrl: `${hostBaseUrl}/v1`,
+    api: "openai-completions",
+    models,
+  };
+}
+
+export async function resolveImplicitProviders(params: {
+  agentDir: string;
+  explicitProviders?: ModelsConfig["providers"];
+}): Promise<ModelsConfig["providers"]> {
  const providers: Record<string, ProviderConfig> = {};
  const authStore = ensureAuthProfileStore(params.agentDir, {
    allowKeychainPrompt: false,
  });
+  const explicitProviders = params.explicitProviders ?? {};
+  const hasExplicitOllama = Object.keys(explicitProviders).some(
+    (key) => normalizeProviderId(key) === "ollama",
+  );

  const minimaxKey =
    resolveEnvApiKeyVarName("minimax") ??
@@ -317,6 +457,14 @@ export function resolveImplicitProviders(params: { agentDir: string }): ModelsCo
    };
  }

+  // Ollama provider - only add if explicitly configured
+  const ollamaKey =
+    resolveEnvApiKeyVarName("ollama") ??
+    resolveApiKeyFromProfiles({ provider: "ollama", store: authStore });
+  if (ollamaKey && !hasExplicitOllama) {
+    providers.ollama = { ...(await buildOllamaProvider(OLLAMA_HOST_BASE_URL)), apiKey: ollamaKey };
+  }
+
  return providers;
 }

@@ -80,7 +80,7 @@ export async function ensureClawdbotModelsJson(
  const agentDir = agentDirOverride?.trim() ? agentDirOverride.trim() : resolveClawdbotAgentDir();

  const explicitProviders = (cfg.models?.providers ?? {}) as Record<string, ProviderConfig>;
-  const implicitProviders = resolveImplicitProviders({ agentDir });
+  const implicitProviders = await resolveImplicitProviders({ agentDir, explicitProviders });
  const providers: Record<string, ProviderConfig> = mergeProviders({
    implicit: implicitProviders,
    explicit: explicitProviders,
@@ -1,15 +1,7 @@
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import { describe, expect, it } from "vitest";
 import { formatAssistantErrorText } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";

-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
 describe("formatAssistantErrorText", () => {
  const makeAssistantError = (errorMessage: string): AssistantMessage =>
    ({
@@ -21,6 +13,16 @@ describe("formatAssistantErrorText", () => {
    const msg = makeAssistantError("request_too_large");
    expect(formatAssistantErrorText(msg)).toContain("Context overflow");
  });
+  it("returns context overflow for Anthropic 'Request size exceeds model context window'", () => {
+    // This is the new Anthropic error format that wasn't being detected.
+    // Without the fix, this falls through to the invalidRequest regex and returns
+    // "LLM request rejected: Request size exceeds model context window"
+    // instead of the context overflow message, preventing auto-compaction.
+    const msg = makeAssistantError(
+      '{"type":"error","error":{"type":"invalid_request_error","message":"Request size exceeds model context window"}}',
+    );
+    expect(formatAssistantErrorText(msg)).toContain("Context overflow");
+  });
  it("returns a friendly message for Anthropic role ordering", () => {
    const msg = makeAssistantError('messages: roles must alternate between "user" and "assistant"');
    expect(formatAssistantErrorText(msg)).toContain("Message ordering conflict");
@@ -1,14 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { isContextOverflowError } from "./pi-embedded-helpers.js";
-import { DEFAULT_AGENTS_FILENAME } from "./workspace.js";

-const _makeFile = (overrides: Partial<WorkspaceBootstrapFile>): WorkspaceBootstrapFile => ({
-  name: DEFAULT_AGENTS_FILENAME,
-  path: "/tmp/AGENTS.md",
-  content: "",
-  missing: false,
-  ...overrides,
-});
 describe("isContextOverflowError", () => {
  it("matches known overflow hints", () => {
    const samples = [
@@ -24,7 +16,34 @@ describe("isContextOverflowError", () => {
      expect(isContextOverflowError(sample)).toBe(true);
    }
  });
+
+  it("matches Anthropic 'Request size exceeds model context window' error", () => {
+    // Anthropic returns this error format when the prompt exceeds the context window.
+    // Without this fix, auto-compaction is NOT triggered because neither
+    // isContextOverflowError nor pi-ai's isContextOverflow recognizes this pattern.
+    // The user sees: "LLM request rejected: Request size exceeds model context window"
+    // instead of automatic compaction + retry.
+    const anthropicRawError =
+      '{"type":"error","error":{"type":"invalid_request_error","message":"Request size exceeds model context window"}}';
+    expect(isContextOverflowError(anthropicRawError)).toBe(true);
+  });
+
+  it("matches 'exceeds model context window' in various formats", () => {
+    const samples = [
+      "Request size exceeds model context window",
+      "request size exceeds model context window",
+      '400 {"type":"error","error":{"type":"invalid_request_error","message":"Request size exceeds model context window"}}',
+      "The request size exceeds model context window limit",
+    ];
+    for (const sample of samples) {
+      expect(isContextOverflowError(sample)).toBe(true);
+    }
+  });
+
  it("ignores unrelated errors", () => {
    expect(isContextOverflowError("rate limit exceeded")).toBe(false);
+    expect(isContextOverflowError("request size exceeds upload limit")).toBe(false);
+    expect(isContextOverflowError("model not found")).toBe(false);
+    expect(isContextOverflowError("authentication failed")).toBe(false);
  });
 });
@@ -7,12 +7,19 @@ import type { FailoverReason } from "./types.js";
 export function isContextOverflowError(errorMessage?: string): boolean {
  if (!errorMessage) return false;
  const lower = errorMessage.toLowerCase();
+  const hasRequestSizeExceeds = lower.includes("request size exceeds");
+  const hasContextWindow =
+    lower.includes("context window") ||
+    lower.includes("context length") ||
+    lower.includes("maximum context length");
  return (
    lower.includes("request_too_large") ||
    lower.includes("request exceeds the maximum size") ||
    lower.includes("context length exceeded") ||
    lower.includes("maximum context length") ||
    lower.includes("prompt is too long") ||
+    lower.includes("exceeds model context window") ||
+    (hasRequestSizeExceeds && hasContextWindow) ||
    lower.includes("context overflow") ||
    (lower.includes("413") && lower.includes("too large"))
  );
@@ -72,7 +72,7 @@ const _makeOpenAiConfig = (modelIds: string[]) =>
  }) satisfies ClawdbotConfig;

 const _ensureModels = (cfg: ClawdbotConfig, agentDir: string) =>
-  ensureClawdbotModelsJson(cfg, agentDir);
+  ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const _textFromContent = (content: unknown) => {
  if (typeof content === "string") return content;
@@ -71,7 +71,7 @@ const _makeOpenAiConfig = (modelIds: string[]) =>
  }) satisfies ClawdbotConfig;

 const _ensureModels = (cfg: ClawdbotConfig, agentDir: string) =>
-  ensureClawdbotModelsJson(cfg, agentDir);
+  ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const _textFromContent = (content: unknown) => {
  if (typeof content === "string") return content;
@@ -70,7 +70,7 @@ const _makeOpenAiConfig = (modelIds: string[]) =>
  }) satisfies ClawdbotConfig;

 const _ensureModels = (cfg: ClawdbotConfig, agentDir: string) =>
-  ensureClawdbotModelsJson(cfg, agentDir);
+  ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const _textFromContent = (content: unknown) => {
  if (typeof content === "string") return content;
@@ -70,7 +70,7 @@ const _makeOpenAiConfig = (modelIds: string[]) =>
  }) satisfies ClawdbotConfig;

 const _ensureModels = (cfg: ClawdbotConfig, agentDir: string) =>
-  ensureClawdbotModelsJson(cfg, agentDir);
+  ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const _textFromContent = (content: unknown) => {
  if (typeof content === "string") return content;
@@ -71,7 +71,7 @@ const _makeOpenAiConfig = (modelIds: string[]) =>
  }) satisfies ClawdbotConfig;

 const _ensureModels = (cfg: ClawdbotConfig, agentDir: string) =>
-  ensureClawdbotModelsJson(cfg, agentDir);
+  ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const _textFromContent = (content: unknown) => {
  if (typeof content === "string") return content;
@@ -70,7 +70,7 @@ const _makeOpenAiConfig = (modelIds: string[]) =>
  }) satisfies ClawdbotConfig;

 const _ensureModels = (cfg: ClawdbotConfig, agentDir: string) =>
-  ensureClawdbotModelsJson(cfg, agentDir);
+  ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const _textFromContent = (content: unknown) => {
  if (typeof content === "string") return content;
@@ -71,7 +71,7 @@ const _makeOpenAiConfig = (modelIds: string[]) =>
  }) satisfies ClawdbotConfig;

 const _ensureModels = (cfg: ClawdbotConfig, agentDir: string) =>
-  ensureClawdbotModelsJson(cfg, agentDir);
+  ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const _textFromContent = (content: unknown) => {
  if (typeof content === "string") return content;
@@ -130,7 +130,7 @@ const makeOpenAiConfig = (modelIds: string[]) =>
    },
  }) satisfies ClawdbotConfig;

-const ensureModels = (cfg: ClawdbotConfig) => ensureClawdbotModelsJson(cfg, agentDir);
+const ensureModels = (cfg: ClawdbotConfig) => ensureClawdbotModelsJson(cfg, agentDir) as unknown;

 const nextSessionFile = () => {
  sessionCounter += 1;
@@ -68,12 +68,13 @@ import { formatUserTime, resolveUserTimeFormat, resolveUserTimezone } from "../d
 import { describeUnknownError, mapThinkingLevel, resolveExecToolDefaults } from "./utils.js";
 import { buildTtsSystemPromptHint } from "../../tts/tts.js";

-export async function compactEmbeddedPiSession(params: {
+export type CompactEmbeddedPiSessionParams = {
  sessionId: string;
  sessionKey?: string;
  messageChannel?: string;
  messageProvider?: string;
  agentAccountId?: string;
+  authProfileId?: string;
  /** Group id for channel-level tool policy resolution. */
  groupId?: string | null;
  /** Group channel label (e.g. #general) for channel-level tool policy resolution. */
@@ -97,354 +98,366 @@ export async function compactEmbeddedPiSession(params: {
  enqueue?: typeof enqueueCommand;
  extraSystemPrompt?: string;
  ownerNumbers?: string[];
-}): Promise<EmbeddedPiCompactResult> {
+};
+
+/**
+ * Core compaction logic without lane queueing.
+ * Use this when already inside a session/global lane to avoid deadlocks.
+ */
+export async function compactEmbeddedPiSessionDirect(
+  params: CompactEmbeddedPiSessionParams,
+): Promise<EmbeddedPiCompactResult> {
+  const resolvedWorkspace = resolveUserPath(params.workspaceDir);
+  const prevCwd = process.cwd();
+
+  const provider = (params.provider ?? DEFAULT_PROVIDER).trim() || DEFAULT_PROVIDER;
+  const modelId = (params.model ?? DEFAULT_MODEL).trim() || DEFAULT_MODEL;
+  const agentDir = params.agentDir ?? resolveClawdbotAgentDir();
+  await ensureClawdbotModelsJson(params.config, agentDir);
+  const { model, error, authStorage, modelRegistry } = resolveModel(
+    provider,
+    modelId,
+    agentDir,
+    params.config,
+  );
+  if (!model) {
+    return {
+      ok: false,
+      compacted: false,
+      reason: error ?? `Unknown model: ${provider}/${modelId}`,
+    };
+  }
+  try {
+    const apiKeyInfo = await getApiKeyForModel({
+      model,
+      cfg: params.config,
+      profileId: params.authProfileId,
+      agentDir,
+    });
+
+    if (!apiKeyInfo.apiKey) {
+      if (apiKeyInfo.mode !== "aws-sdk") {
+        throw new Error(
+          `No API key resolved for provider "${model.provider}" (auth mode: ${apiKeyInfo.mode}).`,
+        );
+      }
+    } else if (model.provider === "github-copilot") {
+      const { resolveCopilotApiToken } = await import("../../providers/github-copilot-token.js");
+      const copilotToken = await resolveCopilotApiToken({
+        githubToken: apiKeyInfo.apiKey,
+      });
+      authStorage.setRuntimeApiKey(model.provider, copilotToken.token);
+    } else {
+      authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      compacted: false,
+      reason: describeUnknownError(err),
+    };
+  }
+
+  await fs.mkdir(resolvedWorkspace, { recursive: true });
+  const sandboxSessionKey = params.sessionKey?.trim() || params.sessionId;
+  const sandbox = await resolveSandboxContext({
+    config: params.config,
+    sessionKey: sandboxSessionKey,
+    workspaceDir: resolvedWorkspace,
+  });
+  const effectiveWorkspace = sandbox?.enabled
+    ? sandbox.workspaceAccess === "rw"
+      ? resolvedWorkspace
+      : sandbox.workspaceDir
+    : resolvedWorkspace;
+  await fs.mkdir(effectiveWorkspace, { recursive: true });
+  await ensureSessionHeader({
+    sessionFile: params.sessionFile,
+    sessionId: params.sessionId,
+    cwd: effectiveWorkspace,
+  });
+
+  let restoreSkillEnv: (() => void) | undefined;
+  process.chdir(effectiveWorkspace);
+  try {
+    const shouldLoadSkillEntries = !params.skillsSnapshot || !params.skillsSnapshot.resolvedSkills;
+    const skillEntries = shouldLoadSkillEntries
+      ? loadWorkspaceSkillEntries(effectiveWorkspace)
+      : [];
+    restoreSkillEnv = params.skillsSnapshot
+      ? applySkillEnvOverridesFromSnapshot({
+          snapshot: params.skillsSnapshot,
+          config: params.config,
+        })
+      : applySkillEnvOverrides({
+          skills: skillEntries ?? [],
+          config: params.config,
+        });
+    const skillsPrompt = resolveSkillsPromptForRun({
+      skillsSnapshot: params.skillsSnapshot,
+      entries: shouldLoadSkillEntries ? skillEntries : undefined,
+      config: params.config,
+      workspaceDir: effectiveWorkspace,
+    });
+
+    const sessionLabel = params.sessionKey ?? params.sessionId;
+    const { contextFiles } = await resolveBootstrapContextForRun({
+      workspaceDir: effectiveWorkspace,
+      config: params.config,
+      sessionKey: params.sessionKey,
+      sessionId: params.sessionId,
+      warn: makeBootstrapWarn({ sessionLabel, warn: (message) => log.warn(message) }),
+    });
+    const runAbortController = new AbortController();
+    const toolsRaw = createClawdbotCodingTools({
+      exec: {
+        ...resolveExecToolDefaults(params.config),
+        elevated: params.bashElevated,
+      },
+      sandbox,
+      messageProvider: params.messageChannel ?? params.messageProvider,
+      agentAccountId: params.agentAccountId,
+      sessionKey: params.sessionKey ?? params.sessionId,
+      groupId: params.groupId,
+      groupChannel: params.groupChannel,
+      groupSpace: params.groupSpace,
+      spawnedBy: params.spawnedBy,
+      agentDir,
+      workspaceDir: effectiveWorkspace,
+      config: params.config,
+      abortSignal: runAbortController.signal,
+      modelProvider: model.provider,
+      modelId,
+      modelAuthMode: resolveModelAuthMode(model.provider, params.config),
+    });
+    const tools = sanitizeToolsForGoogle({ tools: toolsRaw, provider });
+    logToolSchemasForGoogle({ tools, provider });
+    const machineName = await getMachineDisplayName();
+    const runtimeChannel = normalizeMessageChannel(params.messageChannel ?? params.messageProvider);
+    let runtimeCapabilities = runtimeChannel
+      ? (resolveChannelCapabilities({
+          cfg: params.config,
+          channel: runtimeChannel,
+          accountId: params.agentAccountId,
+        }) ?? [])
+      : undefined;
+    if (runtimeChannel === "telegram" && params.config) {
+      const inlineButtonsScope = resolveTelegramInlineButtonsScope({
+        cfg: params.config,
+        accountId: params.agentAccountId ?? undefined,
+      });
+      if (inlineButtonsScope !== "off") {
+        if (!runtimeCapabilities) runtimeCapabilities = [];
+        if (
+          !runtimeCapabilities.some((cap) => String(cap).trim().toLowerCase() === "inlinebuttons")
+        ) {
+          runtimeCapabilities.push("inlineButtons");
+        }
+      }
+    }
+    // Resolve channel-specific message actions for system prompt
+    const channelActions = runtimeChannel
+      ? listChannelSupportedActions({
+          cfg: params.config,
+          channel: runtimeChannel,
+        })
+      : undefined;
+    const messageToolHints = runtimeChannel
+      ? resolveChannelMessageToolHints({
+          cfg: params.config,
+          channel: runtimeChannel,
+          accountId: params.agentAccountId,
+        })
+      : undefined;
+
+    const runtimeInfo = {
+      host: machineName,
+      os: `${os.type()} ${os.release()}`,
+      arch: os.arch(),
+      node: process.version,
+      model: `${provider}/${modelId}`,
+      channel: runtimeChannel,
+      capabilities: runtimeCapabilities,
+      channelActions,
+    };
+    const sandboxInfo = buildEmbeddedSandboxInfo(sandbox, params.bashElevated);
+    const reasoningTagHint = isReasoningTagProvider(provider);
+    const userTimezone = resolveUserTimezone(params.config?.agents?.defaults?.userTimezone);
+    const userTimeFormat = resolveUserTimeFormat(params.config?.agents?.defaults?.timeFormat);
+    const userTime = formatUserTime(new Date(), userTimezone, userTimeFormat);
+    const { defaultAgentId, sessionAgentId } = resolveSessionAgentIds({
+      sessionKey: params.sessionKey,
+      config: params.config,
+    });
+    const isDefaultAgent = sessionAgentId === defaultAgentId;
+    const promptMode = isSubagentSessionKey(params.sessionKey) ? "minimal" : "full";
+    const docsPath = await resolveClawdbotDocsPath({
+      workspaceDir: effectiveWorkspace,
+      argv1: process.argv[1],
+      cwd: process.cwd(),
+      moduleUrl: import.meta.url,
+    });
+    const ttsHint = params.config ? buildTtsSystemPromptHint(params.config) : undefined;
+    const appendPrompt = buildEmbeddedSystemPrompt({
+      workspaceDir: effectiveWorkspace,
+      defaultThinkLevel: params.thinkLevel,
+      reasoningLevel: params.reasoningLevel ?? "off",
+      extraSystemPrompt: params.extraSystemPrompt,
+      ownerNumbers: params.ownerNumbers,
+      reasoningTagHint,
+      heartbeatPrompt: isDefaultAgent
+        ? resolveHeartbeatPrompt(params.config?.agents?.defaults?.heartbeat?.prompt)
+        : undefined,
+      skillsPrompt,
+      docsPath: docsPath ?? undefined,
+      ttsHint,
+      promptMode,
+      runtimeInfo,
+      messageToolHints,
+      sandboxInfo,
+      tools,
+      modelAliasLines: buildModelAliasLines(params.config),
+      userTimezone,
+      userTime,
+      userTimeFormat,
+      contextFiles,
+    });
+    const systemPrompt = createSystemPromptOverride(appendPrompt);
+
+    const sessionLock = await acquireSessionWriteLock({
+      sessionFile: params.sessionFile,
+    });
+    try {
+      await prewarmSessionFile(params.sessionFile);
+      const transcriptPolicy = resolveTranscriptPolicy({
+        modelApi: model.api,
+        provider,
+        modelId,
+      });
+      const sessionManager = guardSessionManager(SessionManager.open(params.sessionFile), {
+        agentId: sessionAgentId,
+        sessionKey: params.sessionKey,
+        allowSyntheticToolResults: transcriptPolicy.allowSyntheticToolResults,
+      });
+      trackSessionManagerAccess(params.sessionFile);
+      const settingsManager = SettingsManager.create(effectiveWorkspace, agentDir);
+      ensurePiCompactionReserveTokens({
+        settingsManager,
+        minReserveTokens: resolveCompactionReserveTokensFloor(params.config),
+      });
+      const additionalExtensionPaths = buildEmbeddedExtensionPaths({
+        cfg: params.config,
+        sessionManager,
+        provider,
+        modelId,
+        model,
+      });
+
+      const { builtInTools, customTools } = splitSdkTools({
+        tools,
+        sandboxEnabled: !!sandbox?.enabled,
+      });
+
+      let session: Awaited<ReturnType<typeof createAgentSession>>["session"];
+      ({ session } = await createAgentSession({
+        cwd: resolvedWorkspace,
+        agentDir,
+        authStorage,
+        modelRegistry,
+        model,
+        thinkingLevel: mapThinkingLevel(params.thinkLevel),
+        systemPrompt,
+        tools: builtInTools,
+        customTools,
+        sessionManager,
+        settingsManager,
+        skills: [],
+        contextFiles: [],
+        additionalExtensionPaths,
+      }));
+
+      try {
+        const prior = await sanitizeSessionHistory({
+          messages: session.messages,
+          modelApi: model.api,
+          modelId,
+          provider,
+          sessionManager,
+          sessionId: params.sessionId,
+          policy: transcriptPolicy,
+        });
+        const validatedGemini = transcriptPolicy.validateGeminiTurns
+          ? validateGeminiTurns(prior)
+          : prior;
+        const validated = transcriptPolicy.validateAnthropicTurns
+          ? validateAnthropicTurns(validatedGemini)
+          : validatedGemini;
+        const limited = limitHistoryTurns(
+          validated,
+          getDmHistoryLimitFromSessionKey(params.sessionKey, params.config),
+        );
+        if (limited.length > 0) {
+          session.agent.replaceMessages(limited);
+        }
+        const result = await session.compact(params.customInstructions);
+        // Estimate tokens after compaction by summing token estimates for remaining messages
+        let tokensAfter: number | undefined;
+        try {
+          tokensAfter = 0;
+          for (const message of session.messages) {
+            tokensAfter += estimateTokens(message);
+          }
+          // Sanity check: tokensAfter should be less than tokensBefore
+          if (tokensAfter > result.tokensBefore) {
+            tokensAfter = undefined; // Don't trust the estimate
+          }
+        } catch {
+          // If estimation fails, leave tokensAfter undefined
+          tokensAfter = undefined;
+        }
+        return {
+          ok: true,
+          compacted: true,
+          result: {
+            summary: result.summary,
+            firstKeptEntryId: result.firstKeptEntryId,
+            tokensBefore: result.tokensBefore,
+            tokensAfter,
+            details: result.details,
+          },
+        };
+      } finally {
+        sessionManager.flushPendingToolResults?.();
+        session.dispose();
+      }
+    } finally {
+      await sessionLock.release();
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      compacted: false,
+      reason: describeUnknownError(err),
+    };
+  } finally {
+    restoreSkillEnv?.();
+    process.chdir(prevCwd);
+  }
+}
+
+/**
+ * Compacts a session with lane queueing (session lane + global lane).
+ * Use this from outside a lane context. If already inside a lane, use
+ * `compactEmbeddedPiSessionDirect` to avoid deadlocks.
+ */
+export async function compactEmbeddedPiSession(
+  params: CompactEmbeddedPiSessionParams,
+): Promise<EmbeddedPiCompactResult> {
  const sessionLane = resolveSessionLane(params.sessionKey?.trim() || params.sessionId);
  const globalLane = resolveGlobalLane(params.lane);
  const enqueueGlobal =
    params.enqueue ?? ((task, opts) => enqueueCommandInLane(globalLane, task, opts));
  return enqueueCommandInLane(sessionLane, () =>
-    enqueueGlobal(async () => {
-      const resolvedWorkspace = resolveUserPath(params.workspaceDir);
-      const prevCwd = process.cwd();
-
-      const provider = (params.provider ?? DEFAULT_PROVIDER).trim() || DEFAULT_PROVIDER;
-      const modelId = (params.model ?? DEFAULT_MODEL).trim() || DEFAULT_MODEL;
-      const agentDir = params.agentDir ?? resolveClawdbotAgentDir();
-      await ensureClawdbotModelsJson(params.config, agentDir);
-      const { model, error, authStorage, modelRegistry } = resolveModel(
-        provider,
-        modelId,
-        agentDir,
-        params.config,
-      );
-      if (!model) {
-        return {
-          ok: false,
-          compacted: false,
-          reason: error ?? `Unknown model: ${provider}/${modelId}`,
-        };
-      }
-      try {
-        const apiKeyInfo = await getApiKeyForModel({
-          model,
-          cfg: params.config,
-          agentDir,
-        });
-
-        if (!apiKeyInfo.apiKey) {
-          if (apiKeyInfo.mode !== "aws-sdk") {
-            throw new Error(
-              `No API key resolved for provider "${model.provider}" (auth mode: ${apiKeyInfo.mode}).`,
-            );
-          }
-        } else if (model.provider === "github-copilot") {
-          const { resolveCopilotApiToken } =
-            await import("../../providers/github-copilot-token.js");
-          const copilotToken = await resolveCopilotApiToken({
-            githubToken: apiKeyInfo.apiKey,
-          });
-          authStorage.setRuntimeApiKey(model.provider, copilotToken.token);
-        } else {
-          authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);
-        }
-      } catch (err) {
-        return {
-          ok: false,
-          compacted: false,
-          reason: describeUnknownError(err),
-        };
-      }
-
-      await fs.mkdir(resolvedWorkspace, { recursive: true });
-      const sandboxSessionKey = params.sessionKey?.trim() || params.sessionId;
-      const sandbox = await resolveSandboxContext({
-        config: params.config,
-        sessionKey: sandboxSessionKey,
-        workspaceDir: resolvedWorkspace,
-      });
-      const effectiveWorkspace = sandbox?.enabled
-        ? sandbox.workspaceAccess === "rw"
-          ? resolvedWorkspace
-          : sandbox.workspaceDir
-        : resolvedWorkspace;
-      await fs.mkdir(effectiveWorkspace, { recursive: true });
-      await ensureSessionHeader({
-        sessionFile: params.sessionFile,
-        sessionId: params.sessionId,
-        cwd: effectiveWorkspace,
-      });
-
-      let restoreSkillEnv: (() => void) | undefined;
-      process.chdir(effectiveWorkspace);
-      try {
-        const shouldLoadSkillEntries =
-          !params.skillsSnapshot || !params.skillsSnapshot.resolvedSkills;
-        const skillEntries = shouldLoadSkillEntries
-          ? loadWorkspaceSkillEntries(effectiveWorkspace)
-          : [];
-        restoreSkillEnv = params.skillsSnapshot
-          ? applySkillEnvOverridesFromSnapshot({
-              snapshot: params.skillsSnapshot,
-              config: params.config,
-            })
-          : applySkillEnvOverrides({
-              skills: skillEntries ?? [],
-              config: params.config,
-            });
-        const skillsPrompt = resolveSkillsPromptForRun({
-          skillsSnapshot: params.skillsSnapshot,
-          entries: shouldLoadSkillEntries ? skillEntries : undefined,
-          config: params.config,
-          workspaceDir: effectiveWorkspace,
-        });
-
-        const sessionLabel = params.sessionKey ?? params.sessionId;
-        const { contextFiles } = await resolveBootstrapContextForRun({
-          workspaceDir: effectiveWorkspace,
-          config: params.config,
-          sessionKey: params.sessionKey,
-          sessionId: params.sessionId,
-          warn: makeBootstrapWarn({ sessionLabel, warn: (message) => log.warn(message) }),
-        });
-        const runAbortController = new AbortController();
-        const toolsRaw = createClawdbotCodingTools({
-          exec: {
-            ...resolveExecToolDefaults(params.config),
-            elevated: params.bashElevated,
-          },
-          sandbox,
-          messageProvider: params.messageChannel ?? params.messageProvider,
-          agentAccountId: params.agentAccountId,
-          sessionKey: params.sessionKey ?? params.sessionId,
-          groupId: params.groupId,
-          groupChannel: params.groupChannel,
-          groupSpace: params.groupSpace,
-          spawnedBy: params.spawnedBy,
-          agentDir,
-          workspaceDir: effectiveWorkspace,
-          config: params.config,
-          abortSignal: runAbortController.signal,
-          modelProvider: model.provider,
-          modelId,
-          modelAuthMode: resolveModelAuthMode(model.provider, params.config),
-        });
-        const tools = sanitizeToolsForGoogle({ tools: toolsRaw, provider });
-        logToolSchemasForGoogle({ tools, provider });
-        const machineName = await getMachineDisplayName();
-        const runtimeChannel = normalizeMessageChannel(
-          params.messageChannel ?? params.messageProvider,
-        );
-        let runtimeCapabilities = runtimeChannel
-          ? (resolveChannelCapabilities({
-              cfg: params.config,
-              channel: runtimeChannel,
-              accountId: params.agentAccountId,
-            }) ?? [])
-          : undefined;
-        if (runtimeChannel === "telegram" && params.config) {
-          const inlineButtonsScope = resolveTelegramInlineButtonsScope({
-            cfg: params.config,
-            accountId: params.agentAccountId ?? undefined,
-          });
-          if (inlineButtonsScope !== "off") {
-            if (!runtimeCapabilities) runtimeCapabilities = [];
-            if (
-              !runtimeCapabilities.some(
-                (cap) => String(cap).trim().toLowerCase() === "inlinebuttons",
-              )
-            ) {
-              runtimeCapabilities.push("inlineButtons");
-            }
-          }
-        }
-        // Resolve channel-specific message actions for system prompt
-        const channelActions = runtimeChannel
-          ? listChannelSupportedActions({
-              cfg: params.config,
-              channel: runtimeChannel,
-            })
-          : undefined;
-        const messageToolHints = runtimeChannel
-          ? resolveChannelMessageToolHints({
-              cfg: params.config,
-              channel: runtimeChannel,
-              accountId: params.agentAccountId,
-            })
-          : undefined;
-
-        const runtimeInfo = {
-          host: machineName,
-          os: `${os.type()} ${os.release()}`,
-          arch: os.arch(),
-          node: process.version,
-          model: `${provider}/${modelId}`,
-          channel: runtimeChannel,
-          capabilities: runtimeCapabilities,
-          channelActions,
-        };
-        const sandboxInfo = buildEmbeddedSandboxInfo(sandbox, params.bashElevated);
-        const reasoningTagHint = isReasoningTagProvider(provider);
-        const userTimezone = resolveUserTimezone(params.config?.agents?.defaults?.userTimezone);
-        const userTimeFormat = resolveUserTimeFormat(params.config?.agents?.defaults?.timeFormat);
-        const userTime = formatUserTime(new Date(), userTimezone, userTimeFormat);
-        const { defaultAgentId, sessionAgentId } = resolveSessionAgentIds({
-          sessionKey: params.sessionKey,
-          config: params.config,
-        });
-        const isDefaultAgent = sessionAgentId === defaultAgentId;
-        const promptMode = isSubagentSessionKey(params.sessionKey) ? "minimal" : "full";
-        const docsPath = await resolveClawdbotDocsPath({
-          workspaceDir: effectiveWorkspace,
-          argv1: process.argv[1],
-          cwd: process.cwd(),
-          moduleUrl: import.meta.url,
-        });
-        const ttsHint = params.config ? buildTtsSystemPromptHint(params.config) : undefined;
-        const appendPrompt = buildEmbeddedSystemPrompt({
-          workspaceDir: effectiveWorkspace,
-          defaultThinkLevel: params.thinkLevel,
-          reasoningLevel: params.reasoningLevel ?? "off",
-          extraSystemPrompt: params.extraSystemPrompt,
-          ownerNumbers: params.ownerNumbers,
-          reasoningTagHint,
-          heartbeatPrompt: isDefaultAgent
-            ? resolveHeartbeatPrompt(params.config?.agents?.defaults?.heartbeat?.prompt)
-            : undefined,
-          skillsPrompt,
-          docsPath: docsPath ?? undefined,
-          ttsHint,
-          promptMode,
-          runtimeInfo,
-          messageToolHints,
-          sandboxInfo,
-          tools,
-          modelAliasLines: buildModelAliasLines(params.config),
-          userTimezone,
-          userTime,
-          userTimeFormat,
-          contextFiles,
-        });
-        const systemPrompt = createSystemPromptOverride(appendPrompt);
-
-        const sessionLock = await acquireSessionWriteLock({
-          sessionFile: params.sessionFile,
-        });
-        try {
-          await prewarmSessionFile(params.sessionFile);
-          const transcriptPolicy = resolveTranscriptPolicy({
-            modelApi: model.api,
-            provider,
-            modelId,
-          });
-          const sessionManager = guardSessionManager(SessionManager.open(params.sessionFile), {
-            agentId: sessionAgentId,
-            sessionKey: params.sessionKey,
-            allowSyntheticToolResults: transcriptPolicy.allowSyntheticToolResults,
-          });
-          trackSessionManagerAccess(params.sessionFile);
-          const settingsManager = SettingsManager.create(effectiveWorkspace, agentDir);
-          ensurePiCompactionReserveTokens({
-            settingsManager,
-            minReserveTokens: resolveCompactionReserveTokensFloor(params.config),
-          });
-          const additionalExtensionPaths = buildEmbeddedExtensionPaths({
-            cfg: params.config,
-            sessionManager,
-            provider,
-            modelId,
-            model,
-          });
-
-          const { builtInTools, customTools } = splitSdkTools({
-            tools,
-            sandboxEnabled: !!sandbox?.enabled,
-          });
-
-          let session: Awaited<ReturnType<typeof createAgentSession>>["session"];
-          ({ session } = await createAgentSession({
-            cwd: resolvedWorkspace,
-            agentDir,
-            authStorage,
-            modelRegistry,
-            model,
-            thinkingLevel: mapThinkingLevel(params.thinkLevel),
-            systemPrompt,
-            tools: builtInTools,
-            customTools,
-            sessionManager,
-            settingsManager,
-            skills: [],
-            contextFiles: [],
-            additionalExtensionPaths,
-          }));
-
-          try {
-            const prior = await sanitizeSessionHistory({
-              messages: session.messages,
-              modelApi: model.api,
-              modelId,
-              provider,
-              sessionManager,
-              sessionId: params.sessionId,
-              policy: transcriptPolicy,
-            });
-            const validatedGemini = transcriptPolicy.validateGeminiTurns
-              ? validateGeminiTurns(prior)
-              : prior;
-            const validated = transcriptPolicy.validateAnthropicTurns
-              ? validateAnthropicTurns(validatedGemini)
-              : validatedGemini;
-            const limited = limitHistoryTurns(
-              validated,
-              getDmHistoryLimitFromSessionKey(params.sessionKey, params.config),
-            );
-            if (limited.length > 0) {
-              session.agent.replaceMessages(limited);
-            }
-            const result = await session.compact(params.customInstructions);
-            // Estimate tokens after compaction by summing token estimates for remaining messages
-            let tokensAfter: number | undefined;
-            try {
-              tokensAfter = 0;
-              for (const message of session.messages) {
-                tokensAfter += estimateTokens(message);
-              }
-              // Sanity check: tokensAfter should be less than tokensBefore
-              if (tokensAfter > result.tokensBefore) {
-                tokensAfter = undefined; // Don't trust the estimate
-              }
-            } catch {
-              // If estimation fails, leave tokensAfter undefined
-              tokensAfter = undefined;
-            }
-            return {
-              ok: true,
-              compacted: true,
-              result: {
-                summary: result.summary,
-                firstKeptEntryId: result.firstKeptEntryId,
-                tokensBefore: result.tokensBefore,
-                tokensAfter,
-                details: result.details,
-              },
-            };
-          } finally {
-            sessionManager.flushPendingToolResults?.();
-            session.dispose();
-          }
-        } finally {
-          await sessionLock.release();
-        }
-      } catch (err) {
-        return {
-          ok: false,
-          compacted: false,
-          reason: describeUnknownError(err),
-        };
-      } finally {
-        restoreSkillEnv?.();
-        process.chdir(prevCwd);
-      }
-    }),
+    enqueueGlobal(async () => compactEmbeddedPiSessionDirect(params)),
  );
 }
@@ -0,0 +1,285 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("./run/attempt.js", () => ({
+  runEmbeddedAttempt: vi.fn(),
+}));
+
+vi.mock("./compact.js", () => ({
+  compactEmbeddedPiSessionDirect: vi.fn(),
+}));
+
+vi.mock("./model.js", () => ({
+  resolveModel: vi.fn(() => ({
+    model: {
+      id: "test-model",
+      provider: "anthropic",
+      contextWindow: 200000,
+      api: "messages",
+    },
+    error: null,
+    authStorage: {
+      setRuntimeApiKey: vi.fn(),
+    },
+    modelRegistry: {},
+  })),
+}));
+
+vi.mock("../model-auth.js", () => ({
+  ensureAuthProfileStore: vi.fn(() => ({})),
+  getApiKeyForModel: vi.fn(async () => ({
+    apiKey: "test-key",
+    profileId: "test-profile",
+    source: "test",
+  })),
+  resolveAuthProfileOrder: vi.fn(() => []),
+}));
+
+vi.mock("../models-config.js", () => ({
+  ensureClawdbotModelsJson: vi.fn(async () => {}),
+}));
+
+vi.mock("../context-window-guard.js", () => ({
+  CONTEXT_WINDOW_HARD_MIN_TOKENS: 1000,
+  CONTEXT_WINDOW_WARN_BELOW_TOKENS: 5000,
+  evaluateContextWindowGuard: vi.fn(() => ({
+    shouldWarn: false,
+    shouldBlock: false,
+    tokens: 200000,
+    source: "model",
+  })),
+  resolveContextWindowInfo: vi.fn(() => ({
+    tokens: 200000,
+    source: "model",
+  })),
+}));
+
+vi.mock("../../process/command-queue.js", () => ({
+  enqueueCommandInLane: vi.fn((_lane: string, task: () => unknown) => task()),
+}));
+
+vi.mock("../../utils.js", () => ({
+  resolveUserPath: vi.fn((p: string) => p),
+}));
+
+vi.mock("../../utils/message-channel.js", () => ({
+  isMarkdownCapableMessageChannel: vi.fn(() => true),
+}));
+
+vi.mock("../agent-paths.js", () => ({
+  resolveClawdbotAgentDir: vi.fn(() => "/tmp/agent-dir"),
+}));
+
+vi.mock("../auth-profiles.js", () => ({
+  markAuthProfileFailure: vi.fn(async () => {}),
+  markAuthProfileGood: vi.fn(async () => {}),
+  markAuthProfileUsed: vi.fn(async () => {}),
+}));
+
+vi.mock("../defaults.js", () => ({
+  DEFAULT_CONTEXT_TOKENS: 200000,
+  DEFAULT_MODEL: "test-model",
+  DEFAULT_PROVIDER: "anthropic",
+}));
+
+vi.mock("../failover-error.js", () => ({
+  FailoverError: class extends Error {
+    constructor(msg: string) {
+      super(msg);
+    }
+  },
+  resolveFailoverStatus: vi.fn(),
+}));
+
+vi.mock("../usage.js", () => ({
+  normalizeUsage: vi.fn(() => undefined),
+}));
+
+vi.mock("./lanes.js", () => ({
+  resolveSessionLane: vi.fn(() => "session-lane"),
+  resolveGlobalLane: vi.fn(() => "global-lane"),
+}));
+
+vi.mock("./logger.js", () => ({
+  log: {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+vi.mock("./run/payloads.js", () => ({
+  buildEmbeddedRunPayloads: vi.fn(() => []),
+}));
+
+vi.mock("./utils.js", () => ({
+  describeUnknownError: vi.fn((err: unknown) => {
+    if (err instanceof Error) return err.message;
+    return String(err);
+  }),
+}));
+
+vi.mock("../pi-embedded-helpers.js", async () => {
+  return {
+    isCompactionFailureError: (msg?: string) => {
+      if (!msg) return false;
+      const lower = msg.toLowerCase();
+      return lower.includes("request_too_large") && lower.includes("summarization failed");
+    },
+    isContextOverflowError: (msg?: string) => {
+      if (!msg) return false;
+      const lower = msg.toLowerCase();
+      return lower.includes("request_too_large") || lower.includes("request size exceeds");
+    },
+    isFailoverAssistantError: vi.fn(() => false),
+    isFailoverErrorMessage: vi.fn(() => false),
+    isAuthAssistantError: vi.fn(() => false),
+    isRateLimitAssistantError: vi.fn(() => false),
+    classifyFailoverReason: vi.fn(() => null),
+    formatAssistantErrorText: vi.fn(() => ""),
+    pickFallbackThinkingLevel: vi.fn(() => null),
+    isTimeoutErrorMessage: vi.fn(() => false),
+    parseImageDimensionError: vi.fn(() => null),
+  };
+});
+
+import { runEmbeddedPiAgent } from "./run.js";
+import { runEmbeddedAttempt } from "./run/attempt.js";
+import { compactEmbeddedPiSessionDirect } from "./compact.js";
+import { log } from "./logger.js";
+
+import type { EmbeddedRunAttemptResult } from "./run/types.js";
+
+const mockedRunEmbeddedAttempt = vi.mocked(runEmbeddedAttempt);
+const mockedCompactDirect = vi.mocked(compactEmbeddedPiSessionDirect);
+
+function makeAttemptResult(
+  overrides: Partial<EmbeddedRunAttemptResult> = {},
+): EmbeddedRunAttemptResult {
+  return {
+    aborted: false,
+    timedOut: false,
+    promptError: null,
+    sessionIdUsed: "test-session",
+    assistantTexts: ["Hello!"],
+    toolMetas: [],
+    lastAssistant: undefined,
+    messagesSnapshot: [],
+    didSendViaMessagingTool: false,
+    messagingToolSentTexts: [],
+    messagingToolSentTargets: [],
+    cloudCodeAssistFormatError: false,
+    ...overrides,
+  };
+}
+
+const baseParams = {
+  sessionId: "test-session",
+  sessionKey: "test-key",
+  sessionFile: "/tmp/session.json",
+  workspaceDir: "/tmp/workspace",
+  prompt: "hello",
+  timeoutMs: 30000,
+  runId: "run-1",
+};
+
+describe("overflow compaction in run loop", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("retries after successful compaction on context overflow promptError", async () => {
+    const overflowError = new Error("request_too_large: Request size exceeds model context window");
+
+    mockedRunEmbeddedAttempt
+      .mockResolvedValueOnce(makeAttemptResult({ promptError: overflowError }))
+      .mockResolvedValueOnce(makeAttemptResult({ promptError: null }));
+
+    mockedCompactDirect.mockResolvedValueOnce({
+      ok: true,
+      compacted: true,
+      result: {
+        summary: "Compacted session",
+        firstKeptEntryId: "entry-5",
+        tokensBefore: 150000,
+      },
+    });
+
+    const result = await runEmbeddedPiAgent(baseParams);
+
+    expect(mockedCompactDirect).toHaveBeenCalledTimes(1);
+    expect(mockedCompactDirect).toHaveBeenCalledWith(
+      expect.objectContaining({ authProfileId: "test-profile" }),
+    );
+    expect(mockedRunEmbeddedAttempt).toHaveBeenCalledTimes(2);
+    expect(log.warn).toHaveBeenCalledWith(
+      expect.stringContaining("context overflow detected; attempting auto-compaction"),
+    );
+    expect(log.info).toHaveBeenCalledWith(expect.stringContaining("auto-compaction succeeded"));
+    // Should not be an error result
+    expect(result.meta.error).toBeUndefined();
+  });
+
+  it("returns error if compaction fails", async () => {
+    const overflowError = new Error("request_too_large: Request size exceeds model context window");
+
+    mockedRunEmbeddedAttempt.mockResolvedValue(makeAttemptResult({ promptError: overflowError }));
+
+    mockedCompactDirect.mockResolvedValueOnce({
+      ok: false,
+      compacted: false,
+      reason: "nothing to compact",
+    });
+
+    const result = await runEmbeddedPiAgent(baseParams);
+
+    expect(mockedCompactDirect).toHaveBeenCalledTimes(1);
+    expect(mockedRunEmbeddedAttempt).toHaveBeenCalledTimes(1);
+    expect(result.meta.error?.kind).toBe("context_overflow");
+    expect(result.payloads?.[0]?.isError).toBe(true);
+    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("auto-compaction failed"));
+  });
+
+  it("returns error if overflow happens again after compaction", async () => {
+    const overflowError = new Error("request_too_large: Request size exceeds model context window");
+
+    mockedRunEmbeddedAttempt
+      .mockResolvedValueOnce(makeAttemptResult({ promptError: overflowError }))
+      .mockResolvedValueOnce(makeAttemptResult({ promptError: overflowError }));
+
+    mockedCompactDirect.mockResolvedValueOnce({
+      ok: true,
+      compacted: true,
+      result: {
+        summary: "Compacted",
+        firstKeptEntryId: "entry-3",
+        tokensBefore: 180000,
+      },
+    });
+
+    const result = await runEmbeddedPiAgent(baseParams);
+
+    // Compaction attempted only once
+    expect(mockedCompactDirect).toHaveBeenCalledTimes(1);
+    // Two attempts: first overflow -> compact -> retry -> second overflow -> return error
+    expect(mockedRunEmbeddedAttempt).toHaveBeenCalledTimes(2);
+    expect(result.meta.error?.kind).toBe("context_overflow");
+    expect(result.payloads?.[0]?.isError).toBe(true);
+  });
+
+  it("does not attempt compaction for compaction_failure errors", async () => {
+    const compactionFailureError = new Error(
+      "request_too_large: summarization failed - Request size exceeds model context window",
+    );
+
+    mockedRunEmbeddedAttempt.mockResolvedValue(
+      makeAttemptResult({ promptError: compactionFailureError }),
+    );
+
+    const result = await runEmbeddedPiAgent(baseParams);
+
+    expect(mockedCompactDirect).not.toHaveBeenCalled();
+    expect(mockedRunEmbeddedAttempt).toHaveBeenCalledTimes(1);
+    expect(result.meta.error?.kind).toBe("compaction_failure");
+  });
+});
@@ -42,6 +42,7 @@ import {
 } from "../pi-embedded-helpers.js";
 import { normalizeUsage, type UsageLike } from "../usage.js";

+import { compactEmbeddedPiSessionDirect } from "./compact.js";
 import { resolveGlobalLane, resolveSessionLane } from "./lanes.js";
 import { log } from "./logger.js";
 import { resolveModel } from "./model.js";
@@ -290,6 +291,7 @@ export async function runEmbeddedPiAgent(
        }
      }

+      let overflowCompactionAttempted = false;
      try {
        while (true) {
          attemptedThinking.add(thinkLevel);
@@ -358,9 +360,42 @@ export async function runEmbeddedPiAgent(
          if (promptError && !aborted) {
            const errorText = describeUnknownError(promptError);
            if (isContextOverflowError(errorText)) {
-              const kind = isCompactionFailureError(errorText)
-                ? "compaction_failure"
-                : "context_overflow";
+              const isCompactionFailure = isCompactionFailureError(errorText);
+              // Attempt auto-compaction on context overflow (not compaction_failure)
+              if (!isCompactionFailure && !overflowCompactionAttempted) {
+                log.warn(
+                  `context overflow detected; attempting auto-compaction for ${provider}/${modelId}`,
+                );
+                overflowCompactionAttempted = true;
+                const compactResult = await compactEmbeddedPiSessionDirect({
+                  sessionId: params.sessionId,
+                  sessionKey: params.sessionKey,
+                  messageChannel: params.messageChannel,
+                  messageProvider: params.messageProvider,
+                  agentAccountId: params.agentAccountId,
+                  authProfileId: lastProfileId,
+                  sessionFile: params.sessionFile,
+                  workspaceDir: params.workspaceDir,
+                  agentDir,
+                  config: params.config,
+                  skillsSnapshot: params.skillsSnapshot,
+                  provider,
+                  model: modelId,
+                  thinkLevel,
+                  reasoningLevel: params.reasoningLevel,
+                  bashElevated: params.bashElevated,
+                  extraSystemPrompt: params.extraSystemPrompt,
+                  ownerNumbers: params.ownerNumbers,
+                });
+                if (compactResult.compacted) {
+                  log.info(`auto-compaction succeeded for ${provider}/${modelId}; retrying prompt`);
+                  continue;
+                }
+                log.warn(
+                  `auto-compaction failed for ${provider}/${modelId}: ${compactResult.reason ?? "nothing to compact"}`,
+                );
+              }
+              const kind = isCompactionFailure ? "compaction_failure" : "context_overflow";
              return {
                payloads: [
                  {
@@ -460,6 +460,22 @@ File contents here`,
    expect(result).toBe("The actual answer.");
  });

+  it("strips final tags while keeping content", () => {
+    const msg: AssistantMessage = {
+      role: "assistant",
+      content: [
+        {
+          type: "text",
+          text: "<final>\nAnswer\n</final>",
+        },
+      ],
+      timestamp: Date.now(),
+    };
+
+    const result = extractAssistantText(msg);
+    expect(result).toBe("Answer");
+  });
+
  it("strips thought tags", () => {
    const msg: AssistantMessage = {
      role: "assistant",
@@ -1,4 +1,5 @@
 import type { AssistantMessage } from "@mariozechner/pi-ai";
+import { stripReasoningTagsFromText } from "../shared/text/reasoning-tags.js";
 import { sanitizeUserFacingText } from "./pi-embedded-helpers.js";
 import { formatToolDetail, resolveToolDisplay } from "./tool-display.js";

@@ -166,36 +167,7 @@ export function stripDowngradedToolCallText(text: string): string {
 * that slip through other filtering mechanisms.
 */
 export function stripThinkingTagsFromText(text: string): string {
-  if (!text) return text;
-  // Quick check to avoid regex overhead when no tags present.
-  if (!/(?:think(?:ing)?|thought|antthinking)/i.test(text)) return text;
-
-  const tagRe = /<\s*(\/?)\s*(?:think(?:ing)?|thought|antthinking)\b[^>]*>/gi;
-  let result = "";
-  let lastIndex = 0;
-  let inThinking = false;
-
-  for (const match of text.matchAll(tagRe)) {
-    const idx = match.index ?? 0;
-    const isClose = match[1] === "/";
-
-    if (!inThinking && !isClose) {
-      // Opening tag - save text before it.
-      result += text.slice(lastIndex, idx);
-      inThinking = true;
-    } else if (inThinking && isClose) {
-      // Closing tag - skip content inside.
-      inThinking = false;
-    }
-    lastIndex = idx + match[0].length;
-  }
-
-  // Append remaining text if we're not inside thinking.
-  if (!inThinking) {
-    result += text.slice(lastIndex);
-  }
-
-  return result.trim();
+  return stripReasoningTagsFromText(text, { mode: "strict", trim: "both" });
 }

 export function extractAssistantText(msg: AssistantMessage): string {
@@ -164,6 +164,13 @@ function buildChatCommands(): ChatCommandDefinition[] {
      acceptsArgs: true,
      scope: "text",
    }),
+    defineChatCommand({
+      key: "approve",
+      nativeName: "approve",
+      description: "Approve or deny exec requests.",
+      textAlias: "/approve",
+      acceptsArgs: true,
+    }),
    defineChatCommand({
      key: "context",
      nativeName: "context",
@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ClawdbotConfig } from "../../config/config.js";
+import type { MsgContext } from "../templating.js";
+import { buildCommandContext, handleCommands } from "./commands.js";
+import { parseInlineDirectives } from "./directive-handling.js";
+import { callGateway } from "../../gateway/call.js";
+
+vi.mock("../../gateway/call.js", () => ({
+  callGateway: vi.fn(),
+}));
+
+function buildParams(commandBody: string, cfg: ClawdbotConfig, ctxOverrides?: Partial<MsgContext>) {
+  const ctx = {
+    Body: commandBody,
+    CommandBody: commandBody,
+    CommandSource: "text",
+    CommandAuthorized: true,
+    Provider: "whatsapp",
+    Surface: "whatsapp",
+    ...ctxOverrides,
+  } as MsgContext;
+
+  const command = buildCommandContext({
+    ctx,
+    cfg,
+    isGroup: false,
+    triggerBodyNormalized: commandBody.trim().toLowerCase(),
+    commandAuthorized: true,
+  });
+
+  return {
+    ctx,
+    cfg,
+    command,
+    directives: parseInlineDirectives(commandBody),
+    elevated: { enabled: true, allowed: true, failures: [] },
+    sessionKey: "agent:main:main",
+    workspaceDir: "/tmp",
+    defaultGroupActivation: () => "mention",
+    resolvedVerboseLevel: "off" as const,
+    resolvedReasoningLevel: "off" as const,
+    resolveDefaultThinkingLevel: async () => undefined,
+    provider: "whatsapp",
+    model: "test-model",
+    contextTokens: 0,
+    isGroup: false,
+  };
+}
+
+describe("/approve command", () => {
+  it("rejects invalid usage", async () => {
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+    } as ClawdbotConfig;
+    const params = buildParams("/approve", cfg);
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Usage: /approve");
+  });
+
+  it("submits approval", async () => {
+    const cfg = {
+      commands: { text: true },
+      channels: { whatsapp: { allowFrom: ["*"] } },
+    } as ClawdbotConfig;
+    const params = buildParams("/approve abc allow-once", cfg, { SenderId: "123" });
+
+    const mockCallGateway = vi.mocked(callGateway);
+    mockCallGateway.mockResolvedValueOnce({ ok: true });
+
+    const result = await handleCommands(params);
+    expect(result.shouldContinue).toBe(false);
+    expect(result.reply?.text).toContain("Exec approval allow-once submitted");
+    expect(mockCallGateway).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: "exec.approval.resolve",
+        params: { id: "abc", decision: "allow-once" },
+      }),
+    );
+  });
+});
@@ -0,0 +1,101 @@
+import { callGateway } from "../../gateway/call.js";
+import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../utils/message-channel.js";
+import { logVerbose } from "../../globals.js";
+import type { CommandHandler } from "./commands-types.js";
+
+const COMMAND = "/approve";
+
+const DECISION_ALIASES: Record<string, "allow-once" | "allow-always" | "deny"> = {
+  allow: "allow-once",
+  once: "allow-once",
+  "allow-once": "allow-once",
+  allowonce: "allow-once",
+  always: "allow-always",
+  "allow-always": "allow-always",
+  allowalways: "allow-always",
+  deny: "deny",
+  reject: "deny",
+  block: "deny",
+};
+
+type ParsedApproveCommand =
+  | { ok: true; id: string; decision: "allow-once" | "allow-always" | "deny" }
+  | { ok: false; error: string };
+
+function parseApproveCommand(raw: string): ParsedApproveCommand | null {
+  const trimmed = raw.trim();
+  if (!trimmed.toLowerCase().startsWith(COMMAND)) return null;
+  const rest = trimmed.slice(COMMAND.length).trim();
+  if (!rest) {
+    return { ok: false, error: "Usage: /approve <id> allow-once|allow-always|deny" };
+  }
+  const tokens = rest.split(/\s+/).filter(Boolean);
+  if (tokens.length < 2) {
+    return { ok: false, error: "Usage: /approve <id> allow-once|allow-always|deny" };
+  }
+
+  const first = tokens[0].toLowerCase();
+  const second = tokens[1].toLowerCase();
+
+  if (DECISION_ALIASES[first]) {
+    return {
+      ok: true,
+      decision: DECISION_ALIASES[first],
+      id: tokens.slice(1).join(" ").trim(),
+    };
+  }
+  if (DECISION_ALIASES[second]) {
+    return {
+      ok: true,
+      decision: DECISION_ALIASES[second],
+      id: tokens[0],
+    };
+  }
+  return { ok: false, error: "Usage: /approve <id> allow-once|allow-always|deny" };
+}
+
+function buildResolvedByLabel(params: Parameters<CommandHandler>[0]): string {
+  const channel = params.command.channel;
+  const sender = params.command.senderId ?? "unknown";
+  return `${channel}:${sender}`;
+}
+
+export const handleApproveCommand: CommandHandler = async (params, allowTextCommands) => {
+  if (!allowTextCommands) return null;
+  const normalized = params.command.commandBodyNormalized;
+  const parsed = parseApproveCommand(normalized);
+  if (!parsed) return null;
+  if (!params.command.isAuthorizedSender) {
+    logVerbose(
+      `Ignoring /approve from unauthorized sender: ${params.command.senderId || "<unknown>"}`,
+    );
+    return { shouldContinue: false };
+  }
+
+  if (!parsed.ok) {
+    return { shouldContinue: false, reply: { text: parsed.error } };
+  }
+
+  const resolvedBy = buildResolvedByLabel(params);
+  try {
+    await callGateway({
+      method: "exec.approval.resolve",
+      params: { id: parsed.id, decision: parsed.decision },
+      clientName: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
+      clientDisplayName: `Chat approval (${resolvedBy})`,
+      mode: GATEWAY_CLIENT_MODES.BACKEND,
+    });
+  } catch (err) {
+    return {
+      shouldContinue: false,
+      reply: {
+        text: `❌ Failed to submit approval: ${String(err)}`,
+      },
+    };
+  }
+
+  return {
+    shouldContinue: false,
+    reply: { text: `✅ Exec approval ${parsed.decision} submitted for ${parsed.id}.` },
+  };
+};
@@ -14,6 +14,7 @@ import {
  handleWhoamiCommand,
 } from "./commands-info.js";
 import { handleAllowlistCommand } from "./commands-allowlist.js";
+import { handleApproveCommand } from "./commands-approve.js";
 import { handleSubagentsCommand } from "./commands-subagents.js";
 import { handleModelsCommand } from "./commands-models.js";
 import { handleTtsCommands } from "./commands-tts.js";
@@ -45,6 +46,7 @@ const HANDLERS: CommandHandler[] = [
  handleCommandsListCommand,
  handleStatusCommand,
  handleAllowlistCommand,
+  handleApproveCommand,
  handleContextCommand,
  handleWhoamiCommand,
  handleSubagentsCommand,
@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from "vitest";
+
+describe("gateway.remote.transport", () => {
+  it("accepts direct transport", async () => {
+    vi.resetModules();
+    const { validateConfigObject } = await import("./config.js");
+    const res = validateConfigObject({
+      gateway: {
+        remote: {
+          transport: "direct",
+          url: "wss://gateway.example.ts.net",
+        },
+      },
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects unknown transport", async () => {
+    vi.resetModules();
+    const { validateConfigObject } = await import("./config.js");
+    const res = validateConfigObject({
+      gateway: {
+        remote: {
+          transport: "udp",
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues[0]?.path).toBe("gateway.remote.transport");
+    }
+  });
+});
@@ -0,0 +1,29 @@
+export type ExecApprovalForwardingMode = "session" | "targets" | "both";
+
+export type ExecApprovalForwardTarget = {
+  /** Channel id (e.g. "discord", "slack", or plugin channel id). */
+  channel: string;
+  /** Destination id (channel id, user id, etc. depending on channel). */
+  to: string;
+  /** Optional account id for multi-account channels. */
+  accountId?: string;
+  /** Optional thread id to reply inside a thread. */
+  threadId?: string | number;
+};
+
+export type ExecApprovalForwardingConfig = {
+  /** Enable forwarding exec approvals to chat channels. Default: false. */
+  enabled?: boolean;
+  /** Delivery mode (session=origin chat, targets=config targets, both=both). Default: session. */
+  mode?: ExecApprovalForwardingMode;
+  /** Only forward approvals for these agent IDs. Omit = all agents. */
+  agentFilter?: string[];
+  /** Only forward approvals matching these session key patterns (substring or regex). */
+  sessionFilter?: string[];
+  /** Explicit delivery targets (used when mode includes targets). */
+  targets?: ExecApprovalForwardTarget[];
+};
+
+export type ApprovalsConfig = {
+  exec?: ExecApprovalForwardingConfig;
+};
@@ -1,4 +1,5 @@
 import type { AgentBinding, AgentsConfig } from "./types.agents.js";
+import type { ApprovalsConfig } from "./types.approvals.js";
 import type { AuthConfig } from "./types.auth.js";
 import type { DiagnosticsConfig, LoggingConfig, SessionConfig, WebConfig } from "./types.base.js";
 import type { BrowserConfig } from "./types.browser.js";
@@ -84,6 +85,7 @@ export type ClawdbotConfig = {
  audio?: AudioConfig;
  messages?: MessagesConfig;
  commands?: CommandsConfig;
+  approvals?: ApprovalsConfig;
  session?: SessionConfig;
  web?: WebConfig;
  channels?: ChannelsConfig;
@@ -72,6 +72,17 @@ export type DiscordActionConfig = {
  channels?: boolean;
 };

+export type DiscordExecApprovalConfig = {
+  /** Enable exec approval forwarding to Discord DMs. Default: false. */
+  enabled?: boolean;
+  /** Discord user IDs to receive approval prompts. Required if enabled. */
+  approvers?: Array<string | number>;
+  /** Only forward approvals for these agent IDs. Omit = all agents. */
+  agentFilter?: string[];
+  /** Only forward approvals matching these session key patterns (substring or regex). */
+  sessionFilter?: string[];
+};
+
 export type DiscordAccountConfig = {
  /** Optional display name for this account (used in CLI/UI lists). */
  name?: string;
@@ -124,6 +135,8 @@ export type DiscordAccountConfig = {
  guilds?: Record<string, DiscordGuildEntry>;
  /** Heartbeat visibility settings for this channel. */
  heartbeat?: ChannelHeartbeatVisibilityConfig;
+  /** Exec approval forwarding configuration. */
+  execApprovals?: DiscordExecApprovalConfig;
 };

 export type DiscordConfig = {
@@ -80,6 +80,8 @@ export type GatewayTailscaleConfig = {
 export type GatewayRemoteConfig = {
  /** Remote Gateway WebSocket URL (ws:// or wss://). */
  url?: string;
+  /** Transport for macOS remote connections (ssh tunnel or direct WS). */
+  transport?: "ssh" | "direct";
  /** Token for remote auth (when the gateway requires token auth). */
  token?: string;
  /** Password for remote auth (when the gateway requires password auth). */
@@ -2,6 +2,7 @@

 export * from "./types.agent-defaults.js";
 export * from "./types.agents.js";
+export * from "./types.approvals.js";
 export * from "./types.auth.js";
 export * from "./types.base.js";
 export * from "./types.browser.js";
@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+const ExecApprovalForwardTargetSchema = z
+  .object({
+    channel: z.string().min(1),
+    to: z.string().min(1),
+    accountId: z.string().optional(),
+    threadId: z.union([z.string(), z.number()]).optional(),
+  })
+  .strict();
+
+const ExecApprovalForwardingSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    mode: z.union([z.literal("session"), z.literal("targets"), z.literal("both")]).optional(),
+    agentFilter: z.array(z.string()).optional(),
+    sessionFilter: z.array(z.string()).optional(),
+    targets: z.array(ExecApprovalForwardTargetSchema).optional(),
+  })
+  .strict()
+  .optional();
+
+export const ApprovalsSchema = z
+  .object({
+    exec: ExecApprovalForwardingSchema,
+  })
+  .strict()
+  .optional();
@@ -244,6 +244,15 @@ export const DiscordAccountSchema = z
    dm: DiscordDmSchema.optional(),
    guilds: z.record(z.string(), DiscordGuildSchema.optional()).optional(),
    heartbeat: ChannelHeartbeatVisibilitySchema,
+    execApprovals: z
+      .object({
+        enabled: z.boolean().optional(),
+        approvers: z.array(z.union([z.string(), z.number()])).optional(),
+        agentFilter: z.array(z.string()).optional(),
+        sessionFilter: z.array(z.string()).optional(),
+      })
+      .strict()
+      .optional(),
  })
  .strict();

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ToolsSchema } from "./zod-schema.agent-runtime.js";
+import { ApprovalsSchema } from "./zod-schema.approvals.js";
 import { AgentsSchema, AudioSchema, BindingsSchema, BroadcastSchema } from "./zod-schema.agents.js";
 import { HexColorSchema, ModelsConfigSchema } from "./zod-schema.core.js";
 import { HookMappingSchema, HooksGmailSchema, InternalHooksSchema } from "./zod-schema.hooks.js";
@@ -220,6 +221,7 @@ export const ClawdbotSchema = z
      .optional(),
    messages: MessagesSchema,
    commands: CommandsSchema,
+    approvals: ApprovalsSchema,
    session: SessionSchema,
    cron: z
      .object({
@@ -332,6 +334,7 @@ export const ClawdbotSchema = z
        remote: z
          .object({
            url: z.string().optional(),
+            transport: z.union([z.literal("ssh"), z.literal("direct")]).optional(),
            token: z.string().optional(),
            password: z.string().optional(),
            tlsFingerprint: z.string().optional(),
@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildExecApprovalCustomId,
+  parseExecApprovalData,
+  type ExecApprovalRequest,
+  DiscordExecApprovalHandler,
+} from "./exec-approvals.js";
+import type { DiscordExecApprovalConfig } from "../../config/types.discord.js";
+
+describe("buildExecApprovalCustomId", () => {
+  it("encodes approval id and action", () => {
+    const customId = buildExecApprovalCustomId("abc-123", "allow-once");
+    expect(customId).toBe("execapproval:id=abc-123;action=allow-once");
+  });
+
+  it("encodes special characters in approval id", () => {
+    const customId = buildExecApprovalCustomId("abc=123;test", "deny");
+    expect(customId).toBe("execapproval:id=abc%3D123%3Btest;action=deny");
+  });
+});
+
+describe("parseExecApprovalData", () => {
+  it("parses valid data", () => {
+    const result = parseExecApprovalData({ id: "abc-123", action: "allow-once" });
+    expect(result).toEqual({ approvalId: "abc-123", action: "allow-once" });
+  });
+
+  it("parses encoded data", () => {
+    const result = parseExecApprovalData({
+      id: "abc%3D123%3Btest",
+      action: "allow-always",
+    });
+    expect(result).toEqual({ approvalId: "abc=123;test", action: "allow-always" });
+  });
+
+  it("rejects invalid action", () => {
+    const result = parseExecApprovalData({ id: "abc-123", action: "invalid" });
+    expect(result).toBeNull();
+  });
+
+  it("rejects missing id", () => {
+    const result = parseExecApprovalData({ action: "deny" });
+    expect(result).toBeNull();
+  });
+
+  it("rejects missing action", () => {
+    const result = parseExecApprovalData({ id: "abc-123" });
+    expect(result).toBeNull();
+  });
+
+  it("rejects null/undefined input", () => {
+    expect(parseExecApprovalData(null as any)).toBeNull();
+    expect(parseExecApprovalData(undefined as any)).toBeNull();
+  });
+
+  it("accepts all valid actions", () => {
+    expect(parseExecApprovalData({ id: "x", action: "allow-once" })?.action).toBe("allow-once");
+    expect(parseExecApprovalData({ id: "x", action: "allow-always" })?.action).toBe("allow-always");
+    expect(parseExecApprovalData({ id: "x", action: "deny" })?.action).toBe("deny");
+  });
+});
+
+describe("roundtrip encoding", () => {
+  it("encodes and decodes correctly", () => {
+    const approvalId = "test-approval-with=special;chars&more";
+    const action = "allow-always" as const;
+    const customId = buildExecApprovalCustomId(approvalId, action);
+
+    // Parse the key=value pairs from the custom ID
+    const parts = customId.split(";");
+    const data: Record<string, string> = {};
+    for (const part of parts) {
+      const match = part.match(/^([^:]+:)?([^=]+)=(.+)$/);
+      if (match) {
+        data[match[2]] = match[3];
+      }
+    }
+
+    const result = parseExecApprovalData(data);
+    expect(result).toEqual({ approvalId, action });
+  });
+});
+
+describe("DiscordExecApprovalHandler.shouldHandle", () => {
+  function createHandler(config: DiscordExecApprovalConfig) {
+    return new DiscordExecApprovalHandler({
+      token: "test-token",
+      accountId: "default",
+      config,
+      cfg: {},
+    });
+  }
+
+  function createRequest(
+    overrides: Partial<ExecApprovalRequest["request"]> = {},
+  ): ExecApprovalRequest {
+    return {
+      id: "test-id",
+      request: {
+        command: "echo hello",
+        cwd: "/home/user",
+        host: "gateway",
+        agentId: "test-agent",
+        sessionKey: "agent:test-agent:discord:123",
+        ...overrides,
+      },
+      createdAtMs: Date.now(),
+      expiresAtMs: Date.now() + 60000,
+    };
+  }
+
+  it("returns false when disabled", () => {
+    const handler = createHandler({ enabled: false, approvers: ["123"] });
+    expect(handler.shouldHandle(createRequest())).toBe(false);
+  });
+
+  it("returns false when no approvers", () => {
+    const handler = createHandler({ enabled: true, approvers: [] });
+    expect(handler.shouldHandle(createRequest())).toBe(false);
+  });
+
+  it("returns true with minimal config", () => {
+    const handler = createHandler({ enabled: true, approvers: ["123"] });
+    expect(handler.shouldHandle(createRequest())).toBe(true);
+  });
+
+  it("filters by agent ID", () => {
+    const handler = createHandler({
+      enabled: true,
+      approvers: ["123"],
+      agentFilter: ["allowed-agent"],
+    });
+    expect(handler.shouldHandle(createRequest({ agentId: "allowed-agent" }))).toBe(true);
+    expect(handler.shouldHandle(createRequest({ agentId: "other-agent" }))).toBe(false);
+    expect(handler.shouldHandle(createRequest({ agentId: null }))).toBe(false);
+  });
+
+  it("filters by session key substring", () => {
+    const handler = createHandler({
+      enabled: true,
+      approvers: ["123"],
+      sessionFilter: ["discord"],
+    });
+    expect(handler.shouldHandle(createRequest({ sessionKey: "agent:test:discord:123" }))).toBe(
+      true,
+    );
+    expect(handler.shouldHandle(createRequest({ sessionKey: "agent:test:telegram:123" }))).toBe(
+      false,
+    );
+    expect(handler.shouldHandle(createRequest({ sessionKey: null }))).toBe(false);
+  });
+
+  it("filters by session key regex", () => {
+    const handler = createHandler({
+      enabled: true,
+      approvers: ["123"],
+      sessionFilter: ["^agent:.*:discord:"],
+    });
+    expect(handler.shouldHandle(createRequest({ sessionKey: "agent:test:discord:123" }))).toBe(
+      true,
+    );
+    expect(handler.shouldHandle(createRequest({ sessionKey: "other:test:discord:123" }))).toBe(
+      false,
+    );
+  });
+
+  it("combines agent and session filters", () => {
+    const handler = createHandler({
+      enabled: true,
+      approvers: ["123"],
+      agentFilter: ["my-agent"],
+      sessionFilter: ["discord"],
+    });
+    expect(
+      handler.shouldHandle(
+        createRequest({
+          agentId: "my-agent",
+          sessionKey: "agent:my-agent:discord:123",
+        }),
+      ),
+    ).toBe(true);
+    expect(
+      handler.shouldHandle(
+        createRequest({
+          agentId: "other-agent",
+          sessionKey: "agent:other:discord:123",
+        }),
+      ),
+    ).toBe(false);
+    expect(
+      handler.shouldHandle(
+        createRequest({
+          agentId: "my-agent",
+          sessionKey: "agent:my-agent:telegram:123",
+        }),
+      ),
+    ).toBe(false);
+  });
+});
@@ -0,0 +1,549 @@
+import { Button, type ButtonInteraction, type ComponentData } from "@buape/carbon";
+import { ButtonStyle, Routes } from "discord-api-types/v10";
+import type { ClawdbotConfig } from "../../config/config.js";
+import { GatewayClient } from "../../gateway/client.js";
+import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../utils/message-channel.js";
+import type { EventFrame } from "../../gateway/protocol/index.js";
+import type { ExecApprovalDecision } from "../../infra/exec-approvals.js";
+import { createDiscordClient } from "../send.shared.js";
+import { logDebug, logError } from "../../logger.js";
+import type { DiscordExecApprovalConfig } from "../../config/types.discord.js";
+import type { RuntimeEnv } from "../../runtime.js";
+
+const EXEC_APPROVAL_KEY = "execapproval";
+
+export type ExecApprovalRequest = {
+  id: string;
+  request: {
+    command: string;
+    cwd?: string | null;
+    host?: string | null;
+    security?: string | null;
+    ask?: string | null;
+    agentId?: string | null;
+    resolvedPath?: string | null;
+    sessionKey?: string | null;
+  };
+  createdAtMs: number;
+  expiresAtMs: number;
+};
+
+export type ExecApprovalResolved = {
+  id: string;
+  decision: ExecApprovalDecision;
+  resolvedBy?: string | null;
+  ts: number;
+};
+
+type PendingApproval = {
+  discordMessageId: string;
+  discordChannelId: string;
+  timeoutId: NodeJS.Timeout;
+};
+
+function encodeCustomIdValue(value: string): string {
+  return encodeURIComponent(value);
+}
+
+function decodeCustomIdValue(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function buildExecApprovalCustomId(
+  approvalId: string,
+  action: ExecApprovalDecision,
+): string {
+  return [`${EXEC_APPROVAL_KEY}:id=${encodeCustomIdValue(approvalId)}`, `action=${action}`].join(
+    ";",
+  );
+}
+
+export function parseExecApprovalData(
+  data: ComponentData,
+): { approvalId: string; action: ExecApprovalDecision } | null {
+  if (!data || typeof data !== "object") return null;
+  const coerce = (value: unknown) =>
+    typeof value === "string" || typeof value === "number" ? String(value) : "";
+  const rawId = coerce(data.id);
+  const rawAction = coerce(data.action);
+  if (!rawId || !rawAction) return null;
+  const action = rawAction as ExecApprovalDecision;
+  if (action !== "allow-once" && action !== "allow-always" && action !== "deny") {
+    return null;
+  }
+  return {
+    approvalId: decodeCustomIdValue(rawId),
+    action,
+  };
+}
+
+function formatExecApprovalEmbed(request: ExecApprovalRequest) {
+  const commandText = request.request.command;
+  const commandPreview =
+    commandText.length > 1000 ? `${commandText.slice(0, 1000)}...` : commandText;
+  const expiresIn = Math.max(0, Math.round((request.expiresAtMs - Date.now()) / 1000));
+
+  const fields: Array<{ name: string; value: string; inline: boolean }> = [
+    {
+      name: "Command",
+      value: `\`\`\`\n${commandPreview}\n\`\`\``,
+      inline: false,
+    },
+  ];
+
+  if (request.request.cwd) {
+    fields.push({
+      name: "Working Directory",
+      value: request.request.cwd,
+      inline: true,
+    });
+  }
+
+  if (request.request.host) {
+    fields.push({
+      name: "Host",
+      value: request.request.host,
+      inline: true,
+    });
+  }
+
+  if (request.request.agentId) {
+    fields.push({
+      name: "Agent",
+      value: request.request.agentId,
+      inline: true,
+    });
+  }
+
+  return {
+    title: "Exec Approval Required",
+    description: "A command needs your approval.",
+    color: 0xffa500, // Orange
+    fields,
+    footer: { text: `Expires in ${expiresIn}s | ID: ${request.id}` },
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function formatResolvedEmbed(
+  request: ExecApprovalRequest,
+  decision: ExecApprovalDecision,
+  resolvedBy?: string | null,
+) {
+  const commandText = request.request.command;
+  const commandPreview = commandText.length > 500 ? `${commandText.slice(0, 500)}...` : commandText;
+
+  const decisionLabel =
+    decision === "allow-once"
+      ? "Allowed (once)"
+      : decision === "allow-always"
+        ? "Allowed (always)"
+        : "Denied";
+
+  const color = decision === "deny" ? 0xed4245 : decision === "allow-always" ? 0x5865f2 : 0x57f287;
+
+  return {
+    title: `Exec Approval: ${decisionLabel}`,
+    description: resolvedBy ? `Resolved by ${resolvedBy}` : "Resolved",
+    color,
+    fields: [
+      {
+        name: "Command",
+        value: `\`\`\`\n${commandPreview}\n\`\`\``,
+        inline: false,
+      },
+    ],
+    footer: { text: `ID: ${request.id}` },
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function formatExpiredEmbed(request: ExecApprovalRequest) {
+  const commandText = request.request.command;
+  const commandPreview = commandText.length > 500 ? `${commandText.slice(0, 500)}...` : commandText;
+
+  return {
+    title: "Exec Approval: Expired",
+    description: "This approval request has expired.",
+    color: 0x99aab5, // Gray
+    fields: [
+      {
+        name: "Command",
+        value: `\`\`\`\n${commandPreview}\n\`\`\``,
+        inline: false,
+      },
+    ],
+    footer: { text: `ID: ${request.id}` },
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export type DiscordExecApprovalHandlerOpts = {
+  token: string;
+  accountId: string;
+  config: DiscordExecApprovalConfig;
+  gatewayUrl?: string;
+  cfg: ClawdbotConfig;
+  runtime?: RuntimeEnv;
+  onResolve?: (id: string, decision: ExecApprovalDecision) => Promise<void>;
+};
+
+export class DiscordExecApprovalHandler {
+  private gatewayClient: GatewayClient | null = null;
+  private pending = new Map<string, PendingApproval>();
+  private requestCache = new Map<string, ExecApprovalRequest>();
+  private opts: DiscordExecApprovalHandlerOpts;
+  private started = false;
+
+  constructor(opts: DiscordExecApprovalHandlerOpts) {
+    this.opts = opts;
+  }
+
+  shouldHandle(request: ExecApprovalRequest): boolean {
+    const config = this.opts.config;
+    if (!config.enabled) return false;
+    if (!config.approvers || config.approvers.length === 0) return false;
+
+    // Check agent filter
+    if (config.agentFilter?.length) {
+      if (!request.request.agentId) return false;
+      if (!config.agentFilter.includes(request.request.agentId)) return false;
+    }
+
+    // Check session filter (substring match)
+    if (config.sessionFilter?.length) {
+      const session = request.request.sessionKey;
+      if (!session) return false;
+      const matches = config.sessionFilter.some((p) => {
+        try {
+          return session.includes(p) || new RegExp(p).test(session);
+        } catch {
+          return session.includes(p);
+        }
+      });
+      if (!matches) return false;
+    }
+
+    return true;
+  }
+
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+
+    const config = this.opts.config;
+    if (!config.enabled) {
+      logDebug("discord exec approvals: disabled");
+      return;
+    }
+
+    if (!config.approvers || config.approvers.length === 0) {
+      logDebug("discord exec approvals: no approvers configured");
+      return;
+    }
+
+    logDebug("discord exec approvals: starting handler");
+
+    this.gatewayClient = new GatewayClient({
+      url: this.opts.gatewayUrl ?? "ws://127.0.0.1:18789",
+      clientName: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
+      clientDisplayName: "Discord Exec Approvals",
+      mode: GATEWAY_CLIENT_MODES.BACKEND,
+      scopes: ["operator.approvals"],
+      onEvent: (evt) => this.handleGatewayEvent(evt),
+      onHelloOk: () => {
+        logDebug("discord exec approvals: connected to gateway");
+      },
+      onConnectError: (err) => {
+        logError(`discord exec approvals: connect error: ${err.message}`);
+      },
+      onClose: (code, reason) => {
+        logDebug(`discord exec approvals: gateway closed: ${code} ${reason}`);
+      },
+    });
+
+    this.gatewayClient.start();
+  }
+
+  async stop(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+
+    // Clear all pending timeouts
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timeoutId);
+    }
+    this.pending.clear();
+    this.requestCache.clear();
+
+    this.gatewayClient?.stop();
+    this.gatewayClient = null;
+
+    logDebug("discord exec approvals: stopped");
+  }
+
+  private handleGatewayEvent(evt: EventFrame): void {
+    if (evt.event === "exec.approval.requested") {
+      const request = evt.payload as ExecApprovalRequest;
+      void this.handleApprovalRequested(request);
+    } else if (evt.event === "exec.approval.resolved") {
+      const resolved = evt.payload as ExecApprovalResolved;
+      void this.handleApprovalResolved(resolved);
+    }
+  }
+
+  private async handleApprovalRequested(request: ExecApprovalRequest): Promise<void> {
+    if (!this.shouldHandle(request)) return;
+
+    logDebug(`discord exec approvals: received request ${request.id}`);
+
+    this.requestCache.set(request.id, request);
+
+    const { rest, request: discordRequest } = createDiscordClient(
+      { token: this.opts.token, accountId: this.opts.accountId },
+      this.opts.cfg,
+    );
+
+    const embed = formatExecApprovalEmbed(request);
+
+    // Build action rows with buttons
+    const components = [
+      {
+        type: 1, // ACTION_ROW
+        components: [
+          {
+            type: 2, // BUTTON
+            style: ButtonStyle.Success,
+            label: "Allow once",
+            custom_id: buildExecApprovalCustomId(request.id, "allow-once"),
+          },
+          {
+            type: 2, // BUTTON
+            style: ButtonStyle.Primary,
+            label: "Always allow",
+            custom_id: buildExecApprovalCustomId(request.id, "allow-always"),
+          },
+          {
+            type: 2, // BUTTON
+            style: ButtonStyle.Danger,
+            label: "Deny",
+            custom_id: buildExecApprovalCustomId(request.id, "deny"),
+          },
+        ],
+      },
+    ];
+
+    const approvers = this.opts.config.approvers ?? [];
+
+    for (const approver of approvers) {
+      const userId = String(approver);
+      try {
+        // Create DM channel
+        const dmChannel = (await discordRequest(
+          () =>
+            rest.post(Routes.userChannels(), {
+              body: { recipient_id: userId },
+            }) as Promise<{ id: string }>,
+          "dm-channel",
+        )) as { id: string };
+
+        if (!dmChannel?.id) {
+          logError(`discord exec approvals: failed to create DM for user ${userId}`);
+          continue;
+        }
+
+        // Send message with embed and buttons
+        const message = (await discordRequest(
+          () =>
+            rest.post(Routes.channelMessages(dmChannel.id), {
+              body: {
+                embeds: [embed],
+                components,
+              },
+            }) as Promise<{ id: string; channel_id: string }>,
+          "send-approval",
+        )) as { id: string; channel_id: string };
+
+        if (!message?.id) {
+          logError(`discord exec approvals: failed to send message to user ${userId}`);
+          continue;
+        }
+
+        // Set up timeout
+        const timeoutMs = Math.max(0, request.expiresAtMs - Date.now());
+        const timeoutId = setTimeout(() => {
+          void this.handleApprovalTimeout(request.id);
+        }, timeoutMs);
+
+        this.pending.set(request.id, {
+          discordMessageId: message.id,
+          discordChannelId: dmChannel.id,
+          timeoutId,
+        });
+
+        logDebug(`discord exec approvals: sent approval ${request.id} to user ${userId}`);
+      } catch (err) {
+        logError(`discord exec approvals: failed to notify user ${userId}: ${String(err)}`);
+      }
+    }
+  }
+
+  private async handleApprovalResolved(resolved: ExecApprovalResolved): Promise<void> {
+    const pending = this.pending.get(resolved.id);
+    if (!pending) return;
+
+    clearTimeout(pending.timeoutId);
+    this.pending.delete(resolved.id);
+
+    const request = this.requestCache.get(resolved.id);
+    this.requestCache.delete(resolved.id);
+
+    if (!request) return;
+
+    logDebug(`discord exec approvals: resolved ${resolved.id} with ${resolved.decision}`);
+
+    await this.updateMessage(
+      pending.discordChannelId,
+      pending.discordMessageId,
+      formatResolvedEmbed(request, resolved.decision, resolved.resolvedBy),
+    );
+  }
+
+  private async handleApprovalTimeout(approvalId: string): Promise<void> {
+    const pending = this.pending.get(approvalId);
+    if (!pending) return;
+
+    this.pending.delete(approvalId);
+
+    const request = this.requestCache.get(approvalId);
+    this.requestCache.delete(approvalId);
+
+    if (!request) return;
+
+    logDebug(`discord exec approvals: timeout for ${approvalId}`);
+
+    await this.updateMessage(
+      pending.discordChannelId,
+      pending.discordMessageId,
+      formatExpiredEmbed(request),
+    );
+  }
+
+  private async updateMessage(
+    channelId: string,
+    messageId: string,
+    embed: ReturnType<typeof formatExpiredEmbed>,
+  ): Promise<void> {
+    try {
+      const { rest, request: discordRequest } = createDiscordClient(
+        { token: this.opts.token, accountId: this.opts.accountId },
+        this.opts.cfg,
+      );
+
+      await discordRequest(
+        () =>
+          rest.patch(Routes.channelMessage(channelId, messageId), {
+            body: {
+              embeds: [embed],
+              components: [], // Remove buttons
+            },
+          }),
+        "update-approval",
+      );
+    } catch (err) {
+      logError(`discord exec approvals: failed to update message: ${String(err)}`);
+    }
+  }
+
+  async resolveApproval(approvalId: string, decision: ExecApprovalDecision): Promise<boolean> {
+    if (!this.gatewayClient) {
+      logError("discord exec approvals: gateway client not connected");
+      return false;
+    }
+
+    logDebug(`discord exec approvals: resolving ${approvalId} with ${decision}`);
+
+    try {
+      await this.gatewayClient.request("exec.approval.resolve", {
+        id: approvalId,
+        decision,
+      });
+      logDebug(`discord exec approvals: resolved ${approvalId} successfully`);
+      return true;
+    } catch (err) {
+      logError(`discord exec approvals: resolve failed: ${String(err)}`);
+      return false;
+    }
+  }
+}
+
+export type ExecApprovalButtonContext = {
+  handler: DiscordExecApprovalHandler;
+};
+
+export class ExecApprovalButton extends Button {
+  label = "execapproval";
+  customId = `${EXEC_APPROVAL_KEY}:seed=1`;
+  style = ButtonStyle.Primary;
+  private ctx: ExecApprovalButtonContext;
+
+  constructor(ctx: ExecApprovalButtonContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: ButtonInteraction, data: ComponentData): Promise<void> {
+    const parsed = parseExecApprovalData(data);
+    if (!parsed) {
+      try {
+        await interaction.update({
+          content: "This approval is no longer valid.",
+          components: [],
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    const decisionLabel =
+      parsed.action === "allow-once"
+        ? "Allowed (once)"
+        : parsed.action === "allow-always"
+          ? "Allowed (always)"
+          : "Denied";
+
+    // Update the message immediately to show the decision
+    try {
+      await interaction.update({
+        content: `Submitting decision: **${decisionLabel}**...`,
+        components: [], // Remove buttons
+      });
+    } catch {
+      // Interaction may have expired, try to continue anyway
+    }
+
+    const ok = await this.ctx.handler.resolveApproval(parsed.approvalId, parsed.action);
+
+    if (!ok) {
+      try {
+        await interaction.followUp({
+          content:
+            "Failed to submit approval decision. The request may have expired or already been resolved.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+    }
+    // On success, the handleApprovalResolved event will update the message with the final result
+  }
+}
+
+export function createExecApprovalButton(ctx: ExecApprovalButtonContext): Button {
+  return new ExecApprovalButton(ctx);
+}
@@ -37,6 +37,7 @@ import {
  createDiscordCommandArgFallbackButton,
  createDiscordNativeCommand,
 } from "./native-command.js";
+import { createExecApprovalButton, DiscordExecApprovalHandler } from "./exec-approvals.js";

 export type MonitorDiscordOpts = {
  token?: string;
@@ -406,6 +407,31 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
    }),
  );

+  // Initialize exec approvals handler if enabled
+  const execApprovalsConfig = discordCfg.execApprovals ?? {};
+  const execApprovalsHandler = execApprovalsConfig.enabled
+    ? new DiscordExecApprovalHandler({
+        token,
+        accountId: account.accountId,
+        config: execApprovalsConfig,
+        cfg,
+        runtime,
+      })
+    : null;
+
+  const components = [
+    createDiscordCommandArgFallbackButton({
+      cfg,
+      discordConfig: discordCfg,
+      accountId: account.accountId,
+      sessionPrefix,
+    }),
+  ];
+
+  if (execApprovalsHandler) {
+    components.push(createExecApprovalButton({ handler: execApprovalsHandler }));
+  }
+
  const client = new Client(
    {
      baseUrl: "http://localhost",
@@ -418,14 +444,7 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
    {
      commands,
      listeners: [],
-      components: [
-        createDiscordCommandArgFallbackButton({
-          cfg,
-          discordConfig: discordCfg,
-          accountId: account.accountId,
-          sessionPrefix,
-        }),
-      ],
+      components,
    },
    [
      new GatewayPlugin({
@@ -510,6 +529,11 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {

  runtime.log?.(`logged in to discord${botUserId ? ` as ${botUserId}` : ""}`);

+  // Start exec approvals handler after client is ready
+  if (execApprovalsHandler) {
+    await execApprovalsHandler.start();
+  }
+
  const gateway = client.getPlugin<GatewayPlugin>("gateway");
  const gatewayEmitter = getDiscordGatewayEmitter(gateway);
  const stopGatewayLogging = attachDiscordGatewayLogging({
@@ -575,6 +599,9 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) {
    if (helloTimeoutId) clearTimeout(helloTimeoutId);
    gatewayEmitter?.removeListener("debug", onGatewayDebug);
    abortSignal?.removeEventListener("abort", onAbort);
+    if (execApprovalsHandler) {
+      await execApprovalsHandler.stop();
+    }
  }
 }

@@ -1,4 +1,5 @@
 import type { ExecApprovalDecision } from "../../infra/exec-approvals.js";
+import type { ExecApprovalForwarder } from "../../infra/exec-approval-forwarder.js";
 import type { ExecApprovalManager } from "../exec-approval-manager.js";
 import {
  ErrorCodes,
@@ -9,7 +10,10 @@ import {
 } from "../protocol/index.js";
 import type { GatewayRequestHandlers } from "./types.js";

-export function createExecApprovalHandlers(manager: ExecApprovalManager): GatewayRequestHandlers {
+export function createExecApprovalHandlers(
+  manager: ExecApprovalManager,
+  opts?: { forwarder?: ExecApprovalForwarder },
+): GatewayRequestHandlers {
  return {
    "exec.approval.request": async ({ params, respond, context }) => {
      if (!validateExecApprovalRequestParams(params)) {
@@ -69,6 +73,16 @@ export function createExecApprovalHandlers(manager: ExecApprovalManager): Gatewa
        },
        { dropIfSlow: true },
      );
+      void opts?.forwarder
+        ?.handleRequested({
+          id: record.id,
+          request: record.request,
+          createdAtMs: record.createdAtMs,
+          expiresAtMs: record.expiresAtMs,
+        })
+        .catch((err) => {
+          context.logGateway?.error?.(`exec approvals: forward request failed: ${String(err)}`);
+        });
      const decision = await decisionPromise;
      respond(
        true,
@@ -112,6 +126,11 @@ export function createExecApprovalHandlers(manager: ExecApprovalManager): Gatewa
        { id: p.id, decision, resolvedBy, ts: Date.now() },
        { dropIfSlow: true },
      );
+      void opts?.forwarder
+        ?.handleResolved({ id: p.id, decision, resolvedBy, ts: Date.now() })
+        .catch((err) => {
+          context.logGateway?.error?.(`exec approvals: forward resolve failed: ${String(err)}`);
+        });
      respond(true, { ok: true }, undefined);
    },
  };
@@ -468,7 +468,10 @@ export const nodeHandlers: GatewayRequestHandlers = {
      error: p.error ?? null,
    });
    if (!ok) {
-      respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "unknown invoke id"));
+      // Late-arriving results (after invoke timeout) are expected and harmless.
+      // Return success instead of error to reduce log noise; client can discard.
+      context.logGateway.debug(`late invoke result ignored: id=${p.id} node=${p.nodeId}`);
+      respond(true, { ok: true, ignored: true }, undefined);
      return;
    }
    respond(true, { ok: true }, undefined);
@@ -43,6 +43,7 @@ import {
 import { startGatewayDiscovery } from "./server-discovery-runtime.js";
 import { ExecApprovalManager } from "./exec-approval-manager.js";
 import { createExecApprovalHandlers } from "./server-methods/exec-approval.js";
+import { createExecApprovalForwarder } from "../infra/exec-approval-forwarder.js";
 import type { startBrowserControlServerIfEnabled } from "./server-browser.js";
 import { createChannelManager } from "./server-channels.js";
 import { createAgentEventHandler } from "./server-chat.js";
@@ -344,9 +345,19 @@ export async function startGatewayServer(

  setSkillsRemoteRegistry(nodeRegistry);
  void primeRemoteSkillsCache();
-  registerSkillsChangeListener(() => {
-    const latest = loadConfig();
-    void refreshRemoteBinsForConnectedNodes(latest);
+  // Debounce skills-triggered node probes to avoid feedback loops and rapid-fire invokes.
+  // Skills changes can happen in bursts (e.g., file watcher events), and each probe
+  // takes time to complete. A 30-second delay ensures we batch changes together.
+  let skillsRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+  const skillsRefreshDelayMs = 30_000;
+  const skillsChangeUnsub = registerSkillsChangeListener((event) => {
+    if (event.reason === "remote-node") return;
+    if (skillsRefreshTimer) clearTimeout(skillsRefreshTimer);
+    skillsRefreshTimer = setTimeout(() => {
+      skillsRefreshTimer = null;
+      const latest = loadConfig();
+      void refreshRemoteBinsForConnectedNodes(latest);
+    }, skillsRefreshDelayMs);
  });

  const { tickInterval, healthInterval, dedupeCleanup } = startGatewayMaintenanceTimers({
@@ -386,7 +397,10 @@ export async function startGatewayServer(
  void cron.start().catch((err) => logCron.error(`failed to start: ${String(err)}`));

  const execApprovalManager = new ExecApprovalManager();
-  const execApprovalHandlers = createExecApprovalHandlers(execApprovalManager);
+  const execApprovalForwarder = createExecApprovalForwarder();
+  const execApprovalHandlers = createExecApprovalHandlers(execApprovalManager, {
+    forwarder: execApprovalForwarder,
+  });

  const canvasHostServerPort = (canvasHostServer as CanvasHostServer | null)?.port;

@@ -544,6 +558,11 @@ export async function startGatewayServer(
      if (diagnosticsEnabled) {
        stopDiagnosticHeartbeat();
      }
+      if (skillsRefreshTimer) {
+        clearTimeout(skillsRefreshTimer);
+        skillsRefreshTimer = null;
+      }
+      skillsChangeUnsub();
      await close(opts);
    },
  };
@@ -0,0 +1,125 @@
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import { WebSocket } from "ws";
+
+import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
+import { loadOrCreateDeviceIdentity } from "../infra/device-identity.js";
+
+vi.mock("../infra/update-runner.js", () => ({
+  runGatewayUpdate: vi.fn(async () => ({
+    status: "ok",
+    mode: "git",
+    root: "/repo",
+    steps: [],
+    durationMs: 12,
+  })),
+}));
+
+import {
+  connectOk,
+  installGatewayTestHooks,
+  rpcReq,
+  startServerWithClient,
+} from "./test-helpers.js";
+
+installGatewayTestHooks({ scope: "suite" });
+
+let server: Awaited<ReturnType<typeof startServerWithClient>>["server"];
+let ws: WebSocket;
+let port: number;
+
+beforeAll(async () => {
+  const started = await startServerWithClient();
+  server = started.server;
+  ws = started.ws;
+  port = started.port;
+  await connectOk(ws);
+});
+
+afterAll(async () => {
+  ws.close();
+  await server.close();
+});
+
+describe("late-arriving invoke results", () => {
+  test("returns success for unknown invoke id (late arrival after timeout)", async () => {
+    // Create a node client WebSocket
+    const nodeWs = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve) => nodeWs.once("open", resolve));
+
+    try {
+      // Connect as a node with device identity
+      const identity = loadOrCreateDeviceIdentity();
+      const nodeId = identity.deviceId;
+
+      await connectOk(nodeWs, {
+        role: "node",
+        client: {
+          id: GATEWAY_CLIENT_NAMES.NODE_HOST,
+          version: "1.0.0",
+          platform: "ios",
+          mode: GATEWAY_CLIENT_MODES.NODE,
+        },
+        commands: ["canvas.snapshot"],
+      });
+
+      // Send an invoke result with an unknown ID (simulating late arrival after timeout)
+      const result = await rpcReq<{ ok?: boolean; ignored?: boolean }>(
+        nodeWs,
+        "node.invoke.result",
+        {
+          id: "unknown-invoke-id-12345",
+          nodeId,
+          ok: true,
+          payloadJSON: JSON.stringify({ result: "late" }),
+        },
+      );
+
+      // Late-arriving results return success instead of error to reduce log noise
+      expect(result.ok).toBe(true);
+      expect(result.payload?.ok).toBe(true);
+      expect(result.payload?.ignored).toBe(true);
+    } finally {
+      nodeWs.close();
+    }
+  });
+
+  test("returns success for unknown invoke id with error payload", async () => {
+    // Verifies late results are accepted regardless of their ok/error status
+    const nodeWs = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve) => nodeWs.once("open", resolve));
+
+    try {
+      await connectOk(nodeWs, {
+        role: "node",
+        client: {
+          id: GATEWAY_CLIENT_NAMES.NODE_HOST,
+          version: "1.0.0",
+          platform: "darwin",
+          mode: GATEWAY_CLIENT_MODES.NODE,
+        },
+        commands: [],
+      });
+
+      const identity = loadOrCreateDeviceIdentity();
+      const nodeId = identity.deviceId;
+
+      // Late invoke result with error payload - should still return success
+      const result = await rpcReq<{ ok?: boolean; ignored?: boolean }>(
+        nodeWs,
+        "node.invoke.result",
+        {
+          id: "another-unknown-invoke-id",
+          nodeId,
+          ok: false,
+          error: { code: "FAILED", message: "test error" },
+        },
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.payload?.ok).toBe(true);
+      expect(result.payload?.ignored).toBe(true);
+    } finally {
+      nodeWs.close();
+    }
+  });
+});
@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import type { ClawdbotConfig } from "../config/config.js";
+import { createExecApprovalForwarder } from "./exec-approval-forwarder.js";
+
+const baseRequest = {
+  id: "req-1",
+  request: {
+    command: "echo hello",
+    agentId: "main",
+    sessionKey: "agent:main:main",
+  },
+  createdAtMs: 1000,
+  expiresAtMs: 6000,
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("exec approval forwarder", () => {
+  it("forwards to session target and resolves", async () => {
+    vi.useFakeTimers();
+    const deliver = vi.fn().mockResolvedValue([]);
+    const cfg = {
+      approvals: { exec: { enabled: true, mode: "session" } },
+    } as ClawdbotConfig;
+
+    const forwarder = createExecApprovalForwarder({
+      getConfig: () => cfg,
+      deliver,
+      nowMs: () => 1000,
+      resolveSessionTarget: () => ({ channel: "slack", to: "U1" }),
+    });
+
+    await forwarder.handleRequested(baseRequest);
+    expect(deliver).toHaveBeenCalledTimes(1);
+
+    await forwarder.handleResolved({
+      id: baseRequest.id,
+      decision: "allow-once",
+      resolvedBy: "slack:U1",
+      ts: 2000,
+    });
+    expect(deliver).toHaveBeenCalledTimes(2);
+
+    await vi.runAllTimersAsync();
+    expect(deliver).toHaveBeenCalledTimes(2);
+  });
+
+  it("forwards to explicit targets and expires", async () => {
+    vi.useFakeTimers();
+    const deliver = vi.fn().mockResolvedValue([]);
+    const cfg = {
+      approvals: {
+        exec: {
+          enabled: true,
+          mode: "targets",
+          targets: [{ channel: "telegram", to: "123" }],
+        },
+      },
+    } as ClawdbotConfig;
+
+    const forwarder = createExecApprovalForwarder({
+      getConfig: () => cfg,
+      deliver,
+      nowMs: () => 1000,
+      resolveSessionTarget: () => null,
+    });
+
+    await forwarder.handleRequested(baseRequest);
+    expect(deliver).toHaveBeenCalledTimes(1);
+
+    await vi.runAllTimersAsync();
+    expect(deliver).toHaveBeenCalledTimes(2);
+  });
+});
@@ -0,0 +1,282 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import { loadConfig } from "../config/config.js";
+import { loadSessionStore, resolveStorePath } from "../config/sessions.js";
+import type {
+  ExecApprovalForwardingConfig,
+  ExecApprovalForwardTarget,
+} from "../config/types.approvals.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { parseAgentSessionKey } from "../routing/session-key.js";
+import { isDeliverableMessageChannel, normalizeMessageChannel } from "../utils/message-channel.js";
+import type { ExecApprovalDecision } from "./exec-approvals.js";
+import { deliverOutboundPayloads } from "./outbound/deliver.js";
+import { resolveSessionDeliveryTarget } from "./outbound/targets.js";
+
+const log = createSubsystemLogger("gateway/exec-approvals");
+
+export type ExecApprovalRequest = {
+  id: string;
+  request: {
+    command: string;
+    cwd?: string | null;
+    host?: string | null;
+    security?: string | null;
+    ask?: string | null;
+    agentId?: string | null;
+    resolvedPath?: string | null;
+    sessionKey?: string | null;
+  };
+  createdAtMs: number;
+  expiresAtMs: number;
+};
+
+export type ExecApprovalResolved = {
+  id: string;
+  decision: ExecApprovalDecision;
+  resolvedBy?: string | null;
+  ts: number;
+};
+
+type ForwardTarget = ExecApprovalForwardTarget & { source: "session" | "target" };
+
+type PendingApproval = {
+  request: ExecApprovalRequest;
+  targets: ForwardTarget[];
+  timeoutId: NodeJS.Timeout | null;
+};
+
+export type ExecApprovalForwarder = {
+  handleRequested: (request: ExecApprovalRequest) => Promise<void>;
+  handleResolved: (resolved: ExecApprovalResolved) => Promise<void>;
+  stop: () => void;
+};
+
+export type ExecApprovalForwarderDeps = {
+  getConfig?: () => ClawdbotConfig;
+  deliver?: typeof deliverOutboundPayloads;
+  nowMs?: () => number;
+  resolveSessionTarget?: (params: {
+    cfg: ClawdbotConfig;
+    request: ExecApprovalRequest;
+  }) => ExecApprovalForwardTarget | null;
+};
+
+const DEFAULT_MODE = "session" as const;
+
+function normalizeMode(mode?: ExecApprovalForwardingConfig["mode"]) {
+  return mode ?? DEFAULT_MODE;
+}
+
+function matchSessionFilter(sessionKey: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => {
+    try {
+      return sessionKey.includes(pattern) || new RegExp(pattern).test(sessionKey);
+    } catch {
+      return sessionKey.includes(pattern);
+    }
+  });
+}
+
+function shouldForward(params: {
+  config?: ExecApprovalForwardingConfig;
+  request: ExecApprovalRequest;
+}): boolean {
+  const config = params.config;
+  if (!config?.enabled) return false;
+  if (config.agentFilter?.length) {
+    const agentId =
+      params.request.request.agentId ??
+      parseAgentSessionKey(params.request.request.sessionKey)?.agentId;
+    if (!agentId) return false;
+    if (!config.agentFilter.includes(agentId)) return false;
+  }
+  if (config.sessionFilter?.length) {
+    const sessionKey = params.request.request.sessionKey;
+    if (!sessionKey) return false;
+    if (!matchSessionFilter(sessionKey, config.sessionFilter)) return false;
+  }
+  return true;
+}
+
+function buildTargetKey(target: ExecApprovalForwardTarget): string {
+  const channel = normalizeMessageChannel(target.channel) ?? target.channel;
+  const accountId = target.accountId ?? "";
+  const threadId = target.threadId ?? "";
+  return [channel, target.to, accountId, threadId].join(":");
+}
+
+function buildRequestMessage(request: ExecApprovalRequest, nowMs: number) {
+  const lines: string[] = ["🔒 Exec approval required", `ID: ${request.id}`];
+  lines.push(`Command: ${request.request.command}`);
+  if (request.request.cwd) lines.push(`CWD: ${request.request.cwd}`);
+  if (request.request.host) lines.push(`Host: ${request.request.host}`);
+  if (request.request.agentId) lines.push(`Agent: ${request.request.agentId}`);
+  if (request.request.security) lines.push(`Security: ${request.request.security}`);
+  if (request.request.ask) lines.push(`Ask: ${request.request.ask}`);
+  const expiresIn = Math.max(0, Math.round((request.expiresAtMs - nowMs) / 1000));
+  lines.push(`Expires in: ${expiresIn}s`);
+  lines.push("Reply with: /approve <id> allow-once|allow-always|deny");
+  return lines.join("\n");
+}
+
+function decisionLabel(decision: ExecApprovalDecision): string {
+  if (decision === "allow-once") return "allowed once";
+  if (decision === "allow-always") return "allowed always";
+  return "denied";
+}
+
+function buildResolvedMessage(resolved: ExecApprovalResolved) {
+  const base = `✅ Exec approval ${decisionLabel(resolved.decision)}.`;
+  const by = resolved.resolvedBy ? ` Resolved by ${resolved.resolvedBy}.` : "";
+  return `${base}${by} ID: ${resolved.id}`;
+}
+
+function buildExpiredMessage(request: ExecApprovalRequest) {
+  return `⏱️ Exec approval expired. ID: ${request.id}`;
+}
+
+function defaultResolveSessionTarget(params: {
+  cfg: ClawdbotConfig;
+  request: ExecApprovalRequest;
+}): ExecApprovalForwardTarget | null {
+  const sessionKey = params.request.request.sessionKey?.trim();
+  if (!sessionKey) return null;
+  const parsed = parseAgentSessionKey(sessionKey);
+  const agentId = parsed?.agentId ?? params.request.request.agentId ?? "main";
+  const storePath = resolveStorePath(params.cfg.session?.store, { agentId });
+  const store = loadSessionStore(storePath);
+  const entry = store[sessionKey];
+  if (!entry) return null;
+  const target = resolveSessionDeliveryTarget({ entry, requestedChannel: "last" });
+  if (!target.channel || !target.to) return null;
+  if (!isDeliverableMessageChannel(target.channel)) return null;
+  return {
+    channel: target.channel,
+    to: target.to,
+    accountId: target.accountId,
+    threadId: target.threadId,
+  };
+}
+
+async function deliverToTargets(params: {
+  cfg: ClawdbotConfig;
+  targets: ForwardTarget[];
+  text: string;
+  deliver: typeof deliverOutboundPayloads;
+  shouldSend?: () => boolean;
+}) {
+  const deliveries = params.targets.map(async (target) => {
+    if (params.shouldSend && !params.shouldSend()) return;
+    const channel = normalizeMessageChannel(target.channel) ?? target.channel;
+    if (!isDeliverableMessageChannel(channel)) return;
+    try {
+      await params.deliver({
+        cfg: params.cfg,
+        channel,
+        to: target.to,
+        accountId: target.accountId,
+        threadId: target.threadId,
+        payloads: [{ text: params.text }],
+      });
+    } catch (err) {
+      log.error(`exec approvals: failed to deliver to ${channel}:${target.to}: ${String(err)}`);
+    }
+  });
+  await Promise.allSettled(deliveries);
+}
+
+export function createExecApprovalForwarder(
+  deps: ExecApprovalForwarderDeps = {},
+): ExecApprovalForwarder {
+  const getConfig = deps.getConfig ?? loadConfig;
+  const deliver = deps.deliver ?? deliverOutboundPayloads;
+  const nowMs = deps.nowMs ?? Date.now;
+  const resolveSessionTarget = deps.resolveSessionTarget ?? defaultResolveSessionTarget;
+  const pending = new Map<string, PendingApproval>();
+
+  const handleRequested = async (request: ExecApprovalRequest) => {
+    const cfg = getConfig();
+    const config = cfg.approvals?.exec;
+    if (!shouldForward({ config, request })) return;
+
+    const mode = normalizeMode(config?.mode);
+    const targets: ForwardTarget[] = [];
+    const seen = new Set<string>();
+
+    if (mode === "session" || mode === "both") {
+      const sessionTarget = resolveSessionTarget({ cfg, request });
+      if (sessionTarget) {
+        const key = buildTargetKey(sessionTarget);
+        if (!seen.has(key)) {
+          seen.add(key);
+          targets.push({ ...sessionTarget, source: "session" });
+        }
+      }
+    }
+
+    if (mode === "targets" || mode === "both") {
+      const explicitTargets = config?.targets ?? [];
+      for (const target of explicitTargets) {
+        const key = buildTargetKey(target);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        targets.push({ ...target, source: "target" });
+      }
+    }
+
+    if (targets.length === 0) return;
+
+    const expiresInMs = Math.max(0, request.expiresAtMs - nowMs());
+    const timeoutId = setTimeout(() => {
+      void (async () => {
+        const entry = pending.get(request.id);
+        if (!entry) return;
+        pending.delete(request.id);
+        const expiredText = buildExpiredMessage(request);
+        await deliverToTargets({ cfg, targets: entry.targets, text: expiredText, deliver });
+      })();
+    }, expiresInMs);
+    timeoutId.unref?.();
+
+    const pendingEntry: PendingApproval = { request, targets, timeoutId };
+    pending.set(request.id, pendingEntry);
+
+    if (pending.get(request.id) !== pendingEntry) return;
+
+    const text = buildRequestMessage(request, nowMs());
+    await deliverToTargets({
+      cfg,
+      targets,
+      text,
+      deliver,
+      shouldSend: () => pending.get(request.id) === pendingEntry,
+    });
+  };
+
+  const handleResolved = async (resolved: ExecApprovalResolved) => {
+    const entry = pending.get(resolved.id);
+    if (!entry) return;
+    if (entry.timeoutId) clearTimeout(entry.timeoutId);
+    pending.delete(resolved.id);
+
+    const cfg = getConfig();
+    const text = buildResolvedMessage(resolved);
+    await deliverToTargets({ cfg, targets: entry.targets, text, deliver });
+  };
+
+  const stop = () => {
+    for (const entry of pending.values()) {
+      if (entry.timeoutId) clearTimeout(entry.timeoutId);
+    }
+    pending.clear();
+  };
+
+  return { handleRequested, handleResolved, stop };
+}
+
+export function shouldForwardExecApproval(params: {
+  config?: ExecApprovalForwardingConfig;
+  request: ExecApprovalRequest;
+}): boolean {
+  return shouldForward(params);
+}
@@ -35,6 +35,7 @@ import {
 } from "../config/sessions.js";
 import type { AgentDefaultsConfig } from "../config/types.agent-defaults.js";
 import { formatErrorMessage } from "../infra/errors.js";
+import { peekSystemEvents } from "../infra/system-events.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { getQueueSize } from "../process/command-queue.js";
 import { CommandLane } from "../process/lanes.js";
@@ -88,6 +89,14 @@ export type HeartbeatSummary = {
 const DEFAULT_HEARTBEAT_TARGET = "last";
 const ACTIVE_HOURS_TIME_PATTERN = /^([01]\d|2[0-3]|24):([0-5]\d)$/;

+// Prompt used when an async exec has completed and the result should be relayed to the user.
+// This overrides the standard heartbeat prompt to ensure the model responds with the exec result
+// instead of just "HEARTBEAT_OK".
+const EXEC_EVENT_PROMPT =
+  "An async command you ran earlier has completed. The result is shown in the system messages above. " +
+  "Please relay the command output to the user in a helpful way. If the command succeeded, share the relevant output. " +
+  "If it failed, explain what went wrong.";
+
 function resolveActiveHoursTimezone(cfg: ClawdbotConfig, raw?: string): string {
  const trimmed = raw?.trim();
  if (!trimmed || trimmed === "user") {
@@ -453,11 +462,13 @@ export async function runHeartbeatOnce(opts: {

  // Skip heartbeat if HEARTBEAT.md exists but has no actionable content.
  // This saves API calls/costs when the file is effectively empty (only comments/headers).
+  // EXCEPTION: Don't skip for exec events - they have pending system events to process.
+  const isExecEventReason = opts.reason === "exec-event";
  const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
  const heartbeatFilePath = path.join(workspaceDir, DEFAULT_HEARTBEAT_FILENAME);
  try {
    const heartbeatFileContent = await fs.readFile(heartbeatFilePath, "utf-8");
-    if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent)) {
+    if (isHeartbeatContentEffectivelyEmpty(heartbeatFileContent) && !isExecEventReason) {
      emitHeartbeatEvent({
        status: "skipped",
        reason: "empty-heartbeat-file",
@@ -483,12 +494,20 @@ export async function runHeartbeatOnce(opts: {
      : { showOk: false, showAlerts: true, useIndicator: true };
  const { sender } = resolveHeartbeatSenderContext({ cfg, entry, delivery });
  const responsePrefix = resolveEffectiveMessagesConfig(cfg, agentId).responsePrefix;
-  const prompt = resolveHeartbeatPrompt(cfg, heartbeat);
+
+  // Check if this is an exec event with pending exec completion system events.
+  // If so, use a specialized prompt that instructs the model to relay the result
+  // instead of the standard heartbeat prompt with "reply HEARTBEAT_OK".
+  const isExecEvent = opts.reason === "exec-event";
+  const pendingEvents = isExecEvent ? peekSystemEvents(sessionKey) : [];
+  const hasExecCompletion = pendingEvents.some((evt) => evt.includes("Exec finished"));
+
+  const prompt = hasExecCompletion ? EXEC_EVENT_PROMPT : resolveHeartbeatPrompt(cfg, heartbeat);
  const ctx = {
    Body: prompt,
    From: sender,
    To: sender,
-    Provider: "heartbeat",
+    Provider: hasExecCompletion ? "exec-event" : "heartbeat",
    SessionKey: sessionKey,
  };
  if (!visibility.showAlerts && !visibility.showOk && !visibility.useIndicator) {
@@ -558,7 +577,19 @@ export async function runHeartbeatOnce(opts: {

    const ackMaxChars = resolveHeartbeatAckMaxChars(cfg, heartbeat);
    const normalized = normalizeHeartbeatReply(replyPayload, responsePrefix, ackMaxChars);
-    const shouldSkipMain = normalized.shouldSkip && !normalized.hasMedia;
+    // For exec completion events, don't skip even if the response looks like HEARTBEAT_OK.
+    // The model should be responding with exec results, not ack tokens.
+    // Also, if normalized.text is empty due to token stripping but we have exec completion,
+    // fall back to the original reply text.
+    const execFallbackText =
+      hasExecCompletion && !normalized.text.trim() && replyPayload.text?.trim()
+        ? replyPayload.text.trim()
+        : null;
+    if (execFallbackText) {
+      normalized.text = execFallbackText;
+      normalized.shouldSkip = false;
+    }
+    const shouldSkipMain = normalized.shouldSkip && !normalized.hasMedia && !hasExecCompletion;
    if (shouldSkipMain && reasoningPayloads.length === 0) {
      await restoreHeartbeatUpdatedAt({
        storePath,
@@ -55,10 +55,10 @@ function extractErrorMessage(err: unknown): string | undefined {
 function logRemoteBinProbeFailure(nodeId: string, err: unknown) {
  const message = extractErrorMessage(err);
  const label = describeNode(nodeId);
-  if (message?.includes("node not connected")) {
-    log.info(
-      `remote bin probe skipped: node not connected (${label}); check nodes list/status for ${label}`,
-    );
+  // Node unavailable errors (not connected or disconnected mid-operation) are expected
+  // when nodes have transient connections - log at info level instead of warn
+  if (message?.includes("node not connected") || message?.includes("node disconnected")) {
+    log.info(`remote bin probe skipped: node unavailable (${label})`);
    return;
  }
  if (message?.includes("invoke timed out") || message?.includes("timeout")) {
@@ -213,6 +213,15 @@ function parseBinProbePayload(payloadJSON: string | null | undefined, payload?:
  return [];
 }

+function areBinSetsEqual(a: Set<string> | undefined, b: Set<string>): boolean {
+  if (!a) return false;
+  if (a.size !== b.size) return false;
+  for (const bin of b) {
+    if (!a.has(bin)) return false;
+  }
+  return true;
+}
+
 export async function refreshRemoteNodeBins(params: {
  nodeId: string;
  platform?: string;
@@ -261,7 +270,11 @@ export async function refreshRemoteNodeBins(params: {
      return;
    }
    const bins = parseBinProbePayload(res.payloadJSON, res.payload);
+    const existingBins = remoteNodes.get(params.nodeId)?.bins;
+    const nextBins = new Set(bins);
+    const hasChanged = !areBinSetsEqual(existingBins, nextBins);
    recordRemoteNodeBins(params.nodeId, bins);
+    if (!hasChanged) return;
    await updatePairedNodeMetadata(params.nodeId, { bins });
    bumpSkillsSnapshotVersion({ reason: "remote-node" });
  } catch (err) {
@@ -67,9 +67,10 @@ export function normalizeAgentId(value: string | undefined | null): string {
 export function sanitizeAgentId(value: string | undefined | null): string {
  const trimmed = (value ?? "").trim();
  if (!trimmed) return DEFAULT_AGENT_ID;
-  if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) return trimmed;
+  if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) return trimmed.toLowerCase();
  return (
    trimmed
+      .toLowerCase()
      .replace(/[^a-z0-9_-]+/gi, "-")
      .replace(/^-+/, "")
      .replace(/-+$/, "")
@@ -0,0 +1,61 @@
+export type ReasoningTagMode = "strict" | "preserve";
+export type ReasoningTagTrim = "none" | "start" | "both";
+
+const QUICK_TAG_RE = /<\s*\/?\s*(?:think(?:ing)?|thought|antthinking|final)\b/i;
+const FINAL_TAG_RE = /<\s*\/?\s*final\b[^>]*>/gi;
+const THINKING_TAG_RE = /<\s*(\/?)\s*(?:think(?:ing)?|thought|antthinking)\b[^>]*>/gi;
+
+function applyTrim(value: string, mode: ReasoningTagTrim): string {
+  if (mode === "none") return value;
+  if (mode === "start") return value.trimStart();
+  return value.trim();
+}
+
+export function stripReasoningTagsFromText(
+  text: string,
+  options?: {
+    mode?: ReasoningTagMode;
+    trim?: ReasoningTagTrim;
+  },
+): string {
+  if (!text) return text;
+  if (!QUICK_TAG_RE.test(text)) return text;
+
+  const mode = options?.mode ?? "strict";
+  const trimMode = options?.trim ?? "both";
+
+  let cleaned = text;
+  if (FINAL_TAG_RE.test(cleaned)) {
+    FINAL_TAG_RE.lastIndex = 0;
+    cleaned = cleaned.replace(FINAL_TAG_RE, "");
+  } else {
+    FINAL_TAG_RE.lastIndex = 0;
+  }
+
+  THINKING_TAG_RE.lastIndex = 0;
+  let result = "";
+  let lastIndex = 0;
+  let inThinking = false;
+
+  for (const match of cleaned.matchAll(THINKING_TAG_RE)) {
+    const idx = match.index ?? 0;
+    const isClose = match[1] === "/";
+
+    if (!inThinking) {
+      result += cleaned.slice(lastIndex, idx);
+      if (!isClose) {
+        inThinking = true;
+      }
+    } else if (isClose) {
+      inThinking = false;
+    }
+
+    lastIndex = idx + match[0].length;
+  }
+
+  if (!inThinking || mode === "preserve") {
+    result += cleaned.slice(lastIndex);
+  }
+
+  return applyTrim(result, trimMode);
+}
@@ -177,13 +177,11 @@ describe("createTelegramBot", () => {
    expect(throttlerSpy).toHaveBeenCalledTimes(1);
    expect(useSpy).toHaveBeenCalledWith("throttler");
  });
-  it("forces native fetch only under Bun", () => {
+  it("uses wrapped fetch when global fetch is available", () => {
    const originalFetch = globalThis.fetch;
-    const originalBun = (globalThis as { Bun?: unknown }).Bun;
    const fetchSpy = vi.fn() as unknown as typeof fetch;
    globalThis.fetch = fetchSpy;
    try {
-      (globalThis as { Bun?: unknown }).Bun = {};
      createTelegramBot({ token: "tok" });
      const fetchImpl = resolveTelegramFetch();
      expect(fetchImpl).toBeTypeOf("function");
@@ -194,33 +192,6 @@ describe("createTelegramBot", () => {
      expect(clientFetch).not.toBe(fetchSpy);
    } finally {
      globalThis.fetch = originalFetch;
-      if (originalBun === undefined) {
-        delete (globalThis as { Bun?: unknown }).Bun;
-      } else {
-        (globalThis as { Bun?: unknown }).Bun = originalBun;
-      }
-    }
-  });
-  it("does not force native fetch on Node", () => {
-    const originalFetch = globalThis.fetch;
-    const originalBun = (globalThis as { Bun?: unknown }).Bun;
-    const fetchSpy = vi.fn() as unknown as typeof fetch;
-    globalThis.fetch = fetchSpy;
-    try {
-      if (originalBun !== undefined) {
-        delete (globalThis as { Bun?: unknown }).Bun;
-      }
-      createTelegramBot({ token: "tok" });
-      const fetchImpl = resolveTelegramFetch();
-      expect(fetchImpl).toBeUndefined();
-      expect(botCtorSpy).toHaveBeenCalledWith("tok", undefined);
-    } finally {
-      globalThis.fetch = originalFetch;
-      if (originalBun === undefined) {
-        delete (globalThis as { Bun?: unknown }).Bun;
-      } else {
-        (globalThis as { Bun?: unknown }).Bun = originalBun;
-      }
    }
  });
  it("passes timeoutSeconds even without a custom fetch", () => {
@@ -309,13 +309,11 @@ describe("createTelegramBot", () => {
    expect(registered.some((command) => reserved.includes(command.command))).toBe(false);
  });

-  it("forces native fetch only under Bun", () => {
+  it("uses wrapped fetch when global fetch is available", () => {
    const originalFetch = globalThis.fetch;
-    const originalBun = (globalThis as { Bun?: unknown }).Bun;
    const fetchSpy = vi.fn() as unknown as typeof fetch;
    globalThis.fetch = fetchSpy;
    try {
-      (globalThis as { Bun?: unknown }).Bun = {};
      createTelegramBot({ token: "tok" });
      const fetchImpl = resolveTelegramFetch();
      expect(fetchImpl).toBeTypeOf("function");
@@ -326,34 +324,6 @@ describe("createTelegramBot", () => {
      expect(clientFetch).not.toBe(fetchSpy);
    } finally {
      globalThis.fetch = originalFetch;
-      if (originalBun === undefined) {
-        delete (globalThis as { Bun?: unknown }).Bun;
-      } else {
-        (globalThis as { Bun?: unknown }).Bun = originalBun;
-      }
-    }
-  });
-
-  it("does not force native fetch on Node", () => {
-    const originalFetch = globalThis.fetch;
-    const originalBun = (globalThis as { Bun?: unknown }).Bun;
-    const fetchSpy = vi.fn() as unknown as typeof fetch;
-    globalThis.fetch = fetchSpy;
-    try {
-      if (originalBun !== undefined) {
-        delete (globalThis as { Bun?: unknown }).Bun;
-      }
-      createTelegramBot({ token: "tok" });
-      const fetchImpl = resolveTelegramFetch();
-      expect(fetchImpl).toBeUndefined();
-      expect(botCtorSpy).toHaveBeenCalledWith("tok", undefined);
-    } finally {
-      globalThis.fetch = originalFetch;
-      if (originalBun === undefined) {
-        delete (globalThis as { Bun?: unknown }).Bun;
-      } else {
-        (globalThis as { Bun?: unknown }).Bun = originalBun;
-      }
    }
  });

@@ -117,8 +117,7 @@ export function createTelegramBot(opts: TelegramBotOptions) {
  const telegramCfg = account.config;

  const fetchImpl = resolveTelegramFetch(opts.proxyFetch);
-  const isBun = "Bun" in globalThis || Boolean(process?.versions?.bun);
-  const shouldProvideFetch = Boolean(opts.proxyFetch) || isBun;
+  const shouldProvideFetch = Boolean(fetchImpl);
  const timeoutSeconds =
    typeof telegramCfg?.timeoutSeconds === "number" && Number.isFinite(telegramCfg.timeoutSeconds)
      ? Math.max(1, Math.floor(telegramCfg.timeoutSeconds))
@@ -1,37 +1,28 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";

 import { resolveTelegramFetch } from "./fetch.js";

 describe("resolveTelegramFetch", () => {
-  it("wraps proxy fetch to normalize foreign abort signals", async () => {
-    let seenSignal: AbortSignal | undefined;
-    const proxyFetch = vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => {
-      seenSignal = init?.signal as AbortSignal | undefined;
-      return {} as Response;
-    });
+  const originalFetch = globalThis.fetch;

-    const fetcher = resolveTelegramFetch(proxyFetch);
-    expect(fetcher).toBeTypeOf("function");
+  afterEach(() => {
+    if (originalFetch) {
+      globalThis.fetch = originalFetch;
+    } else {
+      delete (globalThis as { fetch?: typeof fetch }).fetch;
+    }
+  });

-    let abortHandler: (() => void) | null = null;
-    const fakeSignal = {
-      aborted: false,
-      addEventListener: (event: string, handler: () => void) => {
-        if (event === "abort") abortHandler = handler;
-      },
-      removeEventListener: (event: string, handler: () => void) => {
-        if (event === "abort" && abortHandler === handler) abortHandler = null;
-      },
-    } as AbortSignal;
+  it("returns wrapped global fetch when available", () => {
+    const fetchMock = vi.fn(async () => ({}));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+    const resolved = resolveTelegramFetch();
+    expect(resolved).toBeTypeOf("function");
+  });

-    const promise = fetcher!("https://example.com", { signal: fakeSignal });
-    expect(proxyFetch).toHaveBeenCalledOnce();
-    expect(seenSignal).toBeInstanceOf(AbortSignal);
-    expect(seenSignal).not.toBe(fakeSignal);
-
-    abortHandler?.();
-    expect(seenSignal?.aborted).toBe(true);
-
-    await promise;
+  it("prefers proxy fetch when provided", () => {
+    const fetchMock = vi.fn(async () => ({}));
+    const resolved = resolveTelegramFetch(fetchMock as unknown as typeof fetch);
+    expect(resolved).toBeTypeOf("function");
  });
 });
@@ -1,10 +1,8 @@
 import { resolveFetch } from "../infra/fetch.js";

-// Bun-only: force native fetch to avoid grammY's Node shim under Bun.
+// Prefer wrapped fetch when available to normalize AbortSignal across runtimes.
 export function resolveTelegramFetch(proxyFetch?: typeof fetch): typeof fetch | undefined {
  if (proxyFetch) return resolveFetch(proxyFetch);
-  const isBun = "Bun" in globalThis || Boolean(process?.versions?.bun);
-  if (!isBun) return undefined;
  const fetchImpl = resolveFetch();
  if (!fetchImpl) {
    throw new Error("fetch is not available; set channels.telegram.proxy in config");
@@ -1,5 +1,8 @@
 import { afterAll, afterEach, beforeEach, vi } from "vitest";

+// Ensure Vitest environment is properly set
+process.env.VITEST = "true";
+
 import type {
  ChannelId,
  ChannelOutboundAdapter,
@@ -21,5 +21,22 @@ describe("stripThinkingTags", () => {
  it("returns original text when no tags exist", () => {
    expect(stripThinkingTags("Hello")).toBe("Hello");
  });
+
+  it("strips <final>…</final> segments", () => {
+    const input = "<final>\n\nHello there\n\n</final>";
+    expect(stripThinkingTags(input)).toBe("Hello there\n\n");
+  });
+
+  it("strips mixed <think> and <final> tags", () => {
+    const input = "<think>reasoning</think>\n\n<final>Hello</final>";
+    expect(stripThinkingTags(input)).toBe("Hello");
+  });
+
+  it("handles incomplete <final tag gracefully", () => {
+    // When streaming splits mid-tag, we may see "<final" without closing ">"
+    // This should not crash and should handle gracefully
+    expect(stripThinkingTags("<final\nHello")).toBe("<final\nHello");
+    expect(stripThinkingTags("Hello</final>")).toBe("Hello");
+  });
 });

@@ -1,3 +1,5 @@
+import { stripReasoningTagsFromText } from "../../../src/shared/text/reasoning-tags.js";
+
 export function formatMs(ms?: number | null): string {
  if (!ms && ms !== 0) return "n/a";
  return new Date(ms).toLocaleString();
@@ -67,38 +69,6 @@ export function parseList(input: string): string[] {
    .filter((v) => v.length > 0);
 }

-const THINKING_TAG_RE = /<\s*\/?\s*think(?:ing)?\s*>/gi;
-const THINKING_OPEN_RE = /<\s*think(?:ing)?\s*>/i;
-const THINKING_CLOSE_RE = /<\s*\/\s*think(?:ing)?\s*>/i;
-
 export function stripThinkingTags(value: string): string {
-  if (!value) return value;
-  const hasOpen = THINKING_OPEN_RE.test(value);
-  const hasClose = THINKING_CLOSE_RE.test(value);
-  if (!hasOpen && !hasClose) return value;
-  // If we don't have a balanced pair, avoid dropping trailing content.
-  if (hasOpen !== hasClose) {
-    if (!hasOpen) return value.replace(THINKING_CLOSE_RE, "").trimStart();
-    return value.replace(THINKING_OPEN_RE, "").trimStart();
-  }
-
-  if (!THINKING_TAG_RE.test(value)) return value;
-  THINKING_TAG_RE.lastIndex = 0;
-
-  let result = "";
-  let lastIndex = 0;
-  let inThinking = false;
-  for (const match of value.matchAll(THINKING_TAG_RE)) {
-    const idx = match.index ?? 0;
-    if (!inThinking) {
-      result += value.slice(lastIndex, idx);
-    }
-    const tag = match[0].toLowerCase();
-    inThinking = !tag.includes("/");
-    lastIndex = idx + match[0].length;
-  }
-  if (!inThinking) {
-    result += value.slice(lastIndex);
-  }
-  return result.trimStart();
+  return stripReasoningTagsFromText(value, { mode: "preserve", trim: "start" });
 }
Author	SHA1	Message	Date
Peter Steinberger	af05c6b4e9	test: restore Ollama provider tests (#1606 ) (thanks @abhaymundhara)	2026-01-24 22:38:21 +00:00
Abhay	6691e32faf	fix: Make Ollama provider opt-in to avoid breaking existing tests Root Cause: The Ollama provider was being added to ALL configurations by default (with a fallback API key of 'ollama-local'), which broke tests that expected NO providers when no API keys were configured. Solution: - Removed the default fallback API key for Ollama - Ollama provider now requires explicit configuration via: - OLLAMA_API_KEY environment variable, OR - Ollama profile in auth store - Updated documentation to reflect the explicit configuration requirement - Added a test to verify Ollama is not added by default This fixes all 4 failing test suites: - checks (node, test, pnpm test) - checks (bun, test, bunx vitest run) - checks-windows (node, test, pnpm test) - checks-macos (test, pnpm test) Closes #1531	2026-01-24 22:37:44 +00:00
Abhay	cda6c02e8f	test: Temporarily skip Ollama provider tests to diagnose CI failures	2026-01-24 22:37:19 +00:00
Peter Steinberger	8c9d022a88	feat: add Ollama provider discovery parity (#1606 ) (thanks @abhaymundhara)	2026-01-24 22:35:17 +00:00
Peter Steinberger	dd150d69c6	fix: use active auth profile for auto-compaction	2026-01-24 22:23:49 +00:00
Rodrigo Uroz Claude Peter Steinberger	9ceac415c5	fix: auto-compact on context overflow promptError before returning error (#1627 ) * fix: detect Anthropic 'Request size exceeds model context window' as context overflow Anthropic now returns 'Request size exceeds model context window' instead of the previously detected 'prompt is too long' format. This new error message was not recognized by isContextOverflowError(), causing auto-compaction to NOT trigger. Users would see the raw error twice without any recovery attempt. Changes: - Add 'exceeds model context window' and 'request size exceeds' to isContextOverflowError() detection patterns - Add tests that fail without the fix, verifying both the raw error string and the JSON-wrapped format from Anthropic's API - Add test for formatAssistantErrorText to ensure the friendly 'Context overflow' message is shown instead of the raw error Note: The upstream pi-ai package (@mariozechner/pi-ai) also needs a fix in its OVERFLOW_PATTERNS regex: /exceeds the context window/i should be changed to /exceeds.context window/i to match both 'the' and 'model' variants for triggering auto-compaction retry. fix(tests): remove unused imports and helper from test files Remove WorkspaceBootstrapFile references and _makeFile helper that were incorrectly copied from another test file. These caused type errors and were unrelated to the context overflow detection tests. * fix: trigger auto-compaction on context overflow promptError When the LLM rejects a request with a context overflow error that surfaces as a promptError (thrown exception rather than streamed error), the existing auto-compaction in pi-coding-agent never triggers. This happens because the error bypasses the agent's message_end → agent_end → _checkCompaction path. This fix adds a fallback compaction attempt directly in the run loop: - Detects context overflow in promptError (excluding compaction_failure) - Calls compactEmbeddedPiSessionDirect (bypassing lane queues since already in-lane) - Retries the prompt after successful compaction - Limits to one compaction attempt per run to prevent infinite loops Fixes: context overflow errors shown to user without auto-compaction attempt * style: format compact.ts and run.ts with oxfmt * fix: tighten context overflow match (#1627) (thanks @rodrigouroz) --------- Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Peter Steinberger <steipete@gmail.com>	2026-01-24 22:09:24 +00:00
Peter Steinberger	ac00065727	fix: normalize telegram fetch for long-polling	2026-01-24 21:58:42 +00:00
Peter Steinberger	30534c5c33	docs: add Bedrock EC2 role notes (#1625 ) (thanks @sergical)	2026-01-24 21:18:18 +00:00
Sergiy DybskiyandClaude Opus 4.5	97755683c7	docs: add EC2 instance role setup for Bedrock (#1625 ) - Add EC2 Instance Roles section with workaround for IMDS credential detection - Include step-by-step IAM role and instance profile setup - Document required permissions (bedrock:InvokeModel, ListFoundationModels) - Update example model to Claude Opus 4.5 (latest) The AWS SDK auto-detects EC2 instance roles via IMDS, but Clawdbot's credential detection only checks environment variables. The workaround is to set AWS_PROFILE=default to signal credentials are available. Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-24 21:17:21 +00:00
Peter Steinberger	a4f6b3528a	fix: cover elevated ask approvals (#1636 )	2026-01-24 21:12:46 +00:00
Peter Steinberger	9f8e66359e	fix: default direct gateway port + docs (#1603 ) (thanks @ngutman)	2026-01-24 21:10:54 +00:00
Hunter MillerandPeter Steinberger	8a2720db4c	fix(tlon): Fix Zod v4 record() and @urbit/aura v3 API changes (#1631 ) * fix(tlon): Fix Zod v4 record() and @urbit/aura v3 API changes - Fix Zod v4.3.6 bug: single-arg z.record() fails with toJSONSchema() - Use two-arg form: z.record(z.string(), schema) - Fixes 'Cannot read properties of undefined (reading _zod)' error - Fix @urbit/aura v3.0.0 API migration: - unixToDa() → da.fromUnix() - formatUd() → scot('ud', ...) - Fixes '(0 , _aura.unixToDa) is not a function' error These were blocking Tlon plugin loading and outbound messaging. * fix: add tlon schema/aura tests (#1631) (thanks @arthyn) --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>	2026-01-24 21:09:18 +00:00
Nimrod Gutman	5330595a5a	feat(macos): add direct gateway transport	2026-01-24 21:02:13 +00:00
Peter Steinberger	2c5141d7df	docs: clarify beta promotion flow	2026-01-24 20:59:41 +00:00
Lucas Czekaj Claude Opus 4.5 Peter Steinberger	483fba41b9	feat(discord): add exec approval forwarding to DMs (#1621 ) * feat(discord): add exec approval forwarding to DMs Add support for forwarding exec approval requests to Discord DMs, allowing users to approve/deny command execution via interactive buttons. Features: - New DiscordExecApprovalHandler that connects to gateway and listens for exec.approval.requested/resolved events - Sends DMs with embeds showing command details and 3 buttons: Allow once, Always allow, Deny - Configurable via channels.discord.execApprovals with: - enabled: boolean - approvers: Discord user IDs to notify - agentFilter: only forward for specific agents - sessionFilter: only forward for matching session patterns - Updates message embed when approval is resolved or expires Also fixes exec completion routing: when async exec completes after approval, the heartbeat now uses a specialized prompt to ensure the model relays the result to the user instead of responding HEARTBEAT_OK. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat: generic exec approvals forwarding (#1621) (thanks @czekaj) --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Peter Steinberger <steipete@gmail.com>	2026-01-24 20:56:40 +00:00
Ivan Casco	fe7436a1f6	fix(exec): only set security=full when elevated mode is full (#1616 )	2026-01-24 20:55:21 +00:00
Peter Steinberger	a1ed671636	docs: add backup strategy faq	2026-01-24 20:34:05 +00:00
Peter Steinberger	8c47d226ad	docs: add subscription requirement faq	2026-01-24 20:32:33 +00:00
Peter Steinberger	e1942603e9	docs: add xfinity unblock link	2026-01-24 20:30:03 +00:00
Peter Steinberger	926c2647b8	docs: mention local-only model option	2026-01-24 20:15:58 +00:00
Peter Steinberger	c427f4a2fc	docs: add imessage mac requirement faq	2026-01-24 20:13:13 +00:00
Peter Steinberger	f99f9a6b64	docs: add self-update faq entry	2026-01-24 20:10:47 +00:00
Petter BlombergandPeter Steinberger	39d8c441eb	fix: reduce log noise for node disconnect/late invoke errors (#1607 ) * fix: reduce log noise for node disconnect/late invoke errors - Handle both 'node not connected' and 'node disconnected' errors at info level - Return success with late:true for unknown invoke IDs instead of error - Add 30-second throttle to skills change listener to prevent rapid-fire probes - Add tests for isNodeUnavailableError and late invoke handling * fix: clean up skills refresh timer and listener on shutdown Store the return value from registerSkillsChangeListener() and call it on gateway shutdown. Also clear any pending refresh timer. This follows the same pattern used for agentUnsub and heartbeatUnsub. * refactor: simplify KISS/YAGNI - inline checks, remove unit tests for internal utilities * fix: reduce gateway log noise (#1607) (thanks @petter-b) * test: align agent id casing expectations (#1607) --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>	2026-01-24 20:05:41 +00:00
Peter Steinberger	40ef3b5d30	docs: add linux install faq entry	2026-01-24 19:58:42 +00:00
Peter Steinberger	390b730b37	fix: unify reasoning tags + agent ids (#1613 ) (thanks @kyleok) (#1629 )	2026-01-24 19:56:02 +00:00
Ganghyun KimandClaude Code	71457fa100	fix(tui): strip <final> tags in TUI display (#1613 ) Add <final> tag handling to stripThinkingTags() to prevent reasoning-tag provider responses from leaking incomplete tags during streaming. When using providers like google-antigravity/*, ollama, or minimax, the model wraps responses in <think>...</think> and <final>...</final> tags. The TUI was only stripping <think> tags, causing <final> to leak through and display as the response ~50% of the time. This is a defense-in-depth fix for the TUI layer. Fixes: #1561 Co-authored-by: Claude Code <noreply@anthropic.com>	2026-01-24 19:52:34 +00:00
Peter Steinberger	da7a45b3a5	docs: clarify migration state vs workspace	2026-01-24 19:50:02 +00:00
Denys VitaliandClaude	15a9c21203	Add Build & Release Docker Image workflows (#1602 ) * ci: build & release docker image * ci: sync docker-release workflow updates Squashes: - ci: use correct runs-on - ci: build images Co-Authored-By: Claude <noreply@anthropic.com> * Remove submodule checkout from docker-release.yml Removed submodule checkout step from Docker release workflow. * Simplify Docker release workflow by removing submodule checkout Removed submodule checkout step from Docker release workflow. --------- Co-authored-by: Claude <noreply@anthropic.com>	2026-01-24 19:23:55 +00:00