@aimarket/warden 0.20.0 → 0.21.0

package/native/macos/Sources/WardenDesktop/NativeSurface.swift

@@ -0,0 +1,246 @@
+import AppKit
+import CryptoKit
+import Security
+import ObjectiveC
+
+public let wardenAtomicProtocol = "warden.screen.atomic.v1"
+
+public enum DesktopError: Error { case invalid, unavailable, unsupported, uncertain }
+private func digest(_ data: Data) -> String { SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() }
+private func digest(_ text: String) -> String { digest(Data(text.utf8)) }
+private func opaque() throws -> String {
+    var bytes = [UInt8](repeating: 0, count: 32)
+    guard SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes) == errSecSuccess else { throw DesktopError.unavailable }
+    return bytes.map { String(format: "%02x", $0) }.joined()
+}
+private func json(_ value: Any) throws -> String {
+    let data = try JSONSerialization.data(withJSONObject: value, options: [.fragmentsAllowed, .withoutEscapingSlashes, .sortedKeys])
+    guard let result = String(data: data, encoding: .utf8) else { throw DesktopError.invalid }
+    return result
+}
+private func exact(_ value: [String: Any], _ keys: [String]) -> Bool { Set(value.keys) == Set(keys) }
+private func hex(_ value: Any?) -> String? {
+    guard let s = value as? String, s.count == 64, s.allSatisfy({ "0123456789abcdef".contains($0) }) else { return nil }; return s
+}
+private func number(_ value: Any?) -> Double? {
+    guard let n = value as? NSNumber, CFGetTypeID(n) != CFBooleanGetTypeID(), n.doubleValue.isFinite, abs(n.doubleValue) <= 1_000_000 else { return nil }
+    return n.doubleValue
+}
+private typealias NativeAction = @convention(c) (AnyObject, Selector, AnyObject) -> Void
+private func actionImplementation(_ target: NSObject, _ selector: Selector) -> IMP? {
+    guard NSStringFromSelector(selector).filter({ $0 == ":" }).count == 1,
+          let method = class_getInstanceMethod(type(of: target), selector), method_getNumberOfArguments(method) == 3 else { return nil }
+    var returns = [CChar](repeating: 0, count: 32), argument = [CChar](repeating: 0, count: 32)
+    method_getReturnType(method, &returns, returns.count); method_getArgumentType(method, 2, &argument, argument.count)
+    // A block (@?) is not an object sender, despite sharing the '@' prefix.
+    guard returns[0] == 118 && returns[1] == 0 && argument[0] == 64 && argument[1] == 0 else { return nil } // void action(id sender)
+    return method_getImplementation(method)
+}
+
+/// Target-side authority. Embed INSIDE the application that owns these AppKit controls.
+/// All model/handler changes must run on MainActor and call invalidate BEFORE mutation.
+/// This is deliberately not an AXUIElement/CGEvent proxy for other applications.
+@MainActor public final class WardenDesktopSurface {
+    private struct Binding {
+        let button: NSButton
+        let target: NSObject
+        let selector: Selector
+        let implementation: IMP
+        let identity: String
+    }
+    private struct Capture { let observation: [String: Any]; let fingerprint: String; let boxes: [String: CGRect]; let stamps: [String: String] }
+    private struct Ticket {
+        let revision: String; let stamp: String; let fingerprint: String; let action: String; let target: String
+        let expires: Double; let deadline: UInt64
+    }
+    private let window: NSWindow
+    private let applicationID: String
+    private var bindings: [String: Binding] = [:]
+    private var tickets: [String: Ticket] = [:]
+    private var revision: String
+    private var poisoned = false
+    private var uncertain = false
+    private var committing = false
+    private var lastFingerprint: String?
+    private let now: () -> Double
+    private let uptime: () -> UInt64
+    private var observers: [NSObjectProtocol] = []
+    deinit { for observer in observers { NotificationCenter.default.removeObserver(observer) } }
+
+    public init(window: NSWindow, applicationID: String, now: @escaping () -> Double = { Date().timeIntervalSince1970 * 1000 }, uptime: @escaping () -> UInt64 = { DispatchTime.now().uptimeNanoseconds }) throws {
+        guard !applicationID.isEmpty, applicationID.utf16.count <= 200, !applicationID.unicodeScalars.contains(where: { $0.value < 32 || $0.value == 127 }) else { throw DesktopError.invalid }
+        self.window = window; self.applicationID = applicationID; self.revision = try opaque(); self.now = now; self.uptime = uptime
+        for event in [NSWindow.didMoveNotification, NSWindow.didResizeNotification, NSWindow.willCloseNotification, NSWindow.willMiniaturizeNotification, NSWindow.didMiniaturizeNotification,
+                      NSWindow.willBeginSheetNotification, NSWindow.didEndSheetNotification,
+                      NSWindow.didDeminiaturizeNotification, NSWindow.didChangeScreenNotification, NSWindow.didBecomeKeyNotification, NSWindow.didResignKeyNotification] {
+            observers.append(NotificationCenter.default.addObserver(forName: event, object: window, queue: .main) { [weak self] _ in
+                MainActor.assumeIsolated { if let s = self, !s.committing, !s.uncertain { try? s.invalidate() } }
+            })
+        }
+    }
+
+    /// Only explicit, retained action targets; nil/first-responder routing is not supported.
+    /// Register momentary push buttons whose synchronous handlers do not pump a nested run loop.
+    public func register(id: String, button: NSButton, target: NSObject, selector: Selector) throws {
+        guard !committing, !uncertain else { throw DesktopError.unavailable }
+        let identity = button.accessibilityIdentifier()
+        guard !committing, bindings.count < 64, bindings[id] == nil, id.range(of: "^[A-Za-z0-9_.:-]{1,40}$", options: .regularExpression) != nil,
+              button.window === window, button.target === target, button.action == selector,
+              !identity.isEmpty, identity.utf16.count <= 200, !identity.unicodeScalars.contains(where: { $0.value < 32 || $0.value == 127 }),
+              !bindings.values.contains(where: { $0.identity == identity || $0.button === button }),
+              button.accessibilityRole() == .button,
+              let cell = button.cell as? NSButtonCell, cell.showsStateBy.isEmpty,
+              let implementation = actionImplementation(target, selector) else { throw DesktopError.unsupported }
+        try invalidate()
+        bindings[id] = Binding(button: button, target: target, selector: selector, implementation: implementation, identity: identity)
+    }
+
+    /// Mandatory for invisible model/recipient/handler changes, even A -> B -> A.
+    /// Failure invalidates existing approvals. Does not recover an uncertain effect.
+    public func invalidate() throws {
+        guard !committing, !uncertain else { throw DesktopError.unavailable }
+        poisoned = true; revision = try opaque(); lastFingerprint = nil; poisoned = false
+    }
+
+    private func capture() throws -> Capture {
+        guard !poisoned, !bindings.isEmpty, window.isVisible, !window.isMiniaturized,
+              window.alphaValue.isFinite, window.alphaValue > 0, window.attachedSheet == nil, window.sheets.isEmpty,
+              !NSApp.windows.contains(where: { $0.sheetParent === window }),
+              NSApp.modalWindow == nil || NSApp.modalWindow === window,
+              window.title.utf16.count <= 160, let content = window.contentView else { throw DesktopError.unavailable }
+        let top = NSScreen.screens.first?.frame.maxY ?? 0
+        var elements: [[String: Any]] = [], boxes: [String: CGRect] = [:], stamps: [String: String] = [:], internals: [[String: Any]] = []
+        for id in bindings.keys.sorted() {
+            let b = bindings[id]!, button = b.button
+            guard button.window === window, button.isDescendant(of: content), !button.isHiddenOrHasHiddenAncestor, button.isEnabled,
+                  button.target === b.target, button.action == b.selector, actionImplementation(b.target, b.selector) == b.implementation,
+                  button.accessibilityIdentifier() == b.identity, button.accessibilityRole() == .button,
+                  (button.cell as? NSButtonCell)?.showsStateBy.isEmpty == true else { throw DesktopError.unavailable }
+            guard button.title.utf16.count <= 160 else { throw DesktopError.unavailable }
+            var appearance: [[String: Any]] = [], ancestor: NSView? = button
+            while let view = ancestor {
+                guard appearance.count < 128, view.alphaValue.isFinite, view.alphaValue > 0 else { throw DesktopError.unavailable }
+                appearance.append(["view": String(describing: ObjectIdentifier(view)), "alpha": view.alphaValue])
+                if view === content { break }
+                ancestor = view.superview
+            }
+            let screen = window.convertToScreen(button.convert(button.bounds, to: nil))
+            let box = CGRect(x: screen.minX, y: top - screen.maxY, width: screen.width, height: screen.height)
+            guard [box.minX, box.minY, box.width, box.height].allSatisfy({ $0.isFinite && abs($0) <= 1_000_000 }), box.width > 0, box.height > 0 else { throw DesktopError.unavailable }
+            let bounds: [String: Any] = ["x": box.minX, "y": box.minY, "width": box.width, "height": box.height]
+            elements.append(["index": id, "role": "button", "name": button.title, "accessibilityIdentifier": b.identity, "bounds": bounds])
+            boxes[id] = box
+            // Match flow-guard.ts screenTargetEvidence exactly; conformance is integration-tested.
+            let label = try json([button.title] + Array(repeating: NSNull() as Any, count: 8))
+            let geometry = try "{\"x\":\(json(box.minX)),\"y\":\(json(box.minY)),\"width\":\(json(box.width)),\"height\":\(json(box.height))}"
+            let stampText = try "{\"target\":\(json(id)),\"role\":\"button\",\"reference\":\(json(digest(id))),\"identity\":\(json(digest(b.identity))),\"bounds\":\(geometry),\"label\":\(json(digest(label))),\"application\":\(json(applicationID)),\"titles\":[\(json(digest(String(window.title.trimmingCharacters(in: .whitespacesAndNewlines).prefix(160)))))]}"
+            stamps[id] = digest(stampText)
+            internals.append(["id": id, "object": String(describing: ObjectIdentifier(button)), "target": String(describing: ObjectIdentifier(b.target)),
+                              "selector": NSStringFromSelector(b.selector), "frame": bounds, "title": button.title, "identity": b.identity,
+                              "state": button.state.rawValue, "tag": button.tag, "alternateTitle": button.alternateTitle, "appearance": appearance])
+        }
+        let observation: [String: Any] = ["content": [["type": "text", "text": "Native AppKit controls owned by this application; coordinates are global top-left points, not pixels."]],
+            "structuredContent": ["applicationId": applicationID, "windowTitle": window.title, "elements": elements]]
+        let state: [String: Any] = ["elements": internals, "window": String(describing: ObjectIdentifier(window)), "windowNumber": window.windowNumber,
+                                  "title": window.title, "alpha": window.alphaValue, "modal": NSApp.modalWindow.map { String(describing: ObjectIdentifier($0)) } ?? "",
+                                  "key": window.isKeyWindow, "focus": window.firstResponder.map { String(describing: ObjectIdentifier($0)) } ?? ""]
+        return Capture(observation: observation, fingerprint: digest(try json(state)), boxes: boxes, stamps: stamps)
+    }
+    private func fresh() throws -> Capture {
+        guard !committing else { throw DesktopError.unavailable }
+        do {
+            let view = try capture()
+            if let before = lastFingerprint, before != view.fingerprint { revision = try opaque() }
+            lastFingerprint = view.fingerprint
+            return view
+        } catch {
+            poisoned = true; tickets.removeAll(); throw DesktopError.unavailable
+        }
+    }
+    public func read() throws -> [String: Any] { try fresh().observation }
+    private func resolve(_ action: [String: Any], _ view: Capture) throws -> String {
+        guard exact(action, ["name", "arguments"]), action["name"] as? String == "click", let args = action["arguments"] as? [String: Any] else { throw DesktopError.unsupported }
+        let id: String
+        var requestedPoint: CGPoint?
+        if exact(args, ["index"]), let ref = args["index"] as? String, bindings[ref] != nil { id = ref }
+        else if exact(args, ["x", "y"]), let x = number(args["x"]), let y = number(args["y"]) {
+            let hits = view.boxes.filter { $0.value.contains(CGPoint(x: x, y: y)) }
+            guard hits.count == 1, let ref = hits.first?.key else { throw DesktopError.unsupported }; id = ref
+            requestedPoint = CGPoint(x: x, y: y)
+        } else { throw DesktopError.unsupported }
+        // Bind visible native hit target too; another view in this window must not cover it.
+        let b = bindings[id]!, center = requestedPoint ?? CGPoint(x: view.boxes[id]!.midX, y: view.boxes[id]!.midY)
+        let top = NSScreen.screens.first?.frame.maxY ?? 0
+        let inWindow = window.convertPoint(fromScreen: CGPoint(x: center.x, y: top - center.y))
+        guard let content = window.contentView, let hit = content.hitTest(content.convert(inWindow, from: nil)), hit === b.button || hit.isDescendant(of: b.button) else { throw DesktopError.unavailable }
+        return id
+    }
+    public func prepare(_ params: [String: Any]) throws -> [String: Any] {
+        guard exact(params, ["protocol", "observation", "action"]), params["protocol"] as? String == wardenAtomicProtocol,
+              let observation = params["observation"] as? [String: Any], exact(observation, ["name", "arguments"]), observation["name"] as? String == "screenshot",
+              let args = observation["arguments"] as? [String: Any], args.isEmpty, let action = params["action"] as? [String: Any] else { throw DesktopError.invalid }
+        let view = try fresh(), observedRevision = revision, target = try resolve(action, view)
+        let final = try fresh()
+        guard revision == observedRevision, view.fingerprint == final.fingerprint,
+              view.stamps[target] == final.stamps[target] else { throw DesktopError.unavailable }
+        let actionText = try json(action), time = now(), monotonic = uptime()
+        let (deadline, overflow) = monotonic.addingReportingOverflow(300_000_000_000)
+        guard time.isFinite, time >= 0, time <= 9_007_199_254_440_991, !overflow,
+              revision == observedRevision, !poisoned, !committing else { throw DesktopError.unavailable }
+        tickets = tickets.filter { $0.value.expires > time && $0.value.deadline > monotonic }
+        guard tickets.count < 256 else { throw DesktopError.unavailable }
+        let ticket = try opaque(), expiry = floor(time + 300_000), stamp = view.stamps[target]!
+        tickets[ticket] = Ticket(revision: observedRevision, stamp: stamp, fingerprint: view.fingerprint, action: actionText, target: target, expires: expiry, deadline: deadline)
+        return ["protocol": wardenAtomicProtocol, "ticket": ticket, "revision": revision, "stamp": stamp, "expiresAt": expiry, "observation": view.observation]
+    }
+    public func cancel(_ params: [String: Any]) throws {
+        guard exact(params, ["protocol", "ticket"]), params["protocol"] as? String == wardenAtomicProtocol, let ticket = hex(params["ticket"]) else { throw DesktopError.invalid }
+        tickets.removeValue(forKey: ticket)
+    }
+    public func commit(_ params: [String: Any]) throws -> [String: Any] {
+        guard exact(params, ["protocol", "ticket", "expected", "action"]), params["protocol"] as? String == wardenAtomicProtocol,
+              let ticket = hex(params["ticket"]), let expected = params["expected"] as? [String: Any], exact(expected, ["revision", "stamp"]),
+              let expectedRevision = hex(expected["revision"]), let stamp = hex(expected["stamp"]), let action = params["action"] as? [String: Any] else { throw DesktopError.invalid }
+        func refused(_ reason: String) -> [String: Any] { ["protocol": wardenAtomicProtocol, "status": "refused", "reason": reason] }
+        guard let approved = tickets.removeValue(forKey: ticket) else { return refused("unknown") }
+        guard !poisoned, !committing else { return refused("unavailable") }
+        let admissionTime = now()
+        guard admissionTime < approved.expires, admissionTime >= approved.expires - 300_000, uptime() < approved.deadline else { return refused("expired") }
+        guard expectedRevision == approved.revision, stamp == approved.stamp, try json(action) == approved.action else { return refused("mismatch") }
+        let view: Capture
+        do { view = try fresh() } catch { return refused("unavailable") }
+        guard revision == approved.revision, view.fingerprint == approved.fingerprint, view.stamps[approved.target] == approved.stamp else { return refused("stale") }
+        guard (try? resolve(action, view)) == approved.target, revision == approved.revision, !poisoned,
+              let b = bindings[approved.target] else { return refused("stale") }
+        // hitTest is overridable AppKit code. Do not rely solely on the host's
+        // invalidation callback: visible properties/handler may have changed there.
+        let final: Capture
+        do { final = try fresh() } catch { return refused("unavailable") }
+        guard revision == approved.revision, final.fingerprint == approved.fingerprint,
+              final.stamps[approved.target] == approved.stamp else { return refused("stale") }
+        // Validation itself may take time. Check both clocks at the dispatch boundary.
+        // Allocate the receipt revision before any effect; entropy failure must not
+        // escape as an ordinary unavailable error after a successful handler.
+        let committedRevision = try opaque()
+        let dispatchTime = now()
+        guard dispatchTime < approved.expires, dispatchTime >= approved.expires - 300_000,
+              uptime() < approved.deadline else { return refused("expired") }
+        // Clock providers are injected host callbacks too. No callbacks may run
+        // after this final CAS and before the pinned implementation invocation.
+        guard revision == approved.revision, !poisoned, !committing else { return refused("stale") }
+        // Linearization point in the TARGET APPLICATION's main run loop. No AX RPC,
+        // CGEvent, performClick animation, await, timer or queued coordinate dispatch.
+        committing = true
+        defer { committing = false }
+        uncertain = true; poisoned = true
+        // NSApplication.sendAction is overridable and may reroute/queue or report
+        // success without invoking this method. Call the checked, retained IMP.
+        let invoke = unsafeBitCast(b.implementation, to: NativeAction.self)
+        invoke(b.target, b.selector, b.button)
+        revision = committedRevision; lastFingerprint = nil
+        // A receipt attests local handler dispatch, never remote payment/mail completion.
+        poisoned = false; uncertain = false
+        return ["protocol": wardenAtomicProtocol, "status": "committed", "revisionBefore": approved.revision, "revisionAfter": revision, "stamp": stamp,
+                "result": ["content": [["type": "text", "text": "Native AppKit action dispatched synchronously to the approved button target. External outcomes require reconciliation."]]]]
+    }
+}

package/native/macos/Sources/WardenDesktop/StandardIO.swift

@@ -0,0 +1,139 @@
+import AppKit
+
+/// Bounded NDJSON transport over an exclusive inherited pipe, not a public listener.
+/// Parsing and every surface operation run on the application's main actor.
+@MainActor public final class WardenDesktopStandardIO {
+    private let surface: WardenDesktopSurface
+    private var initialized = false
+    private var stopped = false
+    public init(surface: WardenDesktopSurface) { self.surface = surface }
+    #if WARDEN_DESKTOP_TESTS
+    public var extraRequest: ((String, [String: Any]) throws -> [String: Any]?)?
+    #endif
+    private func send(_ value: [String: Any]) {
+        do {
+            let data = try JSONSerialization.data(withJSONObject: value, options: [.withoutEscapingSlashes, .sortedKeys])
+            guard data.count <= 1_048_576 else { throw DesktopError.invalid }
+            try FileHandle.standardOutput.write(contentsOf: data + Data([10]))
+        } catch { stopped = true; NSApp.terminate(nil) }
+    }
+    public func receive(_ data: Data) {
+        guard !stopped else { return }
+        var id: Any = NSNull()
+        do {
+            let raw = try DesktopJSON.parse(data)
+            guard let msg = raw as? [String: Any], Set(msg.keys).isSubset(of: ["jsonrpc", "id", "method", "params"]), msg["jsonrpc"] as? String == "2.0",
+                  let method = msg["method"] as? String else { throw DesktopError.invalid }
+            if let v = msg["id"] {
+                guard v is String || (v is NSNumber && CFGetTypeID(v as! NSNumber) != CFBooleanGetTypeID() && (v as! NSNumber).doubleValue.isFinite && abs((v as! NSNumber).doubleValue) <= 9_007_199_254_740_991 && (v as! NSNumber).doubleValue.rounded() == (v as! NSNumber).doubleValue) else { throw DesktopError.invalid }
+                id = v
+            }
+            let params: [String: Any]
+            if let p = msg["params"] { guard let object = p as? [String: Any] else { throw DesktopError.invalid }; params = object } else { params = [:] }
+            if method == "notifications/initialized" || method == "notifications/cancelled" { return }
+            if method == "warden/screen/cancel" { try surface.cancel(params); if msg["id"] != nil { send(["jsonrpc": "2.0", "id": id, "result": [:]]) }; return }
+            guard msg["id"] != nil else { return }
+            let result: [String: Any]
+            if method == "initialize" {
+                guard !initialized else { throw DesktopError.invalid }; initialized = true
+                result = ["protocolVersion": "2025-06-18", "capabilities": ["tools": [:]], "serverInfo": ["name": "warden-macos-owned-surface", "version": "1.0.0"]]
+            } else {
+                guard initialized else { throw DesktopError.invalid }
+                let extra: [String: Any]?
+                #if WARDEN_DESKTOP_TESTS
+                extra = try extraRequest?(method, params)
+                #else
+                extra = nil
+                #endif
+                if let extra = extra { result = extra }
+                else if method == "tools/list" {
+                    result = ["tools": [
+                        ["name": "screenshot", "description": "Observe registered native controls in the connected application.", "inputSchema": ["type": "object", "properties": [:], "additionalProperties": false]],
+                        ["name": "click", "description": "Activate a registered native button through an atomic target-side commit.", "inputSchema": ["type": "object", "properties": ["index": ["type": "string"]], "required": ["index"], "additionalProperties": false]],
+                    ]]
+                } else if method == "tools/call" {
+                    guard Set(params.keys).isSubset(of: ["name", "arguments"]), params["name"] as? String == "screenshot" else { throw DesktopError.unsupported }
+                    if let a = params["arguments"] { guard let args = a as? [String: Any], args.isEmpty else { throw DesktopError.invalid } }
+                    result = try surface.read()
+                } else if method == "warden/screen/prepare" { result = try surface.prepare(params) }
+                else if method == "warden/screen/commit" { result = try surface.commit(params) }
+                else if method == "ping" { result = [:] }
+                else { throw DesktopError.unsupported }
+            }
+            send(["jsonrpc": "2.0", "id": id, "result": result])
+        } catch {
+            // No raw UI text, arguments, tickets, paths or arbitrary backend errors in diagnostics.
+            send(["jsonrpc": "2.0", "id": id, "error": ["code": -32041, "message": "Native desktop refused or outcome is uncertain; do not retry automatically."]])
+        }
+    }
+    public func start() {
+        DispatchQueue.global(qos: .userInitiated).async {
+            var buffer = Data()
+            let pending = DispatchSemaphore(value: 32)
+            while true {
+                let chunk = FileHandle.standardInput.availableData
+                if chunk.isEmpty { DispatchQueue.main.async { NSApp.terminate(nil) }; return }
+                for byte in chunk {
+                    if byte == 10 {
+                        let line = buffer; buffer.removeAll(keepingCapacity: true)
+                        if !line.isEmpty { pending.wait(); DispatchQueue.main.async { defer { pending.signal() }; self.receive(line) } }
+                    } else {
+                        buffer.append(byte)
+                        if buffer.count > 65_536 { DispatchQueue.main.async { NSApp.terminate(nil) }; return }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Audit duplicate JSON keys before Foundation parsing (including escaped aliases).
+/// Depth and wire limits apply before recursively constructing a Foundation object.
+public enum DesktopJSON {
+    public static func parse(_ data: Data) throws -> Any {
+        guard data.count <= 65_536, String(data: data, encoding: .utf8) != nil else { throw DesktopError.invalid }
+        var scan = Scanner(bytes: Array(data)); try scan.value(0); scan.whitespace()
+        guard scan.offset == data.count else { throw DesktopError.invalid }
+        return try JSONSerialization.jsonObject(with: data, options: [.fragmentsAllowed])
+    }
+    private struct Scanner {
+        let bytes: [UInt8]; var offset = 0
+        mutating func whitespace() { while offset < bytes.count && [9, 10, 13, 32].contains(bytes[offset]) { offset += 1 } }
+        mutating func take(_ b: UInt8) throws { whitespace(); guard offset < bytes.count, bytes[offset] == b else { throw DesktopError.invalid }; offset += 1 }
+        mutating func string() throws -> String {
+            try take(34); let start = offset - 1
+            while offset < bytes.count {
+                let b = bytes[offset]; offset += 1
+                if b == 92 { guard offset < bytes.count else { throw DesktopError.invalid }; offset += 1 }
+                else if b == 34 {
+                    guard let text = try JSONSerialization.jsonObject(with: Data(bytes[start..<offset]), options: [.fragmentsAllowed]) as? String else { throw DesktopError.invalid }; return text
+                }
+            }
+            throw DesktopError.invalid
+        }
+        mutating func value(_ depth: Int) throws {
+            guard depth <= 32 else { throw DesktopError.invalid }; whitespace(); guard offset < bytes.count else { throw DesktopError.invalid }
+            switch bytes[offset] {
+            case 123:
+                offset += 1; whitespace(); if offset < bytes.count && bytes[offset] == 125 { offset += 1; return }
+                var keys = Set<String>()
+                while true {
+                    let key = try string(); guard keys.insert(key).inserted else { throw DesktopError.invalid }
+                    try take(58); try value(depth + 1); whitespace(); guard offset < bytes.count else { throw DesktopError.invalid }
+                    if bytes[offset] == 125 { offset += 1; return }; try take(44)
+                }
+            case 91:
+                offset += 1; whitespace(); if offset < bytes.count && bytes[offset] == 93 { offset += 1; return }
+                while true {
+                    try value(depth + 1); whitespace(); guard offset < bytes.count else { throw DesktopError.invalid }
+                    if bytes[offset] == 93 { offset += 1; return }; try take(44)
+                }
+            case 34: _ = try string()
+            default:
+                let start = offset
+                while offset < bytes.count && ![9, 10, 13, 32, 44, 93, 125].contains(bytes[offset]) { offset += 1 }
+                guard offset > start else { throw DesktopError.invalid }
+            }
+        }
+    }
+}

package/native/macos/Sources/WardenDesktopHost/Main.swift

@@ -0,0 +1,211 @@
+import AppKit
+#if canImport(WardenDesktop)
+import WardenDesktop
+#endif
+
+#if WARDEN_DESKTOP_TESTS
+@MainActor final class TestApplication: NSApplication {
+    var interceptActions = false
+    var interceptedActions = 0
+    override func sendAction(_ action: Selector, to target: Any?, from sender: Any?) -> Bool {
+        if interceptActions { interceptedActions += 1; return true }
+        return super.sendAction(action, to: target, from: sender)
+    }
+}
+@MainActor final class RaceButton: NSButton {
+    var onHit: (() -> Void)?
+    override func hitTest(_ point: NSPoint) -> NSView? { onHit?(); return super.hitTest(point) }
+}
+#endif
+
+@MainActor final class DemoOwner: NSObject {
+    var count = 0
+    var buttons: [NSButton] = []
+    var window: NSWindow!
+    var surface: WardenDesktopSurface!
+    var clockOffset = 0.0
+    var uptimeOffset: UInt64 = 0
+    #if WARDEN_DESKTOP_TESTS
+    var clockReads = 0
+    var invalidateOnClockRead = 0
+    var clockRaceTriggered = false
+    var auxiliaryWindows: [NSWindow] = []
+    var nestedCommit: [String: Any]?
+    var reentrantRefused = false
+    #endif
+    var raceBeforeCommit = false
+    var hitRaceTriggered = false
+    @objc func pressed(_ sender: NSButton) {
+        precondition(Thread.isMainThread)
+        count += 1
+        #if WARDEN_DESKTOP_TESTS
+        if let params = nestedCommit {
+            nestedCommit = nil
+            let receipt = try? surface.commit(params)
+            var readRefused = false, invalidateRefused = false
+            do { _ = try surface.read() } catch { readRefused = true }
+            do { try surface.invalidate() } catch { invalidateRefused = true }
+            reentrantRefused = receipt?["status"] as? String == "refused" && readRefused && invalidateRefused
+        }
+        #endif
+        sender.title = "Pressed \(count)"
+    }
+    @objc func alternate(_ sender: NSButton) { count += 100 }
+    #if WARDEN_DESKTOP_TESTS
+    @objc func invalidAction(_ sender: NSButton) -> String { "not a void action" }
+    @objc func blockAction(_ sender: @convention(block) () -> Void) { count += 1000 }
+    #endif
+    func monotonicClock() -> UInt64 {
+        #if WARDEN_DESKTOP_TESTS
+        if invalidateOnClockRead > 0 {
+            clockReads += 1
+            if clockReads == invalidateOnClockRead {
+                clockRaceTriggered = true
+                try? surface.invalidate(); buttons[0].tag += 1
+            }
+        }
+        #endif
+        return DispatchTime.now().uptimeNanoseconds + uptimeOffset
+    }
+    func start() throws {
+        window = NSWindow(contentRect: NSRect(x: 40, y: 80, width: 340, height: 160), styleMask: [.titled, .closable], backing: .buffered, defer: false)
+        window.title = "WARDEN native test — local only"
+        window.isReleasedWhenClosed = false
+        window.isRestorable = false
+        #if WARDEN_DESKTOP_TESTS
+        let button = RaceButton(title: "Local action", target: self, action: #selector(pressed(_:)))
+        #else
+        let button = NSButton(title: "Local action", target: self, action: #selector(pressed(_:)))
+        #endif
+        button.setAccessibilityElement(true); button.setAccessibilityRole(.button)
+        button.setButtonType(.momentaryPushIn); button.setAccessibilityIdentifier("warden.demo.local-action")
+        button.frame = NSRect(x: 30, y: 55, width: 180, height: 36)
+        window.contentView!.addSubview(button); buttons = [button]
+        window.orderFront(nil) // Never activate another app or generate global input.
+        surface = try WardenDesktopSurface(window: window, applicationID: "dev.warden.macos.demo", now: { [weak self] in Date().timeIntervalSince1970 * 1000 + (self?.clockOffset ?? 0) }, uptime: { [weak self] in self?.monotonicClock() ?? DispatchTime.now().uptimeNanoseconds })
+        try surface.register(id: "3", button: button, target: self, selector: #selector(pressed(_:)))
+    }
+    #if WARDEN_DESKTOP_TESTS
+    func presentSheet() -> [String: Any] {
+        let sheet = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 200, height: 80), styleMask: [.titled], backing: .buffered, defer: false)
+        sheet.isReleasedWhenClosed = false; sheet.isRestorable = false
+        auxiliaryWindows.append(sheet); window.beginSheet(sheet)
+        return ["sheets": window.sheets.count, "attached": window.attachedSheet != nil, "logicalParent": sheet.sheetParent != nil, "knownSheet": NSApp.windows.contains(where: { $0 === sheet })]
+    }
+    func testRequest(_ method: String, _ params: [String: Any]) throws -> [String: Any]? {
+        if method == "test/clock-race" {
+            clockReads = 0; invalidateOnClockRead = params["at"] as? Int ?? 2
+            return [:]
+        }
+        if method == "test/clock-stats" { return ["triggered": clockRaceTriggered] }
+        if method == "test/intercept-dispatch" { (NSApp as! TestApplication).interceptActions = true; return [:] }
+        if method == "test/dispatch-stats" { return ["intercepted": (NSApp as! TestApplication).interceptedActions] }
+        if method == "test/arm-reentrant" { nestedCommit = params; return [:] }
+        if method == "test/invalid-registration" {
+            let button = NSButton(title: "Not registered", target: self, action: #selector(invalidAction(_:)))
+            if params["kind"] as? String == "block" { button.action = #selector(blockAction(_:)) }
+            button.setAccessibilityElement(true); button.setAccessibilityRole(.button); button.setButtonType(.momentaryPushIn)
+            button.setAccessibilityIdentifier("warden.demo.invalid-signature"); button.frame = NSRect(x: 230, y: 10, width: 80, height: 30); window.contentView!.addSubview(button)
+            defer { button.removeFromSuperview() }
+            do { try surface.register(id: "4", button: button, target: self, selector: button.action!); return ["refused": false] }
+            catch { return ["refused": true] }
+        }
+        if method == "warden/screen/commit" && raceBeforeCommit { try surface.invalidate(); raceBeforeCommit = false; return try surface.commit(params) }
+        if method == "test/stats" { return ["count": count, "mainThread": Thread.isMainThread, "windowVisible": window.isVisible, "hitRaceTriggered": hitRaceTriggered, "reentrantRefused": reentrantRefused, "pid": ProcessInfo.processInfo.processIdentifier] }
+        guard method == "test/change", let kind = params["kind"] as? String else { return nil }
+        if kind == "race-before-commit" { raceBeforeCommit = true; return [:] }
+        if kind == "monotonic-expiry" { uptimeOffset += 300_001_000_000; return [:] }
+        if kind == "expiry" { clockOffset += 300_001; return [:] }
+        if kind == "rollback" { clockOffset -= 1000; return [:] }
+        if kind == "untracked-sheet" { return presentSheet() }
+        if kind == "untracked-ancestor-alpha" { window.contentView!.alphaValue = 0; return [:] }
+        if kind == "untracked-partial-alpha" { buttons[0].alphaValue = 0.5; return [:] }
+        if kind == "untracked-implementation" {
+            guard let a = class_getInstanceMethod(DemoOwner.self, #selector(pressed(_:))), let b = class_getInstanceMethod(DemoOwner.self, #selector(alternate(_:))) else { throw DesktopError.invalid }
+            method_exchangeImplementations(a, b); return [:]
+        }
+        if kind == "untracked-button-alpha" { buttons[0].alphaValue = 0; return [:] }
+        if kind == "untracked-window-alpha" { window.alphaValue = 0; return [:] }
+        if kind == "untracked-title" { buttons[0].title = "Untracked change"; return [:] }
+        if kind.hasPrefix("hit-untracked-") {
+            (buttons[0] as! RaceButton).onHit = { [weak self] in
+                guard let s = self, !s.hitRaceTriggered else { return }
+                s.hitRaceTriggered = true
+                switch kind {
+                case "hit-untracked-sheet": _ = s.presentSheet()
+                case "hit-untracked-button-alpha": s.buttons[0].alphaValue = 0
+                case "hit-untracked-window-alpha": s.window.alphaValue = 0
+                case "hit-untracked-handler": s.buttons[0].action = #selector(DemoOwner.alternate(_:))
+                case "hit-untracked-title": s.buttons[0].title = "Different outcome"
+                case "hit-untracked-disabled": s.buttons[0].isEnabled = false
+                case "hit-untracked-bounds": s.buttons[0].frame.origin.x += 5
+                case "hit-untracked-expiry": s.clockOffset += 300_001
+                case "hit-untracked-monotonic-expiry": s.uptimeOffset += 300_001_000_000
+                default: break
+                }
+            }
+            return [:]
+        }
+        if kind == "hit-test-mutation" {
+            (buttons[0] as! RaceButton).onHit = { [weak self] in
+                guard let s = self, !s.hitRaceTriggered else { return }
+                s.hitRaceTriggered = true; try? s.surface.invalidate(); s.buttons[0].tag += 1
+            }
+            return [:]
+        }
+        if kind == "replace-object" {
+            try surface.invalidate()
+            let old = buttons[0], replacement = NSButton(title: old.title, target: self, action: #selector(pressed(_:)))
+            replacement.setAccessibilityElement(true); replacement.setAccessibilityRole(.button)
+            replacement.setButtonType(.momentaryPushIn); replacement.frame = old.frame; replacement.setAccessibilityIdentifier(old.accessibilityIdentifier())
+            old.removeFromSuperview(); window.contentView!.addSubview(replacement); return [:]
+        }
+        try surface.invalidate() // BEFORE every controlled mutation, including ABA/semantics.
+        switch kind {
+        case "aba", "semantic": break
+        case "title": buttons[0].title = "Other action"
+        case "unicode": buttons[0].title = "Отправить / 发送 / Envoyer"; window.title = "WARDEN — проверка 发送"
+        case "identity": buttons[0].setAccessibilityIdentifier("warden.demo.changed")
+        case "handler": buttons[0].action = #selector(alternate(_:))
+        case "bounds": buttons[0].frame.origin.x += 5
+        case "window": window.title = "Changed native window"
+        case "disabled": buttons[0].isEnabled = false
+        case "hidden": buttons[0].isHidden = true
+        case "close": window.orderOut(nil)
+        case "overlay":
+            let overlay = NSView(frame: buttons[0].frame); window.contentView!.addSubview(overlay, positioned: .above, relativeTo: buttons[0])
+        default: throw DesktopError.invalid
+        }
+        return [:]
+    }
+    #endif
+}
+
+@main struct WardenDesktopHost {
+    @MainActor static func main() {
+        // A native reference application, not an agent injected into unrelated applications.
+        // The reusable library must be embedded by those applications themselves.
+        guard Array(CommandLine.arguments.dropFirst()) == ["--demo"] else {
+            FileHandle.standardError.write(Data("Usage: warden-desktop --demo (owned native window only; no external AX/CGEvent dispatch)\n".utf8)); exit(2)
+        }
+        #if WARDEN_DESKTOP_TESTS
+        _ = TestApplication.shared
+        precondition(NSApp is TestApplication)
+        #else
+        _ = NSApplication.shared
+        #endif
+        NSApp.setActivationPolicy(.accessory)
+        let owner = DemoOwner()
+        do {
+            try owner.start()
+            let io = WardenDesktopStandardIO(surface: owner.surface)
+            #if WARDEN_DESKTOP_TESTS
+            io.extraRequest = { method, params in try owner.testRequest(method, params) }
+            #endif
+            io.start()
+            withExtendedLifetime([owner, io] as [AnyObject]) { NSApp.run() }
+        } catch {
+            FileHandle.standardError.write(Data("Native desktop unavailable; no action was run.\n".utf8)); exit(3)
+        }
+    }
+}