refactor: consolidate mac debug CLI

apps/macos/Sources/ClawdbotMacCLI/ConnectCommand.swift

@@ -0,0 +1,306 @@
+import ClawdbotKit
+import ClawdbotProtocol
+import Foundation
+
+struct ConnectOptions {
+    var url: String?
+    var token: String?
+    var password: String?
+    var mode: String?
+    var timeoutMs: Int = 15_000
+    var json: Bool = false
+    var probe: Bool = false
+    var clientId: String = "clawdbot-macos"
+    var clientMode: String = "ui"
+    var displayName: String?
+    var role: String = "operator"
+    var scopes: [String] = ["operator.admin", "operator.approvals", "operator.pairing"]
+    var help: Bool = false
+
+    static func parse(_ args: [String]) -> ConnectOptions {
+        var opts = ConnectOptions()
+        var i = 0
+        while i < args.count {
+            let arg = args[i]
+            switch arg {
+            case "-h", "--help":
+                opts.help = true
+            case "--json":
+                opts.json = true
+            case "--probe":
+                opts.probe = true
+            case "--url":
+                opts.url = self.nextValue(args, index: &i)
+            case "--token":
+                opts.token = self.nextValue(args, index: &i)
+            case "--password":
+                opts.password = self.nextValue(args, index: &i)
+            case "--mode":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.mode = value
+                }
+            case "--timeout":
+                if let raw = self.nextValue(args, index: &i),
+                   let parsed = Int(raw.trimmingCharacters(in: .whitespacesAndNewlines))
+                {
+                    opts.timeoutMs = max(250, parsed)
+                }
+            case "--client-id":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.clientId = value
+                }
+            case "--client-mode":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.clientMode = value
+                }
+            case "--display-name":
+                opts.displayName = self.nextValue(args, index: &i)
+            case "--role":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.role = value
+                }
+            case "--scopes":
+                if let value = self.nextValue(args, index: &i) {
+                    opts.scopes = value.split(separator: ",").map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                        .filter { !$0.isEmpty }
+                }
+            default:
+                break
+            }
+            i += 1
+        }
+        return opts
+    }
+
+    private static func nextValue(_ args: [String], index: inout Int) -> String? {
+        guard index + 1 < args.count else { return nil }
+        index += 1
+        return args[index].trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
+
+struct ConnectOutput: Encodable {
+    var status: String
+    var url: String
+    var mode: String
+    var role: String
+    var clientId: String
+    var clientMode: String
+    var scopes: [String]
+    var snapshot: HelloOk?
+    var health: ProtoAnyCodable?
+    var error: String?
+}
+
+actor SnapshotStore {
+    private var value: HelloOk?
+
+    func set(_ snapshot: HelloOk) {
+        self.value = snapshot
+    }
+
+    func get() -> HelloOk? {
+        self.value
+    }
+}
+
+func runConnect(_ args: [String]) async {
+    let opts = ConnectOptions.parse(args)
+    if opts.help {
+        print("""
+        clawdbot-mac connect
+
+        Usage:
+          clawdbot-mac connect [--url <ws://host:port>] [--token <token>] [--password <password>]
+                               [--mode <local|remote>] [--timeout <ms>] [--probe] [--json]
+                               [--client-id <id>] [--client-mode <mode>] [--display-name <name>]
+                               [--role <role>] [--scopes <a,b,c>]
+
+        Options:
+          --url <url>        Gateway WebSocket URL (overrides config)
+          --token <token>    Gateway token (if required)
+          --password <pw>    Gateway password (if required)
+          --mode <mode>      Resolve from config: local|remote (default: config or local)
+          --timeout <ms>     Request timeout (default: 15000)
+          --probe            Force a fresh health probe
+          --json             Emit JSON
+          --client-id <id>   Override client id (default: clawdbot-macos)
+          --client-mode <m>  Override client mode (default: ui)
+          --display-name <n> Override display name
+          --role <role>      Override role (default: operator)
+          --scopes <a,b,c>   Override scopes list
+          -h, --help         Show help
+        """)
+        return
+    }
+
+    let config = loadGatewayConfig()
+    do {
+        let endpoint = try resolveGatewayEndpoint(opts: opts, config: config)
+        let displayName = opts.displayName ?? Host.current().localizedName ?? "Clawdbot macOS Debug CLI"
+        let connectOptions = GatewayConnectOptions(
+            role: opts.role,
+            scopes: opts.scopes,
+            caps: [],
+            commands: [],
+            permissions: [:],
+            clientId: opts.clientId,
+            clientMode: opts.clientMode,
+            clientDisplayName: displayName)
+
+        let snapshotStore = SnapshotStore()
+        let channel = GatewayChannelActor(
+            url: endpoint.url,
+            token: endpoint.token,
+            password: endpoint.password,
+            pushHandler: { push in
+                if case let .snapshot(ok) = push {
+                    await snapshotStore.set(ok)
+                }
+            },
+            connectOptions: connectOptions)
+
+        let params: [String: KitAnyCodable]? = opts.probe ? ["probe": KitAnyCodable(true)] : nil
+        let data = try await channel.request(
+            method: "health",
+            params: params,
+            timeoutMs: Double(opts.timeoutMs))
+        let health = try? JSONDecoder().decode(ProtoAnyCodable.self, from: data)
+        let snapshot = await snapshotStore.get()
+        await channel.shutdown()
+
+        let output = ConnectOutput(
+            status: "ok",
+            url: endpoint.url.absoluteString,
+            mode: endpoint.mode,
+            role: opts.role,
+            clientId: opts.clientId,
+            clientMode: opts.clientMode,
+            scopes: opts.scopes,
+            snapshot: snapshot,
+            health: health,
+            error: nil)
+        printConnectOutput(output, json: opts.json)
+    } catch {
+        let endpoint = bestEffortEndpoint(opts: opts, config: config)
+        let fallbackMode = (opts.mode ?? config.mode ?? "local").lowercased()
+        let output = ConnectOutput(
+            status: "error",
+            url: endpoint?.url.absoluteString ?? "unknown",
+            mode: endpoint?.mode ?? fallbackMode,
+            role: opts.role,
+            clientId: opts.clientId,
+            clientMode: opts.clientMode,
+            scopes: opts.scopes,
+            snapshot: nil,
+            health: nil,
+            error: error.localizedDescription)
+        printConnectOutput(output, json: opts.json)
+        exit(1)
+    }
+}
+
+private func printConnectOutput(_ output: ConnectOutput, json: Bool) {
+    if json {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        if let data = try? encoder.encode(output),
+           let text = String(data: data, encoding: .utf8)
+        {
+            print(text)
+        } else {
+            print("{\"error\":\"failed to encode JSON\"}")
+        }
+        return
+    }
+
+    print("Clawdbot macOS Gateway Connect")
+    print("Status: \(output.status)")
+    print("URL: \(output.url)")
+    print("Mode: \(output.mode)")
+    print("Client: \(output.clientId) (\(output.clientMode))")
+    print("Role: \(output.role)")
+    print("Scopes: \(output.scopes.joined(separator: ", "))")
+    if let snapshot = output.snapshot {
+        print("Protocol: \(snapshot._protocol)")
+        if let version = snapshot.server["version"]?.value as? String {
+            print("Server: \(version)")
+        }
+    }
+    if let health = output.health,
+       let ok = (health.value as? [String: ProtoAnyCodable])?["ok"]?.value as? Bool
+    {
+        print("Health: \(ok ? "ok" : "error")")
+    } else if output.health != nil {
+        print("Health: received")
+    }
+    if let error = output.error {
+        print("Error: \(error)")
+    }
+}
+
+private func resolveGatewayEndpoint(opts: ConnectOptions, config: GatewayConfig) throws -> GatewayEndpoint {
+    let resolvedMode = (opts.mode ?? config.mode ?? "local").lowercased()
+    if let raw = opts.url, !raw.isEmpty {
+        guard let url = URL(string: raw) else {
+            throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid url: \(raw)"])
+        }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, mode: resolvedMode, config: config),
+            password: resolvedPassword(opts: opts, mode: resolvedMode, config: config),
+            mode: resolvedMode)
+    }
+
+    if resolvedMode == "remote" {
+        guard let raw = config.remoteUrl?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !raw.isEmpty else {
+            throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "gateway.remote.url is missing"])
+        }
+        guard let url = URL(string: raw) else {
+            throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid url: \(raw)"])
+        }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, mode: resolvedMode, config: config),
+            password: resolvedPassword(opts: opts, mode: resolvedMode, config: config),
+            mode: resolvedMode)
+    }
+
+    let port = config.port ?? 18789
+    let host = "127.0.0.1"
+    guard let url = URL(string: "ws://\(host):\(port)") else {
+        throw NSError(domain: "Gateway", code: 1, userInfo: [NSLocalizedDescriptionKey: "invalid url: ws://\(host):\(port)"])
+    }
+    return GatewayEndpoint(
+        url: url,
+        token: resolvedToken(opts: opts, mode: resolvedMode, config: config),
+        password: resolvedPassword(opts: opts, mode: resolvedMode, config: config),
+        mode: resolvedMode)
+}
+
+private func bestEffortEndpoint(opts: ConnectOptions, config: GatewayConfig) -> GatewayEndpoint? {
+    return try? resolveGatewayEndpoint(opts: opts, config: config)
+}
+
+private func resolvedToken(opts: ConnectOptions, mode: String, config: GatewayConfig) -> String? {
+    if let token = opts.token, !token.isEmpty { return token }
+    if let token = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_TOKEN"], !token.isEmpty {
+        return token
+    }
+    if mode == "remote" {
+        return config.remoteToken
+    }
+    return config.token
+}
+
+private func resolvedPassword(opts: ConnectOptions, mode: String, config: GatewayConfig) -> String? {
+    if let password = opts.password, !password.isEmpty { return password }
+    if let password = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_PASSWORD"], !password.isEmpty {
+        return password
+    }
+    if mode == "remote" {
+        return config.remotePassword
+    }
+    return config.password
+}

apps/macos/Sources/ClawdbotMacCLI/DiscoverCommand.swift

@@ -0,0 +1,149 @@
+import ClawdbotDiscovery
+import Foundation
+
+struct DiscoveryOptions {
+    var timeoutMs: Int = 2000
+    var json: Bool = false
+    var includeLocal: Bool = false
+    var help: Bool = false
+
+    static func parse(_ args: [String]) -> DiscoveryOptions {
+        var opts = DiscoveryOptions()
+        var i = 0
+        while i < args.count {
+            let arg = args[i]
+            switch arg {
+            case "-h", "--help":
+                opts.help = true
+            case "--json":
+                opts.json = true
+            case "--include-local":
+                opts.includeLocal = true
+            case "--timeout":
+                let next = (i + 1 < args.count) ? args[i + 1] : nil
+                if let next, let parsed = Int(next.trimmingCharacters(in: .whitespacesAndNewlines)) {
+                    opts.timeoutMs = max(100, parsed)
+                    i += 1
+                }
+            default:
+                break
+            }
+            i += 1
+        }
+        return opts
+    }
+}
+
+struct DiscoveryOutput: Encodable {
+    struct Gateway: Encodable {
+        var displayName: String
+        var lanHost: String?
+        var tailnetDns: String?
+        var sshPort: Int
+        var gatewayPort: Int?
+        var cliPath: String?
+        var stableID: String
+        var debugID: String
+        var isLocal: Bool
+    }
+
+    var status: String
+    var timeoutMs: Int
+    var includeLocal: Bool
+    var count: Int
+    var gateways: [Gateway]
+}
+
+func runDiscover(_ args: [String]) async {
+    let opts = DiscoveryOptions.parse(args)
+    if opts.help {
+        print("""
+        clawdbot-mac discover
+
+        Usage:
+          clawdbot-mac discover [--timeout <ms>] [--json] [--include-local]
+
+        Options:
+          --timeout <ms>     Discovery window in milliseconds (default: 2000)
+          --json             Emit JSON
+          --include-local    Include gateways considered local
+          -h, --help         Show help
+        """)
+        return
+    }
+
+    let displayName = Host.current().localizedName ?? ProcessInfo.processInfo.hostName
+    let model = await MainActor.run {
+        GatewayDiscoveryModel(
+            localDisplayName: displayName,
+            filterLocalGateways: !opts.includeLocal)
+    }
+
+    await MainActor.run {
+        model.start()
+    }
+
+    let nanos = UInt64(max(100, opts.timeoutMs)) * 1_000_000
+    try? await Task.sleep(nanoseconds: nanos)
+
+    let gateways = await MainActor.run { model.gateways }
+    let status = await MainActor.run { model.statusText }
+
+    await MainActor.run {
+        model.stop()
+    }
+
+    if opts.json {
+        let payload = DiscoveryOutput(
+            status: status,
+            timeoutMs: opts.timeoutMs,
+            includeLocal: opts.includeLocal,
+            count: gateways.count,
+            gateways: gateways.map {
+                DiscoveryOutput.Gateway(
+                    displayName: $0.displayName,
+                    lanHost: $0.lanHost,
+                    tailnetDns: $0.tailnetDns,
+                    sshPort: $0.sshPort,
+                    gatewayPort: $0.gatewayPort,
+                    cliPath: $0.cliPath,
+                    stableID: $0.stableID,
+                    debugID: $0.debugID,
+                    isLocal: $0.isLocal)
+            })
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        if let data = try? encoder.encode(payload),
+           let json = String(data: data, encoding: .utf8)
+        {
+            print(json)
+        } else {
+            print("{\"error\":\"failed to encode JSON\"}")
+        }
+        return
+    }
+
+    print("Gateway Discovery (macOS NWBrowser)")
+    print("Status: \(status)")
+    print("Found \(gateways.count) gateway(s)\(opts.includeLocal ? "" : " (local filtered)")")
+    if gateways.isEmpty { return }
+
+    for gateway in gateways {
+        let hosts = [gateway.tailnetDns, gateway.lanHost]
+            .compactMap { $0?.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .joined(separator: ", ")
+        print("- \(gateway.displayName)")
+        print("  hosts: \(hosts.isEmpty ? "(none)" : hosts)")
+        print("  ssh: \(gateway.sshPort)")
+        if let port = gateway.gatewayPort {
+            print("  gatewayPort: \(port)")
+        }
+        if let cliPath = gateway.cliPath {
+            print("  cliPath: \(cliPath)")
+        }
+        print("  isLocal: \(gateway.isLocal)")
+        print("  stableID: \(gateway.stableID)")
+        print("  debugID: \(gateway.debugID)")
+    }
+}

apps/macos/Sources/ClawdbotMacCLI/EntryPoint.swift

@@ -0,0 +1,56 @@
+import Foundation
+
+private struct RootCommand {
+    var name: String
+    var args: [String]
+}
+
+@main
+struct ClawdbotMacCLI {
+    static func main() async {
+        let args = Array(CommandLine.arguments.dropFirst())
+        let command = parseRootCommand(args)
+        switch command?.name {
+        case nil:
+            printUsage()
+        case "-h", "--help", "help":
+            printUsage()
+        case "connect":
+            await runConnect(command?.args ?? [])
+        case "discover":
+            await runDiscover(command?.args ?? [])
+        case "wizard":
+            await runWizardCommand(command?.args ?? [])
+        default:
+            fputs("clawdbot-mac: unknown command\n", stderr)
+            printUsage()
+            exit(1)
+        }
+    }
+}
+
+private func parseRootCommand(_ args: [String]) -> RootCommand? {
+    guard let first = args.first else { return nil }
+    return RootCommand(name: first, args: Array(args.dropFirst()))
+}
+
+private func printUsage() {
+    print("""
+    clawdbot-mac
+
+    Usage:
+      clawdbot-mac connect [--url <ws://host:port>] [--token <token>] [--password <password>]
+                           [--mode <local|remote>] [--timeout <ms>] [--probe] [--json]
+                           [--client-id <id>] [--client-mode <mode>] [--display-name <name>]
+                           [--role <role>] [--scopes <a,b,c>]
+      clawdbot-mac discover [--timeout <ms>] [--json] [--include-local]
+      clawdbot-mac wizard [--url <ws://host:port>] [--token <token>] [--password <password>]
+                          [--mode <local|remote>] [--workspace <path>] [--json]
+
+    Examples:
+      clawdbot-mac connect
+      clawdbot-mac connect --url ws://127.0.0.1:18789 --json
+      clawdbot-mac discover --timeout 3000 --json
+      clawdbot-mac wizard --mode local
+    """)
+}

apps/macos/Sources/ClawdbotMacCLI/GatewayConfig.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+struct GatewayConfig {
+    var mode: String?
+    var bind: String?
+    var port: Int?
+    var remoteUrl: String?
+    var token: String?
+    var password: String?
+    var remoteToken: String?
+    var remotePassword: String?
+}
+
+struct GatewayEndpoint {
+    let url: URL
+    let token: String?
+    let password: String?
+    let mode: String
+}
+
+func loadGatewayConfig() -> GatewayConfig {
+    let url = FileManager().homeDirectoryForCurrentUser
+        .appendingPathComponent(".clawdbot")
+        .appendingPathComponent("clawdbot.json")
+    guard let data = try? Data(contentsOf: url) else { return GatewayConfig() }
+    guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+        return GatewayConfig()
+    }
+
+    var cfg = GatewayConfig()
+    if let gateway = json["gateway"] as? [String: Any] {
+        cfg.mode = gateway["mode"] as? String
+        cfg.bind = gateway["bind"] as? String
+        cfg.port = gateway["port"] as? Int ?? parseInt(gateway["port"])
+
+        if let auth = gateway["auth"] as? [String: Any] {
+            cfg.token = auth["token"] as? String
+            cfg.password = auth["password"] as? String
+        }
+        if let remote = gateway["remote"] as? [String: Any] {
+            cfg.remoteUrl = remote["url"] as? String
+            cfg.remoteToken = remote["token"] as? String
+            cfg.remotePassword = remote["password"] as? String
+        }
+    }
+    return cfg
+}
+
+func parseInt(_ value: Any?) -> Int? {
+    switch value {
+    case let number as Int:
+        number
+    case let number as Double:
+        Int(number)
+    case let raw as String:
+        Int(raw.trimmingCharacters(in: .whitespacesAndNewlines))
+    default:
+        nil
+    }
+}

apps/macos/Sources/ClawdbotMacCLI/TypeAliases.swift

@@ -0,0 +1,5 @@
+import ClawdbotKit
+import ClawdbotProtocol
+
+typealias ProtoAnyCodable = ClawdbotProtocol.AnyCodable
+typealias KitAnyCodable = ClawdbotKit.AnyCodable

apps/macos/Sources/ClawdbotMacCLI/WizardCommand.swift

@@ -0,0 +1,553 @@
+import ClawdbotKit
+import ClawdbotProtocol
+import Darwin
+import Foundation
+
+struct WizardCliOptions {
+    var url: String?
+    var token: String?
+    var password: String?
+    var mode: String = "local"
+    var workspace: String?
+    var json: Bool = false
+    var help: Bool = false
+
+    static func parse(_ args: [String]) -> WizardCliOptions {
+        var opts = WizardCliOptions()
+        var i = 0
+        while i < args.count {
+            let arg = args[i]
+            switch arg {
+            case "-h", "--help":
+                opts.help = true
+            case "--json":
+                opts.json = true
+            case "--url":
+                opts.url = self.nextValue(args, index: &i)
+            case "--token":
+                opts.token = self.nextValue(args, index: &i)
+            case "--password":
+                opts.password = self.nextValue(args, index: &i)
+            case "--mode":
+                if let value = nextValue(args, index: &i) {
+                    opts.mode = value
+                }
+            case "--workspace":
+                opts.workspace = self.nextValue(args, index: &i)
+            default:
+                break
+            }
+            i += 1
+        }
+        return opts
+    }
+
+    private static func nextValue(_ args: [String], index: inout Int) -> String? {
+        guard index + 1 < args.count else { return nil }
+        index += 1
+        return args[index].trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
+
+enum WizardCliError: Error, CustomStringConvertible {
+    case invalidUrl(String)
+    case missingRemoteUrl
+    case gatewayError(String)
+    case decodeError(String)
+    case cancelled
+
+    var description: String {
+        switch self {
+        case let .invalidUrl(raw): "Invalid URL: \(raw)"
+        case .missingRemoteUrl: "gateway.remote.url is missing"
+        case let .gatewayError(msg): msg
+        case let .decodeError(msg): msg
+        case .cancelled: "Wizard cancelled"
+        }
+    }
+}
+
+func runWizardCommand(_ args: [String]) async {
+    let opts = WizardCliOptions.parse(args)
+    if opts.help {
+        print("""
+        clawdbot-mac wizard
+
+        Usage:
+          clawdbot-mac wizard [--url <ws://host:port>] [--token <token>] [--password <password>]
+                              [--mode <local|remote>] [--workspace <path>] [--json]
+
+        Options:
+          --url <url>        Gateway WebSocket URL (overrides config)
+          --token <token>    Gateway token (if required)
+          --password <pw>    Gateway password (if required)
+          --mode <mode>      Wizard mode (local|remote). Default: local
+          --workspace <path> Wizard workspace override
+          --json             Print raw wizard responses
+          -h, --help         Show help
+        """)
+        return
+    }
+
+    let config = loadGatewayConfig()
+    do {
+        guard isatty(STDIN_FILENO) != 0 else {
+            throw WizardCliError.gatewayError("Wizard requires an interactive TTY.")
+        }
+        let endpoint = try resolveWizardGatewayEndpoint(opts: opts, config: config)
+        let client = GatewayWizardClient(
+            url: endpoint.url,
+            token: endpoint.token,
+            password: endpoint.password,
+            json: opts.json)
+        try await client.connect()
+        defer { Task { await client.close() } }
+        try await runWizard(client: client, opts: opts)
+    } catch {
+        fputs("wizard: \(error)\n", stderr)
+        exit(1)
+    }
+}
+
+private func resolveWizardGatewayEndpoint(opts: WizardCliOptions, config: GatewayConfig) throws -> GatewayEndpoint {
+    if let raw = opts.url, !raw.isEmpty {
+        guard let url = URL(string: raw) else { throw WizardCliError.invalidUrl(raw) }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, config: config),
+            password: resolvedPassword(opts: opts, config: config),
+            mode: (config.mode ?? "local").lowercased())
+    }
+
+    let mode = (config.mode ?? "local").lowercased()
+    if mode == "remote" {
+        guard let raw = config.remoteUrl?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+            throw WizardCliError.missingRemoteUrl
+        }
+        guard let url = URL(string: raw) else { throw WizardCliError.invalidUrl(raw) }
+        return GatewayEndpoint(
+            url: url,
+            token: resolvedToken(opts: opts, config: config),
+            password: resolvedPassword(opts: opts, config: config),
+            mode: mode)
+    }
+
+    let port = config.port ?? 18789
+    let host = "127.0.0.1"
+    guard let url = URL(string: "ws://\(host):\(port)") else {
+        throw WizardCliError.invalidUrl("ws://\(host):\(port)")
+    }
+    return GatewayEndpoint(
+        url: url,
+        token: resolvedToken(opts: opts, config: config),
+        password: resolvedPassword(opts: opts, config: config),
+        mode: mode)
+}
+
+private func resolvedToken(opts: WizardCliOptions, config: GatewayConfig) -> String? {
+    if let token = opts.token, !token.isEmpty { return token }
+    if let token = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_TOKEN"], !token.isEmpty {
+        return token
+    }
+    if (config.mode ?? "local").lowercased() == "remote" {
+        return config.remoteToken
+    }
+    return config.token
+}
+
+private func resolvedPassword(opts: WizardCliOptions, config: GatewayConfig) -> String? {
+    if let password = opts.password, !password.isEmpty { return password }
+    if let password = ProcessInfo.processInfo.environment["CLAWDBOT_GATEWAY_PASSWORD"], !password.isEmpty {
+        return password
+    }
+    if (config.mode ?? "local").lowercased() == "remote" {
+        return config.remotePassword
+    }
+    return config.password
+}
+
+actor GatewayWizardClient {
+    private enum ConnectChallengeError: Error {
+        case timeout
+    }
+
+    private let url: URL
+    private let token: String?
+    private let password: String?
+    private let json: Bool
+    private let encoder = JSONEncoder()
+    private let decoder = JSONDecoder()
+    private let session = URLSession(configuration: .default)
+    private let connectChallengeTimeoutSeconds: Double = 0.75
+    private var task: URLSessionWebSocketTask?
+
+    init(url: URL, token: String?, password: String?, json: Bool) {
+        self.url = url
+        self.token = token
+        self.password = password
+        self.json = json
+    }
+
+    func connect() async throws {
+        let socket = self.session.webSocketTask(with: self.url)
+        socket.maximumMessageSize = 16 * 1024 * 1024
+        socket.resume()
+        self.task = socket
+        try await self.sendConnect()
+    }
+
+    func close() {
+        self.task?.cancel(with: .goingAway, reason: nil)
+        self.task = nil
+    }
+
+    func request(method: String, params: [String: ProtoAnyCodable]?) async throws -> ResponseFrame {
+        guard let task = self.task else {
+            throw WizardCliError.gatewayError("gateway not connected")
+        }
+        let id = UUID().uuidString
+        let frame = RequestFrame(
+            type: "req",
+            id: id,
+            method: method,
+            params: params.map { ProtoAnyCodable($0) })
+        let data = try self.encoder.encode(frame)
+        try await task.send(.data(data))
+
+        while true {
+            let message = try await task.receive()
+            let frame = try decodeFrame(message)
+            if case let .res(res) = frame, res.id == id {
+                if res.ok == false {
+                    let msg = (res.error?["message"]?.value as? String) ?? "gateway error"
+                    throw WizardCliError.gatewayError(msg)
+                }
+                return res
+            }
+        }
+    }
+
+    func decodePayload<T: Decodable>(_ response: ResponseFrame, as _: T.Type) throws -> T {
+        guard let payload = response.payload else {
+            throw WizardCliError.decodeError("missing payload")
+        }
+        let data = try self.encoder.encode(payload)
+        return try self.decoder.decode(T.self, from: data)
+    }
+
+    private func decodeFrame(_ message: URLSessionWebSocketTask.Message) throws -> GatewayFrame {
+        let data: Data? = switch message {
+        case let .data(data): data
+        case let .string(text): text.data(using: .utf8)
+        @unknown default: nil
+        }
+        guard let data else {
+            throw WizardCliError.decodeError("empty gateway response")
+        }
+        return try self.decoder.decode(GatewayFrame.self, from: data)
+    }
+
+    private func sendConnect() async throws {
+        guard let task = self.task else {
+            throw WizardCliError.gatewayError("gateway not connected")
+        }
+        let osVersion = ProcessInfo.processInfo.operatingSystemVersion
+        let platform = "macos \(osVersion.majorVersion).\(osVersion.minorVersion).\(osVersion.patchVersion)"
+        let clientId = "clawdbot-macos"
+        let clientMode = "ui"
+        let role = "operator"
+        let scopes: [String] = []
+        let client: [String: ProtoAnyCodable] = [
+            "id": ProtoAnyCodable(clientId),
+            "displayName": ProtoAnyCodable(Host.current().localizedName ?? "Clawdbot macOS Wizard CLI"),
+            "version": ProtoAnyCodable("dev"),
+            "platform": ProtoAnyCodable(platform),
+            "deviceFamily": ProtoAnyCodable("Mac"),
+            "mode": ProtoAnyCodable(clientMode),
+            "instanceId": ProtoAnyCodable(UUID().uuidString),
+        ]
+
+        var params: [String: ProtoAnyCodable] = [
+            "minProtocol": ProtoAnyCodable(GATEWAY_PROTOCOL_VERSION),
+            "maxProtocol": ProtoAnyCodable(GATEWAY_PROTOCOL_VERSION),
+            "client": ProtoAnyCodable(client),
+            "caps": ProtoAnyCodable([String]()),
+            "locale": ProtoAnyCodable(Locale.preferredLanguages.first ?? Locale.current.identifier),
+            "userAgent": ProtoAnyCodable(ProcessInfo.processInfo.operatingSystemVersionString),
+            "role": ProtoAnyCodable(role),
+            "scopes": ProtoAnyCodable(scopes),
+        ]
+        if let token = self.token {
+            params["auth"] = ProtoAnyCodable(["token": ProtoAnyCodable(token)])
+        } else if let password = self.password {
+            params["auth"] = ProtoAnyCodable(["password": ProtoAnyCodable(password)])
+        }
+        let connectNonce = try await self.waitForConnectChallenge()
+        let identity = DeviceIdentityStore.loadOrCreate()
+        let signedAtMs = Int(Date().timeIntervalSince1970 * 1000)
+        let scopesValue = scopes.joined(separator: ",")
+        var payloadParts = [
+            connectNonce == nil ? "v1" : "v2",
+            identity.deviceId,
+            clientId,
+            clientMode,
+            role,
+            scopesValue,
+            String(signedAtMs),
+            self.token ?? "",
+        ]
+        if let connectNonce {
+            payloadParts.append(connectNonce)
+        }
+        let payload = payloadParts.joined(separator: "|")
+        if let signature = DeviceIdentityStore.signPayload(payload, identity: identity),
+           let publicKey = DeviceIdentityStore.publicKeyBase64Url(identity)
+        {
+            var device: [String: ProtoAnyCodable] = [
+                "id": ProtoAnyCodable(identity.deviceId),
+                "publicKey": ProtoAnyCodable(publicKey),
+                "signature": ProtoAnyCodable(signature),
+                "signedAt": ProtoAnyCodable(signedAtMs),
+            ]
+            if let connectNonce {
+                device["nonce"] = ProtoAnyCodable(connectNonce)
+            }
+            params["device"] = ProtoAnyCodable(device)
+        }
+
+        let reqId = UUID().uuidString
+        let frame = RequestFrame(
+            type: "req",
+            id: reqId,
+            method: "connect",
+            params: ProtoAnyCodable(params))
+        let data = try self.encoder.encode(frame)
+        try await task.send(.data(data))
+
+        while true {
+            let message = try await task.receive()
+            let frameResponse = try decodeFrame(message)
+            if case let .res(res) = frameResponse, res.id == reqId {
+                if res.ok == false {
+                    let msg = (res.error?["message"]?.value as? String) ?? "gateway connect failed"
+                    throw WizardCliError.gatewayError(msg)
+                }
+                _ = try self.decodePayload(res, as: HelloOk.self)
+                return
+            }
+        }
+    }
+
+    private func waitForConnectChallenge() async throws -> String? {
+        guard let task = self.task else { return nil }
+        do {
+            return try await AsyncTimeout.withTimeout(
+                seconds: self.connectChallengeTimeoutSeconds,
+                onTimeout: { ConnectChallengeError.timeout },
+                operation: {
+                    while true {
+                        let message = try await task.receive()
+                        let frame = try await self.decodeFrame(message)
+                        if case let .event(evt) = frame, evt.event == "connect.challenge" {
+                            if let payload = evt.payload?.value as? [String: ProtoAnyCodable],
+                               let nonce = payload["nonce"]?.value as? String
+                            {
+                                return nonce
+                            }
+                        }
+                    }
+                })
+        } catch {
+            if error is ConnectChallengeError { return nil }
+            throw error
+        }
+    }
+}
+
+private func runWizard(client: GatewayWizardClient, opts: WizardCliOptions) async throws {
+    var params: [String: ProtoAnyCodable] = [:]
+    let mode = opts.mode.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+    if mode == "local" || mode == "remote" {
+        params["mode"] = ProtoAnyCodable(mode)
+    }
+    if let workspace = opts.workspace?.trimmingCharacters(in: .whitespacesAndNewlines), !workspace.isEmpty {
+        params["workspace"] = ProtoAnyCodable(workspace)
+    }
+
+    let startResponse = try await client.request(method: "wizard.start", params: params)
+    let startResult = try await client.decodePayload(startResponse, as: WizardStartResult.self)
+    if opts.json {
+        dumpResult(startResponse)
+    }
+
+    let sessionId = startResult.sessionid
+    var nextResult = WizardNextResult(
+        done: startResult.done,
+        step: startResult.step,
+        status: startResult.status,
+        error: startResult.error)
+
+    do {
+        while true {
+            let status = wizardStatusString(nextResult.status) ?? (nextResult.done ? "done" : "running")
+            if status == "cancelled" {
+                print("Wizard cancelled.")
+                return
+            }
+            if status == "error" || (nextResult.done && nextResult.error != nil) {
+                throw WizardCliError.gatewayError(nextResult.error ?? "wizard error")
+            }
+            if status == "done" || nextResult.done {
+                print("Wizard complete.")
+                return
+            }
+
+            if let step = decodeWizardStep(nextResult.step) {
+                let answer = try promptAnswer(for: step)
+                var answerPayload: [String: ProtoAnyCodable] = [
+                    "stepId": ProtoAnyCodable(step.id),
+                ]
+                if !(answer is NSNull) {
+                    answerPayload["value"] = ProtoAnyCodable(answer)
+                }
+                let response = try await client.request(
+                    method: "wizard.next",
+                    params: [
+                        "sessionId": ProtoAnyCodable(sessionId),
+                        "answer": ProtoAnyCodable(answerPayload),
+                    ])
+                nextResult = try await client.decodePayload(response, as: WizardNextResult.self)
+                if opts.json {
+                    dumpResult(response)
+                }
+            } else {
+                let response = try await client.request(
+                    method: "wizard.next",
+                    params: ["sessionId": ProtoAnyCodable(sessionId)])
+                nextResult = try await client.decodePayload(response, as: WizardNextResult.self)
+                if opts.json {
+                    dumpResult(response)
+                }
+            }
+        }
+    } catch WizardCliError.cancelled {
+        _ = try? await client.request(
+            method: "wizard.cancel",
+            params: ["sessionId": ProtoAnyCodable(sessionId)])
+        throw WizardCliError.cancelled
+    }
+}
+
+private func dumpResult(_ response: ResponseFrame) {
+    guard let payload = response.payload else {
+        print("{\"error\":\"missing payload\"}")
+        return
+    }
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+    if let data = try? encoder.encode(payload), let text = String(data: data, encoding: .utf8) {
+        print(text)
+    }
+}
+
+private func promptAnswer(for step: WizardStep) throws -> Any {
+    let type = wizardStepType(step)
+    if let title = step.title, !title.isEmpty {
+        print("\n\(title)")
+    }
+    if let message = step.message, !message.isEmpty {
+        print(message)
+    }
+
+    switch type {
+    case "note":
+        _ = try readLineWithPrompt("Continue? (enter)")
+        return NSNull()
+    case "progress":
+        _ = try readLineWithPrompt("Continue? (enter)")
+        return NSNull()
+    case "action":
+        _ = try readLineWithPrompt("Run? (enter)")
+        return true
+    case "text":
+        let initial = anyCodableString(step.initialvalue)
+        let prompt = step.placeholder ?? "Value"
+        let value = try readLineWithPrompt("\(prompt)\(initial.isEmpty ? "" : " [\(initial)]")")
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? initial : trimmed
+    case "confirm":
+        let initial = anyCodableBool(step.initialvalue)
+        let value = try readLineWithPrompt("Confirm? (y/n) [\(initial ? "y" : "n")]")
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if trimmed.isEmpty { return initial }
+        return trimmed == "y" || trimmed == "yes" || trimmed == "true"
+    case "select":
+        return try promptSelect(step)
+    case "multiselect":
+        return try promptMultiSelect(step)
+    default:
+        _ = try readLineWithPrompt("Continue? (enter)")
+        return NSNull()
+    }
+}
+
+private func promptSelect(_ step: WizardStep) throws -> Any {
+    let options = parseWizardOptions(step.options)
+    guard !options.isEmpty else { return NSNull() }
+    for (idx, option) in options.enumerated() {
+        let hint = option.hint?.isEmpty == false ? " — \(option.hint!)" : ""
+        print("  [\(idx + 1)] \(option.label)\(hint)")
+    }
+    let initialIndex = options.firstIndex(where: { anyCodableEqual($0.value, step.initialvalue) })
+    let defaultLabel = initialIndex.map { " [\($0 + 1)]" } ?? ""
+    while true {
+        let input = try readLineWithPrompt("Select one\(defaultLabel)")
+        let trimmed = input.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty, let initialIndex {
+            return options[initialIndex].value?.value ?? options[initialIndex].label
+        }
+        if trimmed.lowercased() == "q" { throw WizardCliError.cancelled }
+        if let number = Int(trimmed), (1...options.count).contains(number) {
+            let option = options[number - 1]
+            return option.value?.value ?? option.label
+        }
+        print("Invalid selection.")
+    }
+}
+
+private func promptMultiSelect(_ step: WizardStep) throws -> [Any] {
+    let options = parseWizardOptions(step.options)
+    guard !options.isEmpty else { return [] }
+    for (idx, option) in options.enumerated() {
+        let hint = option.hint?.isEmpty == false ? " — \(option.hint!)" : ""
+        print("  [\(idx + 1)] \(option.label)\(hint)")
+    }
+    let initialValues = anyCodableArray(step.initialvalue)
+    let initialIndices = options.enumerated().compactMap { index, option in
+        initialValues.contains { anyCodableEqual($0, option.value) } ? index + 1 : nil
+    }
+    let defaultLabel = initialIndices.isEmpty ? "" : " [\(initialIndices.map(String.init).joined(separator: ","))]"
+    while true {
+        let input = try readLineWithPrompt("Select (comma-separated)\(defaultLabel)")
+        let trimmed = input.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            return initialIndices.map { options[$0 - 1].value?.value ?? options[$0 - 1].label }
+        }
+        if trimmed.lowercased() == "q" { throw WizardCliError.cancelled }
+        let parts = trimmed.split(separator: ",").map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        let indices = parts.compactMap { Int($0) }.filter { (1...options.count).contains($0) }
+        if indices.isEmpty {
+            print("Invalid selection.")
+            continue
+        }
+        return indices.map { options[$0 - 1].value?.value ?? options[$0 - 1].label }
+    }
+}
+
+private func readLineWithPrompt(_ prompt: String) throws -> String {
+    print("\(prompt): ", terminator: "")
+    guard let line = readLine() else {
+        throw WizardCliError.cancelled
+    }
+    return line
+}