@stim-cli/server 1.14.0 → 1.16.0

package/dist/stim-frames/OwnedAppWindowReader.swift

@@ -0,0 +1,87 @@
+import ApplicationServices
+import CoreGraphics
+
+/// Reads one process's windows for `OwnedAppWindows`, from CoreGraphics and Accessibility.
+public enum OwnedAppWindowReader {
+  public struct Accessible {
+    public var windows: [OwnedAppWindows.Accessible]
+    public var elements: [AXUIElement]
+    /// Whether any window of the app is modal, or does not say.
+    public var modal: Bool
+  }
+
+  /// The process's on-screen windows, front to back; nil when the inventory or a window's metadata is unavailable.
+  public static func screen(pid: pid_t) -> [OwnedAppWindows.Screen]? {
+    guard
+      let entries = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID)
+        as? [[String: Any]]
+    else { return nil }
+    var screen: [OwnedAppWindows.Screen] = []
+    for entry in entries where entry[kCGWindowOwnerPID as String] as? Int == Int(pid) {
+      guard let id = entry[kCGWindowNumber as String] as? UInt32, let layer = entry[kCGWindowLayer as String] as? Int,
+        let bounds = entry[kCGWindowBounds as String] as? [String: Any],
+        let frame = CGRect(dictionaryRepresentation: bounds as CFDictionary)
+      else { return nil }
+      screen.append(.init(id: id, layer: layer, frame: frame, title: entry[kCGWindowName as String] as? String ?? ""))
+    }
+    return screen
+  }
+
+  /// The process's standard windows, front to back; nil when Accessibility does not list its windows.
+  public static func accessible(pid: pid_t) -> Accessible? {
+    let application = AXUIElementCreateApplication(pid)
+    var value: CFTypeRef?
+    guard AXUIElementCopyAttributeValue(application, kAXWindowsAttribute as CFString, &value) == .success,
+      let owned = value as? [AXUIElement]
+    else { return nil }
+    var main: CFTypeRef?
+    var focused: CFTypeRef?
+    _ = AXUIElementCopyAttributeValue(application, kAXMainWindowAttribute as CFString, &main)
+    _ = AXUIElementCopyAttributeValue(application, kAXFocusedWindowAttribute as CFString, &focused)
+    var result = Accessible(windows: [], elements: [], modal: false)
+    for own in owned {
+      var modal: CFTypeRef?
+      if AXUIElementCopyAttributeValue(own, kAXModalAttribute as CFString, &modal) != .success || modal as? Bool != false {
+        result.modal = true
+      }
+      var subrole: CFTypeRef?
+      guard AXUIElementCopyAttributeValue(own, kAXSubroleAttribute as CFString, &subrole) == .success,
+        subrole as? String == kAXStandardWindowSubrole, let frame = frame(own)
+      else { continue }
+      var title: CFTypeRef?
+      _ = AXUIElementCopyAttributeValue(own, kAXTitleAttribute as CFString, &title)
+      result.windows.append(
+        .init(
+          frame: frame, title: title as? String ?? "", main: main.map { CFEqual($0, own) } ?? false,
+          focused: focused.map { CFEqual($0, own) } ?? false))
+      result.elements.append(own)
+    }
+    return result
+  }
+
+  /// The windows viewing shows and follows: by Accessibility when this process is trusted, else only an app whose one
+  /// window contains the others. Throws when an inventory is unavailable; nil when the app shows no window.
+  public static func selection(pid: pid_t) throws -> OwnedAppWindows.Selection? {
+    guard let screen = screen(pid: pid) else { throw Unavailable() }
+    guard AXIsProcessTrusted() else { return OwnedAppWindows.single(screen: screen) }
+    guard let accessible = accessible(pid: pid) else { throw Unavailable() }
+    return OwnedAppWindows.select(screen: screen, accessible: accessible.windows)
+  }
+
+  public struct Unavailable: Error {}
+
+  public static func frame(_ element: AXUIElement) -> CGRect? {
+    var positionValue: CFTypeRef?
+    var sizeValue: CFTypeRef?
+    var position = CGPoint.zero
+    var size = CGSize.zero
+    guard AXUIElementCopyAttributeValue(element, kAXPositionAttribute as CFString, &positionValue) == .success,
+      AXUIElementCopyAttributeValue(element, kAXSizeAttribute as CFString, &sizeValue) == .success,
+      let positionValue, let sizeValue, CFGetTypeID(positionValue) == AXValueGetTypeID(),
+      CFGetTypeID(sizeValue) == AXValueGetTypeID(),
+      AXValueGetValue(unsafeDowncast(positionValue, to: AXValue.self), .cgPoint, &position),
+      AXValueGetValue(unsafeDowncast(sizeValue, to: AXValue.self), .cgSize, &size)
+    else { return nil }
+    return CGRect(origin: position, size: size)
+  }
+}

package/dist/stim-frames/OwnedAppWindows.swift

@@ -0,0 +1,108 @@
+import CoreGraphics
+
+/// The windows of an owned macOS app that viewing and Control can show, and the one they follow.
+public enum OwnedAppWindows {
+  /// An on-screen window of the app's process, from `CGWindowListCopyWindowInfo`, front to back.
+  public struct Screen: Equatable, Sendable {
+    public var id: UInt32
+    public var layer: Int
+    public var frame: CGRect
+    public var title: String
+
+    public init(id: UInt32, layer: Int, frame: CGRect, title: String) {
+      self.id = id
+      self.layer = layer
+      self.frame = frame
+      self.title = title
+    }
+  }
+
+  /// A standard window of the app from Accessibility (`kAXWindowsAttribute`), front to back.
+  public struct Accessible: Equatable, Sendable {
+    public var frame: CGRect
+    public var title: String
+    public var main: Bool
+    public var focused: Bool
+
+    public init(frame: CGRect, title: String, main: Bool, focused: Bool) {
+      self.frame = frame
+      self.title = title
+      self.main = main
+      self.focused = focused
+    }
+  }
+
+  /// `accessible` is the index of the window in the Accessibility list it was matched from, or nil without one.
+  public struct Window: Equatable, Sendable {
+    public var id: UInt32
+    public var title: String
+    public var frame: CGRect
+    public var accessible: Int?
+
+    public init(id: UInt32, title: String, frame: CGRect, accessible: Int?) {
+      self.id = id
+      self.title = title
+      self.frame = frame
+      self.accessible = accessible
+    }
+  }
+
+  public struct Selection: Equatable, Sendable {
+    public var current: Window
+    public var windows: [Window]
+
+    public init(current: Window, windows: [Window]) {
+      self.current = current
+      self.windows = windows
+    }
+  }
+
+  /// Matches each standard window to the first unused on-screen layer-0 window with the same frame and title, so
+  /// identical windows pair in their front-to-back order, then pairs the rest by frame alone, as the two inventories
+  /// can disagree on a title that just changed. A standard window without an on-screen match (minimized, on another
+  /// Space) is left out. The current window is the app's main window, else its focused one, else the frontmost.
+  public static func select(screen: [Screen], accessible: [Accessible]) -> Selection? {
+    var unused = screen.filter { $0.layer == 0 }
+    var matched: [Int: Screen] = [:]
+    for sameTitle in [true, false] {
+      for (index, window) in accessible.enumerated() where matched[index] == nil {
+        guard
+          let match = unused.firstIndex(where: { $0.frame == window.frame && (!sameTitle || $0.title == window.title) })
+        else { continue }
+        matched[index] = unused.remove(at: match)
+      }
+    }
+    let windows = accessible.indices.compactMap { index in
+      matched[index].map { Window(id: $0.id, title: accessible[index].title, frame: $0.frame, accessible: index) }
+    }
+    let current =
+      windows.first { accessible[$0.accessible!].main } ?? windows.first { accessible[$0.accessible!].focused }
+      ?? windows.first
+    return current.map { Selection(current: $0, windows: windows) }
+  }
+
+  /// The selection with `pinned` as its current window while that window is still on screen; nil `pinned` in the
+  /// result means the pin is gone and capture follows the front window again. A pinned window that the two
+  /// inventories briefly disagree on stays pinned from its on-screen entry, without an Accessibility match.
+  public static func pin(_ selection: Selection, to pinned: UInt32?, screen: [Screen]) -> (
+    selection: Selection, pinned: UInt32?
+  ) {
+    guard let pinned else { return (selection, nil) }
+    if let window = selection.windows.first(where: { $0.id == pinned }) {
+      return (Selection(current: window, windows: selection.windows), pinned)
+    }
+    guard let shown = screen.first(where: { $0.id == pinned && $0.layer == 0 }) else { return (selection, nil) }
+    let window = Window(id: shown.id, title: shown.title, frame: shown.frame, accessible: nil)
+    return (Selection(current: window, windows: selection.windows + [window]), pinned)
+  }
+
+  /// Without Accessibility, the one layer-0 window that contains every other one, such as a main window with its
+  /// sheets; nil when the app shows disjoint windows.
+  public static func single(screen: [Screen]) -> Selection? {
+    let windows = screen.filter { $0.layer == 0 }
+    let containers = windows.filter { candidate in windows.allSatisfy { candidate.frame.contains($0.frame) } }
+    guard containers.count == 1, let only = containers.first else { return nil }
+    let window = Window(id: only.id, title: only.title, frame: only.frame, accessible: nil)
+    return Selection(current: window, windows: [window])
+  }
+}

package/dist/stim-frames/PhoneSource.swift

@@ -0,0 +1,315 @@
+import AVFoundation
+import CoreImage
+import CoreMediaIO
+import Foundation
+import IOKit
+
+/// The screen of a USB-cabled iPhone, view only. macOS lists a cabled iPhone as an external muxed capture device,
+/// the one QuickTime's New Movie Recording shows, only after a process sets
+/// `kCMIOHardwarePropertyAllowScreenCaptureDevices`, and the device appears some seconds later. Capture runs only
+/// while a subscriber asks for frames.
+///
+/// The capture device's unique ID is a random UUID (macOS 27), and none of its CoreMediaIO properties names the
+/// UDID. The USB device does: its serial number is the UDID without dashes. So the UDID must be cabled, and the
+/// capture device is the iOS one named `name`, or the only one when there is no name and one iPhone is cabled.
+/// Screens appear one by one, so with several iPhones cabled it waits for all of them; any other case refuses
+/// rather than guess.
+final class PhoneSource: NSObject, AVCaptureVideoDataOutputSampleBufferDelegate {
+  static let searchSeconds = 15.0
+  static let retrySeconds = 2.0
+  static let starvedSeconds = 2.0
+
+  let udid: String
+  let name: String?
+  private var serial: String { udid.replacingOccurrences(of: "-", with: "").uppercased() }
+  let queue = DispatchQueue(label: "stim.frames.phone")
+  private let captureQueue = DispatchQueue(label: "stim.frames.phone-capture")
+  private var pacer: Pacer!
+  private let video = videoEncoder()
+  private let jpegGate = JpegGate()
+  private var config = Config(fps: 0)
+  private var device: AVCaptureDevice?
+  private var session: AVCaptureSession?
+  private var authorized = false
+  private var latest: CVPixelBuffer?
+  private var frameAt = Date.distantPast
+  private var watchdog: DispatchSourceTimer?
+  private var retrying = false
+  private var failure: String?
+  private var reportedStall: String??
+  private var observers: [NSObjectProtocol] = []
+  private var watches: [NSKeyValueObservation] = []
+
+  init(udid: String, name: String?) {
+    self.udid = udid
+    self.name = name
+    super.init()
+    pacer = Pacer { [unowned self] config in
+      guard let pixels = self.queue.sync(execute: { self.latest }) else { return }
+      self.render(pixels, config: config)
+    }
+  }
+
+  /// The serial numbers of the iOS devices on USB, which are their UDIDs without dashes. The registry is walked
+  /// instead of matched, because macOS leaves a cabled iPhone's USB device unregistered.
+  static func cabledSerials() -> Set<String> {
+    var iterator: io_iterator_t = 0
+    guard
+      IORegistryEntryCreateIterator(
+        IORegistryGetRootEntry(kIOMainPortDefault), "IOUSB", IOOptionBits(kIORegistryIterateRecursively), &iterator)
+        == KERN_SUCCESS
+    else { return [] }
+    defer { IOObjectRelease(iterator) }
+    var serials: Set<String> = []
+    while case let entry = IOIteratorNext(iterator), entry != 0 {
+      defer { IOObjectRelease(entry) }
+      let property = { (key: String) in
+        IORegistryEntryCreateCFProperty(entry, key as CFString, kCFAllocatorDefault, 0)?.takeRetainedValue()
+      }
+      guard property("UsbAppleDeviceECID") != nil, let serial = property("USB Serial Number") as? String else { continue }
+      serials.insert(serial.uppercased())
+    }
+    return serials
+  }
+
+  func start() {
+    var address = CMIOObjectPropertyAddress(
+      mSelector: CMIOObjectPropertySelector(kCMIOHardwarePropertyAllowScreenCaptureDevices),
+      mScope: CMIOObjectPropertyScope(kCMIOObjectPropertyScopeGlobal),
+      mElement: CMIOObjectPropertyElement(kCMIOObjectPropertyElementMain))
+    var allow: UInt32 = 1
+    let status = CMIOObjectSetPropertyData(
+      CMIOObjectID(kCMIOObjectSystemObject), &address, 0, nil, UInt32(MemoryLayout<UInt32>.size), &allow)
+    guard status == 0 else { fail("macOS refused to list iPhone screens as capture devices (CoreMediaIO \(status)).") }
+    let center = NotificationCenter.default
+    observers.append(
+      center.addObserver(forName: AVCaptureDevice.wasConnectedNotification, object: nil, queue: nil) { [weak self] _ in
+        self?.queue.async { self?.find(until: nil) }
+      })
+    observers.append(
+      center.addObserver(forName: AVCaptureSession.runtimeErrorNotification, object: nil, queue: nil) {
+        [weak self] note in
+        let error = note.userInfo?[AVCaptureSessionErrorKey] as? Error
+        self?.queue.async {
+          guard let self, let session = self.session, session === note.object as? AVCaptureSession else { return }
+          self.failure = "Capture of the iPhone \(self.udid) stopped (\(error?.localizedDescription ?? "unknown error"))."
+          self.close()
+          self.retry()
+        }
+      })
+    observers.append(
+      center.addObserver(forName: AVCaptureDevice.wasDisconnectedNotification, object: nil, queue: nil) {
+        [weak self] note in
+        guard let gone = note.object as? AVCaptureDevice else { return }
+        self?.queue.async {
+          guard let self, let device = self.device, device.uniqueID == gone.uniqueID else { return }
+          fail("The iPhone \(self.udid) was disconnected from this Mac.")
+        }
+      })
+    find(until: Date().addingTimeInterval(Self.searchSeconds))
+  }
+
+  private func find(until deadline: Date?) {
+    guard device == nil else { return }
+    let cabled = Self.cabledSerials()
+    guard cabled.contains(serial) else {
+      fail(
+        "The iPhone \(udid) is not cabled to this Mac. Stim shows a physical iPhone's screen only over a USB cable.")
+    }
+    let screens = AVCaptureDevice.DiscoverySession(deviceTypes: [.external], mediaType: .muxed, position: .unspecified)
+      .devices.filter { $0.modelID == "iOS Device" }
+    if cabled.count > 1 && name == nil {
+      fail("Several iPhones are cabled to this Mac, and Stim has no name to tell \(udid) apart from them.")
+    }
+    let named = name.map { name in screens.filter { $0.localizedName == name } } ?? screens
+    let listed = screens.count >= cabled.count
+    if listed && named.count > 1 {
+      fail(
+        "Several cabled iPhones are named \(name ?? "alike"), so Stim cannot tell which one is \(udid). Rename one in "
+          + "Settings > General > About > Name.")
+    }
+    guard listed, named.count == 1, let found = named.first else {
+      guard let deadline else { return }
+      if Date() > deadline {
+        if screens.isEmpty {
+          fail("macOS shows no screen for the iPhone \(udid). Unlock it, and tap Trust if it asks to trust this Mac.")
+        }
+        if !listed {
+          fail(
+            "Not every cabled iPhone shows its screen yet, so Stim cannot tell \(udid) apart from them. Unlock each "
+              + "one, and tap Trust if it asks to trust this Mac.")
+        }
+        fail(
+          "No cabled iPhone's screen is named \(name ?? "") as the lease of \(udid) records. If it was renamed, run "
+            + "stim device lock ios \(udid) again.")
+      }
+      queue.asyncAfter(deadline: .now() + 1) { self.find(until: deadline) }
+      return
+    }
+    device = found
+    for key in [\AVCaptureDevice.isSuspended, \AVCaptureDevice.isInUseByAnotherApplication] {
+      watches.append(found.observe(key) { [weak self] _, _ in self?.queue.async { self?.reportStall() } })
+    }
+    authorize()
+  }
+
+  /// The first capture asks the user for Camera access, which macOS attributes to the app that started stim-server.
+  private func authorize() {
+    switch AVCaptureDevice.authorizationStatus(for: .video) {
+    case .authorized:
+      authorized = true
+      failure = nil
+      reportStall()
+      apply()
+    case .notDetermined:
+      failure = "macOS is asking on the Mac whether the app that runs stim-server may use the camera."
+      reportStall()
+      AVCaptureDevice.requestAccess(for: .video) { granted in
+        self.queue.async {
+          if !granted { self.denied() }
+          self.authorize()
+        }
+      }
+    default:
+      denied()
+    }
+  }
+
+  /// macOS denies without a prompt when the responsible app has no camera usage description, or runs with the
+  /// hardened runtime and lacks the camera entitlement, such as a bare `node`.
+  private func denied() -> Never {
+    fail(
+      "macOS denied Camera access, which capturing an iPhone screen needs. Run stim-server from Stim, and allow Stim "
+        + "in System Settings > Privacy & Security > Camera.")
+  }
+
+  func configure(_ config: Config) {
+    video.configure(enabled: config.video, maxEdge: config.maxEdge, fps: Int(config.fps), bitrate: config.bitrate)
+    queue.async {
+      self.config = config
+      self.pacer.queue.async {
+        self.pacer.config = config
+        self.pacer.changed()
+      }
+      self.apply()
+    }
+  }
+
+  func keyframe() {
+    video.requestKeyframe()
+    pacer.changed()
+  }
+
+  private func apply() {
+    let wanted = config.fps > 0 && (config.jpeg || config.video)
+    if wanted, session == nil, authorized, let device { open(device) }
+    if !wanted, session != nil {
+      close()
+      latest = nil
+    }
+  }
+
+  private func close() {
+    guard let session else { return }
+    self.session = nil
+    watchdog?.cancel()
+    watchdog = nil
+    captureQueue.async { session.stopRunning() }
+  }
+
+  private func open(_ device: AVCaptureDevice) {
+    let session = AVCaptureSession()
+    do {
+      let input = try AVCaptureDeviceInput(device: device)
+      for port in input.ports where port.mediaType != .video { port.isEnabled = false }
+      guard session.canAddInput(input) else { throw CaptureError.refused }
+      session.addInput(input)
+    } catch {
+      failure = "The iPhone \(udid) could not be opened for capture (\(error.localizedDescription))."
+      return retry()
+    }
+    let output = AVCaptureVideoDataOutput()
+    output.alwaysDiscardsLateVideoFrames = true
+    output.videoSettings = [kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32BGRA]
+    output.setSampleBufferDelegate(self, queue: captureQueue)
+    guard session.canAddOutput(output) else {
+      failure = "The iPhone \(udid) offers no video output macOS can read."
+      return retry()
+    }
+    session.addOutput(output)
+    self.session = session
+    failure = nil
+    frameAt = Date()
+    reportStall()
+    let watchdog = DispatchSource.makeTimerSource(queue: queue)
+    watchdog.schedule(deadline: .now() + 1, repeating: 1)
+    watchdog.setEventHandler { [weak self] in
+      guard let self else { return }
+      if !Self.cabledSerials().contains(self.serial) { fail("The iPhone \(self.udid) was disconnected from this Mac.") }
+      self.reportStall()
+    }
+    watchdog.resume()
+    self.watchdog = watchdog
+    captureQueue.async { session.startRunning() }
+  }
+
+  private func retry() {
+    if !Self.cabledSerials().contains(serial) { fail("The iPhone \(udid) was disconnected from this Mac.") }
+    reportStall()
+    guard !retrying else { return }
+    retrying = true
+    queue.asyncAfter(deadline: .now() + Self.retrySeconds) {
+      self.retrying = false
+      self.apply()
+    }
+  }
+
+  /// A failed open, or frames that stopped, are stalls: the last frame stays on screen with the reason, and frames
+  /// resume when the reason clears. A cabled iPhone sends frames continuously, so a gap names its cause when macOS
+  /// reports one. Another app capturing the iPhone alone is no stall, because several processes can capture it.
+  private func reportStall() {
+    let starved = session != nil && Date().timeIntervalSince(frameAt) > Self.starvedSeconds
+    let stall: String?
+    if starved, let device, device.isSuspended {
+      stall = "The iPhone is locked. Unlock it to see its screen."
+    } else if starved, let device, device.isInUseByAnotherApplication {
+      stall = "Another app, such as QuickTime Player, is capturing this iPhone."
+    } else if starved {
+      stall = "The iPhone stopped sending its screen."
+    } else {
+      stall = failure
+    }
+    guard reportedStall != .some(stall) else { return }
+    reportedStall = .some(stall)
+    Output.notice(["stalled": stall.map { $0 as Any } ?? NSNull()])
+  }
+
+  func captureOutput(_ output: AVCaptureOutput, didOutput sample: CMSampleBuffer, from connection: AVCaptureConnection) {
+    guard let pixels = CMSampleBufferGetImageBuffer(sample) else { return }
+    queue.async {
+      self.latest = pixels
+      self.frameAt = Date()
+      if self.reportedStall != .some(self.failure) { self.reportStall() }
+    }
+    pacer.changed()
+  }
+
+  private func render(_ pixels: CVPixelBuffer, config: Config) {
+    if config.video { video.encode(pixels, quarterTurns: 0, capturedAt: now()) }
+    guard config.jpeg, jpegGate.admit(config, pacer: pacer),
+      let (data, width, height) = jpeg(CIImage(cvPixelBuffer: pixels), config: config)
+    else { return }
+    Output.frame(jpeg: data, width: width, height: height)
+  }
+
+  private enum CaptureError: Error { case refused }
+}
+
+/// stim-server records only the simulators and emulators Stim owns, so a physical iPhone runs no recording encoder.
+extension PhoneSource: Source {
+  func recordKeyframe() {}
+
+  func input(_ command: Command) {
+    Output.notice(["inputError": "Stim shows a physical iPhone's screen but does not send it input."])
+  }
+}

package/dist/stim-frames/ProcessStream.swift

@@ -0,0 +1,155 @@
+import Foundation
+
+public enum OutputChannel: Sendable {
+  case stdout
+  case stderr
+}
+
+public struct OutputLine: Hashable, Sendable {
+  public var channel: OutputChannel
+  public var text: String
+
+  public init(_ channel: OutputChannel, _ text: String) {
+    self.channel = channel
+    self.text = text
+  }
+}
+
+extension String {
+  /// The text without ANSI CSI sequences (colors, cursor moves) and OSC sequences (titles, links).
+  public var strippingANSI: String {
+    replacingOccurrences(
+      of: "\u{1B}\\[[0-?]*[ -/]*[@-~]|\u{1B}\\][^\u{07}\u{1B}]*(\u{07}|\u{1B}\\\\)", with: "",
+      options: .regularExpression)
+  }
+}
+
+/// Splits a byte stream into lines. A chunk can end inside a line or inside a
+/// UTF-8 sequence, so bytes after the last newline wait for the next chunk.
+public struct LineBuffer: Sendable {
+  private var pending = Data()
+
+  public init() {}
+
+  public mutating func append(_ data: Data) -> [String] {
+    pending.append(data)
+    guard let last = pending.lastIndex(of: UInt8(ascii: "\n")) else { return [] }
+    let complete = pending[pending.startIndex..<last]
+    pending = Data(pending[(last + 1)...])
+    return complete.split(separator: UInt8(ascii: "\n"), omittingEmptySubsequences: false).map(Self.decode)
+  }
+
+  public mutating func finish() -> [String] {
+    defer { pending = Data() }
+    return pending.isEmpty ? [] : [Self.decode(pending)]
+  }
+
+  private static func decode<Bytes: Collection<UInt8>>(_ bytes: Bytes) -> String {
+    var text = String(decoding: bytes, as: UTF8.self)
+    if text.hasSuffix("\r") { text.removeLast() }
+    return text
+  }
+}
+
+/// Runs an executable with an argument list, never through a shell, and
+/// reports its output line by line and then its exit status.
+public enum ProcessStream {
+  /// A child the command leaves running can hold the pipes open, so the exit
+  /// is reported this long after termination even without end of file.
+  static let drainGrace: TimeInterval = 2
+
+  @discardableResult
+  public static func start(
+    executable: String,
+    arguments: [String],
+    cwd: String,
+    environment: [String: String]? = nil,
+    onLine: @escaping @Sendable (OutputLine) -> Void,
+    onExit: @escaping @Sendable (Int32) -> Void
+  ) throws -> Process {
+    let process = Process()
+    process.executableURL = URL(fileURLWithPath: executable)
+    process.arguments = arguments
+    process.currentDirectoryURL = URL(fileURLWithPath: cwd)
+    if let environment { process.environment = environment }
+    process.standardInput = FileHandle.nullDevice
+    let out = Pipe()
+    let err = Pipe()
+    process.standardOutput = out
+    process.standardError = err
+
+    let state = StreamState(onLine: onLine, onExit: onExit)
+    for (pipe, channel) in [(out, OutputChannel.stdout), (err, .stderr)] {
+      pipe.fileHandleForReading.readabilityHandler = { handle in
+        let data = handle.availableData
+        if data.isEmpty {
+          handle.readabilityHandler = nil
+          state.close(channel)
+        } else {
+          state.receive(data, on: channel)
+        }
+      }
+    }
+    process.terminationHandler = { process in
+      let status = process.terminationStatus
+      state.terminated(status)
+      DispatchQueue.global().asyncAfter(deadline: .now() + drainGrace) {
+        out.fileHandleForReading.readabilityHandler = nil
+        err.fileHandleForReading.readabilityHandler = nil
+        state.close(.stdout)
+        state.close(.stderr)
+      }
+    }
+    do {
+      try process.run()
+    } catch {
+      out.fileHandleForReading.readabilityHandler = nil
+      err.fileHandleForReading.readabilityHandler = nil
+      throw error
+    }
+    return process
+  }
+}
+
+private final class StreamState: @unchecked Sendable {
+  private let lock = NSLock()
+  private var buffers: [OutputChannel: LineBuffer] = [.stdout: LineBuffer(), .stderr: LineBuffer()]
+  private var open: Set<OutputChannel> = [.stdout, .stderr]
+  private var status: Int32?
+  private var reported = false
+  private let onLine: @Sendable (OutputLine) -> Void
+  private let onExit: @Sendable (Int32) -> Void
+
+  init(onLine: @escaping @Sendable (OutputLine) -> Void, onExit: @escaping @Sendable (Int32) -> Void) {
+    self.onLine = onLine
+    self.onExit = onExit
+  }
+
+  func receive(_ data: Data, on channel: OutputChannel) {
+    lock.lock()
+    defer { lock.unlock() }
+    guard open.contains(channel) else { return }
+    for line in buffers[channel]!.append(data) { onLine(OutputLine(channel, line)) }
+  }
+
+  func close(_ channel: OutputChannel) {
+    lock.lock()
+    defer { lock.unlock() }
+    guard open.remove(channel) != nil else { return }
+    for line in buffers[channel]!.finish() { onLine(OutputLine(channel, line)) }
+    reportIfDone()
+  }
+
+  func terminated(_ status: Int32) {
+    lock.lock()
+    defer { lock.unlock() }
+    self.status = status
+    reportIfDone()
+  }
+
+  private func reportIfDone() {
+    guard !reported, open.isEmpty, let status else { return }
+    reported = true
+    onExit(status)
+  }
+}