pi-caps-blink 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boston Cartwright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# pi-caps-blink
+
+Pi extension for macOS that blinks the MacBook Caps Lock LED while any Pi agent is actively running on the machine, and restores the system-managed LED when all agents settle.
+
+## Requirements
+
+- macOS 26 or later (Darwin 25+)
+- Node.js 22.19+
+- Xcode Command Line Tools (or Xcode) so `/usr/bin/xcrun swift` can run the packaged daemon script
+- A Mac with a built-in keyboard HID service (`Built-In == true`); external keyboards are never used
+
+The npm manifest rejects non-macOS installation. Older macOS versions, or local
+loads on unsupported platforms, disable the extension with a warning.
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:pi-caps-blink
+```
+
+From a local checkout while developing:
+
+```bash
+pi install /absolute/path/to/pi-caps-blink
+# or
+pi install ./relative/path/to/pi-caps-blink
+```
+
+Use `-l` for a project-local install. To try one run without persisting settings: `pi -e ./path/to/pi-caps-blink`.
+
+## Busy semantics
+
+Busy is agent activity, not idle TUI presence:
+
+| Event | Behavior |
+| --- | --- |
+| `agent_start` | Acquire (desired busy) |
+| `agent_settled` | Release only if `ctx.isIdle()` is true |
+| `session_start` | Acquire if the session is already non-idle |
+| `session_shutdown` | Always release |
+
+`agent_settled` is used instead of `agent_end` because retries, compaction retries, and queued follow-ups can remain after `agent_end`.
+
+Handlers update desired state synchronously and reconcile in the background. They never await daemon startup or delay agent work. Failures warn at most once per active period and degrade to no blinking.
+
+## Machine-wide aggregation
+
+Multiple Pi processes share one per-user Swift daemon. An open Unix-domain socket connection is one active lease; there is no heartbeat protocol. The daemon blinks while the lease count is greater than zero and stops only when the last lease closes. Kernel EOF drops a lease if a client crashes or is SIGKILL’d, so one process cannot turn the LED off while another remains busy.
+
+## Behavior
+
+- Blink cadence: **250 ms On / 750 ms Off**, starting On as soon as the first lease appears
+- Idle restore: on transition to zero leases, the daemon synchronously stops the timer and sets `HIDCapsLockLED` to **Auto**
+- Daemon idle exit: after 5 minutes with no leases, the daemon exits, allowing updates and uninstall without leaving an orphan process while avoiding Swift startup between adjacent runs
+- Startup always restores **Auto** before accepting leases
+
+## Caps Lock LED caveat
+
+The LED is controlled via the private, unsupported `HIDCapsLockLED` property (`On` / `Off` / `Auto`) on a passive IOHID event-system client. This is not a public API and may break or be rejected by future macOS releases. The extension feature-detects and fails soft.
+
+No root, Accessibility, or Input Monitoring permission is expected for this path on currently tested hardware. Logical Caps Lock state (`HIDCapsLockState`) is not written.
+
+## Auto restoration
+
+`HIDCapsLockLED=Auto` is restored when:
+
+- The last lease closes
+- The daemon starts (before accepting clients)
+- Catchable termination (`SIGINT` / `SIGTERM`) or clean idle exit
+
+**Limitation:** SIGKILL of the daemon or sudden power loss can leave an On/Off override stranded. Recovery is best-effort: the next daemon start restores Auto before accepting leases. Starting any Pi session that becomes busy (or otherwise spawning the daemon) triggers that recovery.
+
+## Architecture
+
+```
+Pi extension (TypeScript)
+  └─ CapsBlinkClient (desiredBusy / socket / retry / generation)
+       └─ Unix socket lease ──► CapsBlinkDaemon.swift (singleton)
+                                  ├─ flock on runtime lock file
+                                  ├─ count same-UID accepted fds
+                                  └─ HID LED On/Off/Auto (built-in keyboard only)
+```
+
+Runtime directory: Darwin per-user temp (`getconf DARWIN_USER_TEMP_DIR` / `confstr(_CS_DARWIN_USER_TEMP_DIR)`) + `pi-caps-blink-v1/`, with short `l` (lock) and `s` (socket) names. Directory mode `0700`, socket/lock `0600`, no symlinks, UID ownership checks, `getpeereid` same-UID enforcement, and socket path length under 104 bytes. TypeScript passes the canonical path; Swift independently derives it and rejects mismatches. On connect failure, the extension spawns `/usr/bin/xcrun swift <packaged-script>` detached and retries with exponential backoff + jitter; only the flock winner binds the socket.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+The daemon accepts `--fake-led-file <path>` for LED-free local checks of lease/blink lifecycle.
+
+## Manual hardware test
+
+On a MacBook (or other Mac with a built-in keyboard) running macOS 26+:
+
+1. Install this package into Pi and start a session; confirm Caps Lock still reflects real Caps Lock when idle (Auto).
+2. Start an agent turn; the Caps Lock LED should blink ~250 ms on / 750 ms off without changing typing Caps Lock behavior.
+3. Open a second Pi process and run an agent there too; settling one session must not stop the blink while the other remains busy.
+4. Settle all agents; the LED should return to normal Caps Lock indication promptly.
+5. Optional: kill a busy Pi process mid-turn; its lease should drop via EOF and blinking should continue or stop according to remaining leases.
+6. Optional recovery check: if the LED is stuck after a forced daemon kill, start Pi again and become busy once—daemon startup should restore Auto first.
+
+## Privacy and security
+
+- No network I/O; coordination is a per-user local Unix socket under the Darwin user temp directory
+- No agent transcripts, prompts, or tool output are read or sent
+- Same-UID peer checks and restrictive file modes limit cross-user access to the lease socket
+- The extension and daemon run as your user; like other Pi packages, review source before installing from untrusted origins
+
+## License
+
+MIT — Copyright (c) 2026 Boston Cartwright. See [LICENSE](LICENSE).

package/daemon/CapsBlinkDaemon.swift

@@ -0,0 +1,585 @@
+#!/usr/bin/env swift
+// SPDX-License-Identifier: MIT
+//
+// Per-user lease coordinator for the Pi Caps Lock LED indicator.
+// This source is intentionally self-contained so it can be run by `swift`.
+
+import CoreFoundation
+import Dispatch
+import Foundation
+import IOKit.hidsystem
+import Darwin
+
+// This HID constructor is exported by IOKit but is not in the public SDK
+// module. Client type 2 is the passive event-system client.
+@_silgen_name("IOHIDEventSystemClientCreateWithType")
+private func createPassiveHIDClient(
+    _ allocator: CFAllocator?,
+    _ clientType: UInt32,
+    _ attributes: CFDictionary?
+) -> IOHIDEventSystemClient?
+
+private let runtimeLeaf = "pi-caps-blink-v1"
+private let lockLeaf = "l"
+private let socketLeaf = "s"
+private let queue = DispatchQueue(label: "dev.pi.caps-blink.daemon")
+
+private enum DaemonError: Error, CustomStringConvertible {
+    case usage
+    case unsupportedOS
+    case invalidRuntimeDirectory
+    case unsafeRuntimeDirectory(String)
+    case lockUnavailable
+    case socketPathTooLong
+    case systemCall(String)
+    case noBuiltInKeyboard
+    case ledWriteRejected
+
+    var description: String {
+        switch self {
+        case .usage:
+            return "usage: CapsBlinkDaemon.swift --runtime-dir <DARWIN_USER_TEMP_DIR>/pi-caps-blink-v1 [--fake-led-file <path>]"
+        case .unsupportedOS:
+            return "macOS 26 or later is required"
+        case .invalidRuntimeDirectory:
+            return "runtime directory does not match DARWIN_USER_TEMP_DIR"
+        case let .unsafeRuntimeDirectory(reason):
+            return "unsafe runtime directory: \(reason)"
+        case .lockUnavailable:
+            return "another daemon owns the runtime lock"
+        case .socketPathTooLong:
+            return "Unix socket path is too long"
+        case let .systemCall(name):
+            return "\(name): \(String(cString: strerror(errno)))"
+        case .noBuiltInKeyboard:
+            return "no built-in keyboard HID service is available"
+        case .ledWriteRejected:
+            return "macOS rejected the Caps Lock LED update"
+        }
+    }
+}
+
+private enum LEDMode: String {
+    case on = "On"
+    case off = "Off"
+    case auto = "Auto"
+}
+
+private protocol LEDBackend {
+    func apply(_ mode: LEDMode) throws
+}
+
+/// Uses the HID keyboard filter's private override property. It deliberately
+/// selects only a built-in Generic Desktop Keyboard service.
+private final class HIDLEDBackend: LEDBackend {
+    private let client: IOHIDEventSystemClient
+    private let ledKey = "HIDCapsLockLED" as CFString
+    private let builtInKey = "Built-In" as CFString
+
+    init() throws {
+        guard let client = createPassiveHIDClient(kCFAllocatorDefault, 2, nil) else {
+            throw DaemonError.noBuiltInKeyboard
+        }
+        self.client = client
+    }
+
+    func apply(_ mode: LEDMode) throws {
+        guard let services = IOHIDEventSystemClientCopyServices(client) else {
+            throw DaemonError.noBuiltInKeyboard
+        }
+
+        var foundBuiltInKeyboard = false
+        var acceptedWrite = false
+        let count = CFArrayGetCount(services)
+        for index in 0..<count {
+            guard let rawService = CFArrayGetValueAtIndex(services, index) else { continue }
+            let service = unsafeBitCast(rawService, to: IOHIDServiceClient.self)
+            guard IOHIDServiceClientConformsTo(service, 0x01, 0x06) != 0 else { continue }
+            guard isBuiltIn(service) else { continue }
+
+            foundBuiltInKeyboard = true
+            let value = mode.rawValue as NSString
+            if IOHIDServiceClientSetProperty(service, ledKey, value) {
+                acceptedWrite = true
+            }
+        }
+
+        guard foundBuiltInKeyboard else { throw DaemonError.noBuiltInKeyboard }
+        guard acceptedWrite else { throw DaemonError.ledWriteRejected }
+    }
+
+    private func isBuiltIn(_ service: IOHIDServiceClient) -> Bool {
+        guard let value = IOHIDServiceClientCopyProperty(service, builtInKey) else { return false }
+        return (value as? NSNumber)?.boolValue == true
+    }
+}
+
+/// Explicitly opt-in test backend. It writes only the latest requested state.
+private final class FakeLEDBackend: LEDBackend {
+    private let path: String
+
+    init(path: String) {
+        self.path = path
+    }
+
+    func apply(_ mode: LEDMode) throws {
+        let fd = open(path, O_WRONLY | O_CREAT | O_TRUNC | O_CLOEXEC | O_NOFOLLOW, S_IRUSR | S_IWUSR)
+        guard fd >= 0 else { throw DaemonError.systemCall("open fake LED file") }
+        defer { _ = close(fd) }
+
+        var info = stat()
+        guard fstat(fd, &info) == 0 else { throw DaemonError.systemCall("fstat fake LED file") }
+        guard (info.st_mode & S_IFMT) == S_IFREG, info.st_uid == getuid() else {
+            throw DaemonError.unsafeRuntimeDirectory("fake LED file is not a regular file owned by this user")
+        }
+
+        let bytes = Array((mode.rawValue + "\n").utf8)
+        var written = 0
+        while written < bytes.count {
+            let result = bytes.withUnsafeBytes { buffer in
+                write(fd, buffer.baseAddress!.advanced(by: written), bytes.count - written)
+            }
+            if result > 0 {
+                written += result
+            } else if result < 0 && errno == EINTR {
+                continue
+            } else {
+                throw DaemonError.systemCall("write fake LED file")
+            }
+        }
+    }
+}
+
+private struct Arguments {
+    let runtimeDirectory: String
+    let fakeLEDFile: String?
+
+    static func parse(_ arguments: [String]) throws -> Arguments {
+        var runtimeDirectory: String?
+        var fakeLEDFile: String?
+        var index = 1
+        while index < arguments.count {
+            let argument = arguments[index]
+            guard index + 1 < arguments.count else { throw DaemonError.usage }
+            let value = arguments[index + 1]
+            switch argument {
+            case "--runtime-dir":
+                guard runtimeDirectory == nil else { throw DaemonError.usage }
+                runtimeDirectory = value
+            case "--fake-led-file":
+                guard fakeLEDFile == nil else { throw DaemonError.usage }
+                fakeLEDFile = value
+            default:
+                throw DaemonError.usage
+            }
+            index += 2
+        }
+        guard let runtimeDirectory else { throw DaemonError.usage }
+        return Arguments(runtimeDirectory: runtimeDirectory, fakeLEDFile: fakeLEDFile)
+    }
+}
+
+private func darwinUserTemporaryDirectory() throws -> String {
+    let required = confstr(_CS_DARWIN_USER_TEMP_DIR, nil, 0)
+    guard required > 1 else { throw DaemonError.systemCall("confstr(DARWIN_USER_TEMP_DIR)") }
+    var buffer = [CChar](repeating: 0, count: Int(required))
+    guard confstr(_CS_DARWIN_USER_TEMP_DIR, &buffer, buffer.count) == required else {
+        throw DaemonError.systemCall("confstr(DARWIN_USER_TEMP_DIR)")
+    }
+    let root = String(cString: buffer)
+    guard root.hasPrefix("/") else { throw DaemonError.invalidRuntimeDirectory }
+    return root
+}
+
+private func canonicalDARWINUserTemporaryDirectory() throws -> String {
+    let rawRoot = try darwinUserTemporaryDirectory()
+    var resolved = [CChar](repeating: 0, count: Int(PATH_MAX))
+    guard rawRoot.withCString({ realpath($0, &resolved) != nil }) else {
+        throw DaemonError.systemCall("realpath(DARWIN_USER_TEMP_DIR)")
+    }
+
+    let canonicalRoot = String(cString: resolved)
+    guard canonicalRoot.hasPrefix("/") else { throw DaemonError.invalidRuntimeDirectory }
+    if canonicalRoot == "/" { return canonicalRoot }
+    return canonicalRoot.hasSuffix("/") ? String(canonicalRoot.dropLast()) : canonicalRoot
+}
+
+private func checkOwnedDirectory(_ path: String) throws {
+    var info = stat()
+    guard lstat(path, &info) == 0 else { throw DaemonError.systemCall("lstat runtime directory") }
+    guard (info.st_mode & S_IFMT) == S_IFDIR else {
+        throw DaemonError.unsafeRuntimeDirectory("not a directory or is a symlink")
+    }
+    guard info.st_uid == getuid() else { throw DaemonError.unsafeRuntimeDirectory("wrong owner") }
+    guard (info.st_mode & 0o777) == 0o700 else { throw DaemonError.unsafeRuntimeDirectory("permissions are not 0700") }
+}
+
+private func prepareRuntimeDirectory(passedPath: String) throws -> String {
+    // The TypeScript launcher passes the realpath form. Canonicalize the
+    // independently obtained confstr root too, because on this system confstr
+    // begins with /var while realpath produces /private/var.
+    let canonicalRoot = try canonicalDARWINUserTemporaryDirectory()
+    let expected = canonicalRoot == "/" ? "/" + runtimeLeaf : canonicalRoot + "/" + runtimeLeaf
+    guard passedPath == expected else { throw DaemonError.invalidRuntimeDirectory }
+
+    if mkdir(expected, 0o700) != 0 && errno != EEXIST {
+        throw DaemonError.systemCall("mkdir runtime directory")
+    }
+    try checkOwnedDirectory(expected)
+    return expected
+}
+
+private func setNonBlockingAndCloseOnExec(_ fd: Int32) throws {
+    let flags = fcntl(fd, F_GETFL)
+    guard flags >= 0, fcntl(fd, F_SETFL, flags | O_NONBLOCK) == 0 else {
+        throw DaemonError.systemCall("fcntl(O_NONBLOCK)")
+    }
+    let descriptorFlags = fcntl(fd, F_GETFD)
+    guard descriptorFlags >= 0, fcntl(fd, F_SETFD, descriptorFlags | FD_CLOEXEC) == 0 else {
+        throw DaemonError.systemCall("fcntl(FD_CLOEXEC)")
+    }
+}
+
+private final class Daemon {
+    private let runtimeDirectory: String
+    private let lockPath: String
+    private let socketPath: String
+    private let backend: LEDBackend
+    private let lockFD: Int32
+
+    private var listenerFD: Int32 = -1
+    private var listenerSource: DispatchSourceRead?
+    private var clients: [Int32: DispatchSourceRead] = [:]
+    private var blinkTimer: DispatchSourceTimer?
+    private var idleTimer: DispatchSourceTimer?
+    private var signalSources: [DispatchSourceSignal] = []
+    private var ledIsOn = false
+    private var blinkGeneration: UInt64 = 0
+    private var shuttingDown = false
+    private var pendingFDCloses = Set<Int32>()
+
+    init(runtimeDirectory: String, backend: LEDBackend) throws {
+        self.runtimeDirectory = runtimeDirectory
+        self.lockPath = runtimeDirectory + "/" + lockLeaf
+        self.socketPath = runtimeDirectory + "/" + socketLeaf
+        self.backend = backend
+
+        let fd = open(lockPath, O_RDWR | O_CREAT | O_CLOEXEC | O_NOFOLLOW, S_IRUSR | S_IWUSR)
+        guard fd >= 0 else { throw DaemonError.systemCall("open lock") }
+        self.lockFD = fd
+
+        var info = stat()
+        guard fstat(fd, &info) == 0 else {
+            _ = close(fd)
+            throw DaemonError.systemCall("fstat lock")
+        }
+        guard (info.st_mode & S_IFMT) == S_IFREG, info.st_uid == getuid(), (info.st_mode & 0o777) == 0o600 else {
+            _ = close(fd)
+            throw DaemonError.unsafeRuntimeDirectory("lock is not a 0600 regular file owned by this user")
+        }
+        guard flock(fd, LOCK_EX | LOCK_NB) == 0 else {
+            _ = close(fd)
+            if errno == EWOULDBLOCK { throw DaemonError.lockUnavailable }
+            throw DaemonError.systemCall("flock lock")
+        }
+    }
+
+    deinit {
+        if lockFD >= 0 { _ = close(lockFD) }
+    }
+
+    func start() throws {
+        // A prior catchable shutdown may not have reached Auto; reset before
+        // accepting any lease.
+        try backend.apply(.auto)
+        try removeStaleSocketAsLockOwner()
+        try bindListener()
+        installSignalHandlers()
+        armIdleExit(startSuspended: true)
+
+        // All sources are constructed suspended. Resume them together on the
+        // serial state queue only after every mutable field is initialized.
+        queue.sync { [self] in activateInitialSources() }
+    }
+
+    private func activateInitialSources() {
+        listenerSource?.resume()
+        for source in signalSources { source.resume() }
+        idleTimer?.resume()
+    }
+
+    private func removeStaleSocketAsLockOwner() throws {
+        var info = stat()
+        if lstat(socketPath, &info) != 0 {
+            if errno == ENOENT { return }
+            throw DaemonError.systemCall("lstat socket")
+        }
+        guard (info.st_mode & S_IFMT) == S_IFSOCK else {
+            throw DaemonError.unsafeRuntimeDirectory("socket path is not a socket")
+        }
+        let permissions = info.st_mode & 0o777
+        guard info.st_uid == getuid(), permissions == 0o600 || permissions == 0o700 else {
+            throw DaemonError.unsafeRuntimeDirectory("socket has wrong owner or permissions")
+        }
+        guard unlink(socketPath) == 0 else { throw DaemonError.systemCall("unlink stale socket") }
+    }
+
+    private func bindListener() throws {
+        let capacity = MemoryLayout.size(ofValue: sockaddr_un().sun_path)
+        let encodedPath = Array(socketPath.utf8CString)
+        guard encodedPath.count <= capacity else { throw DaemonError.socketPathTooLong }
+
+        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard fd >= 0 else { throw DaemonError.systemCall("socket") }
+        // chmod after bind leaves a SIGKILL window. Create the socket with its
+        // final mode instead, then immediately restore this process's umask.
+        let priorUmask = umask(0o177)
+        defer { _ = umask(priorUmask) }
+        do {
+            try setNonBlockingAndCloseOnExec(fd)
+            var address = sockaddr_un()
+            address.sun_family = sa_family_t(AF_UNIX)
+            let offset = MemoryLayout<sockaddr_un>.offset(of: \sockaddr_un.sun_path)!
+            withUnsafeMutableBytes(of: &address) { raw in
+                encodedPath.withUnsafeBytes { pathBytes in
+                    raw.baseAddress!.advanced(by: offset).copyMemory(from: pathBytes.baseAddress!, byteCount: encodedPath.count)
+                }
+            }
+            let addressLength = socklen_t(offset + encodedPath.count)
+            let bindResult = withUnsafePointer(to: &address) { pointer in
+                pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    bind(fd, $0, addressLength)
+                }
+            }
+            guard bindResult == 0 else { throw DaemonError.systemCall("bind socket") }
+            guard chmod(socketPath, 0o600) == 0 else { throw DaemonError.systemCall("chmod socket") }
+            guard listen(fd, SOMAXCONN) == 0 else { throw DaemonError.systemCall("listen") }
+        } catch {
+            _ = close(fd)
+            _ = unlink(socketPath)
+            throw error
+        }
+
+        listenerFD = fd
+        let source = DispatchSource.makeReadSource(fileDescriptor: fd, queue: queue)
+        source.setEventHandler { [weak self] in self?.drainAcceptedConnections() }
+        source.setCancelHandler { [weak self] in
+            _ = close(fd)
+            self?.fdDidClose(fd)
+        }
+        listenerSource = source
+    }
+
+    private func installSignalHandlers() {
+        for signalNumber in [SIGINT, SIGTERM] {
+            signal(signalNumber, SIG_IGN)
+            let source = DispatchSource.makeSignalSource(signal: signalNumber, queue: queue)
+            source.setEventHandler { [weak self] in self?.beginShutdown() }
+            signalSources.append(source)
+        }
+    }
+
+    private func drainAcceptedConnections() {
+        guard !shuttingDown else { return }
+        while true {
+            let fd = accept(listenerFD, nil, nil)
+            if fd >= 0 {
+                do {
+                    try setNonBlockingAndCloseOnExec(fd)
+                    var peerUID: uid_t = 0
+                    var peerGID: gid_t = 0
+                    guard getpeereid(fd, &peerUID, &peerGID) == 0, peerUID == getuid() else {
+                        _ = close(fd)
+                        continue
+                    }
+                    addClient(fd)
+                } catch {
+                    _ = close(fd)
+                }
+                continue
+            }
+            if errno == EINTR { continue }
+            if errno == EAGAIN || errno == EWOULDBLOCK { return }
+            beginShutdown()
+            return
+        }
+    }
+
+    private func addClient(_ fd: Int32) {
+        let hadNoClients = clients.isEmpty
+        let source = DispatchSource.makeReadSource(fileDescriptor: fd, queue: queue)
+        source.setEventHandler { [weak self] in self?.drainClient(fd) }
+        source.setCancelHandler { [weak self] in
+            _ = close(fd)
+            self?.fdDidClose(fd)
+        }
+        clients[fd] = source
+        source.resume()
+        if hadNoClients { startBlinking() }
+    }
+
+    private func drainClient(_ fd: Int32) {
+        guard clients[fd] != nil else { return }
+        var bytes = [UInt8](repeating: 0, count: 1024)
+        let byteCount = bytes.count
+        while true {
+            let result = bytes.withUnsafeMutableBytes { read(fd, $0.baseAddress!, byteCount) }
+            if result > 0 { continue }
+            if result == 0 {
+                removeClient(fd)
+                return
+            }
+            if errno == EINTR { continue }
+            if errno == EAGAIN || errno == EWOULDBLOCK { return }
+            removeClient(fd)
+            return
+        }
+    }
+
+    private func removeClient(_ fd: Int32) {
+        guard let source = clients.removeValue(forKey: fd) else { return }
+        source.cancel()
+        if clients.isEmpty { stopBlinkingAndArmIdleExit() }
+    }
+
+    private func startBlinking() {
+        idleTimer?.cancel()
+        idleTimer = nil
+        cancelBlinkTimer()
+        blinkGeneration &+= 1
+        let generation = blinkGeneration
+        setLED(.on)
+        ledIsOn = true
+
+        let timer = DispatchSource.makeTimerSource(queue: queue)
+        timer.setEventHandler { [weak self] in self?.blinkTick(generation: generation) }
+        blinkTimer = timer
+        timer.schedule(deadline: .now() + .milliseconds(250), repeating: .never)
+        timer.resume()
+    }
+
+    private func cancelBlinkTimer() {
+        // Dispatch may already have queued a canceled timer's handler. Changing
+        // this token makes that handler inert before a replacement is installed.
+        blinkGeneration &+= 1
+        blinkTimer?.cancel()
+        blinkTimer = nil
+    }
+
+    private func blinkTick(generation: UInt64) {
+        guard generation == blinkGeneration,
+              !shuttingDown,
+              !clients.isEmpty,
+              let timer = blinkTimer else { return }
+        if ledIsOn {
+            setLED(.off)
+            ledIsOn = false
+            timer.schedule(deadline: .now() + .milliseconds(750), repeating: .never)
+        } else {
+            setLED(.on)
+            ledIsOn = true
+            timer.schedule(deadline: .now() + .milliseconds(250), repeating: .never)
+        }
+    }
+
+    private func stopBlinkingAndArmIdleExit() {
+        cancelBlinkTimer()
+        ledIsOn = false
+        setLED(.auto)
+        armIdleExit()
+    }
+
+    private func armIdleExit(startSuspended: Bool = false) {
+        guard !shuttingDown, clients.isEmpty else { return }
+        idleTimer?.cancel()
+        let timer = DispatchSource.makeTimerSource(queue: queue)
+        timer.setEventHandler { [weak self] in
+            guard let self, self.clients.isEmpty else { return }
+            self.beginShutdown()
+        }
+        idleTimer = timer
+        timer.schedule(deadline: .now() + .seconds(300), repeating: .never)
+        if !startSuspended { timer.resume() }
+    }
+
+    private func setLED(_ mode: LEDMode) {
+        // A failed HID write must not destabilize IPC. A later edge or daemon
+        // restart gets another chance to restore the system-managed value.
+        try? backend.apply(mode)
+    }
+
+    private func beginShutdown() {
+        guard !shuttingDown else { return }
+        shuttingDown = true
+
+        cancelBlinkTimer()
+        idleTimer?.cancel()
+        idleTimer = nil
+        ledIsOn = false
+        setLED(.auto)
+
+        for source in signalSources { source.cancel() }
+        signalSources.removeAll()
+
+        if let source = listenerSource {
+            pendingFDCloses.insert(listenerFD)
+            source.cancel()
+            listenerSource = nil
+        }
+        for (fd, source) in clients {
+            pendingFDCloses.insert(fd)
+            source.cancel()
+        }
+        clients.removeAll()
+        finishShutdownIfReady()
+    }
+
+    private func fdDidClose(_ fd: Int32) {
+        guard pendingFDCloses.remove(fd) != nil else { return }
+        finishShutdownIfReady()
+    }
+
+    private func finishShutdownIfReady() {
+        guard shuttingDown, pendingFDCloses.isEmpty else { return }
+        // This process owns the flock, so it alone removes the active pathname.
+        // Re-validate before unlinking rather than deleting an unexpected file.
+        var info = stat()
+        if lstat(socketPath, &info) == 0,
+           (info.st_mode & S_IFMT) == S_IFSOCK,
+           info.st_uid == getuid(),
+           (info.st_mode & 0o777) == 0o600 {
+            _ = unlink(socketPath)
+        }
+        _ = flock(lockFD, LOCK_UN)
+        _ = close(lockFD)
+        exit(0)
+    }
+}
+
+private func run() throws {
+    guard ProcessInfo.processInfo.operatingSystemVersion.majorVersion >= 26 else {
+        throw DaemonError.unsupportedOS
+    }
+    _ = umask(0o077)
+    let arguments = try Arguments.parse(CommandLine.arguments)
+    let runtimeDirectory = try prepareRuntimeDirectory(passedPath: arguments.runtimeDirectory)
+    let backend: LEDBackend
+    if let fakeLEDFile = arguments.fakeLEDFile {
+        backend = FakeLEDBackend(path: fakeLEDFile)
+    } else {
+        backend = try HIDLEDBackend()
+    }
+    let daemon = try Daemon(runtimeDirectory: runtimeDirectory, backend: backend)
+    try daemon.start()
+    dispatchMain()
+}
+
+do {
+    try run()
+} catch DaemonError.lockUnavailable {
+    // Spawn races are expected. The process holding the lock is authoritative.
+    exit(0)
+} catch {
+    fputs("CapsBlinkDaemon: \(error)\n", stderr)
+    exit(1)
+}

package/extensions/index.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CapsBlinkClient, defaultConnect } from "../src/client.ts";
+import { checkPlatformSupport } from "../src/platform.ts";
+import { resolveRuntimePaths } from "../src/runtime-paths.ts";
+import {
+	packageRootFrom,
+	resolveDaemonScriptPath,
+	spawnDaemon,
+} from "../src/spawn.ts";
+
+/**
+ * Blink the built-in Caps Lock LED while this Pi session has an active agent.
+ * Machine-wide coordination is via a shared Swift daemon lease socket.
+ */
+export default function capsBlinkExtension(pi: ExtensionAPI): void {
+	const support = checkPlatformSupport();
+	let client: CapsBlinkClient | null = null;
+	let unsupportedWarned = false;
+
+	const warn = (message: string): void => {
+		console.warn(message);
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		client?.dispose();
+		client = null;
+
+		if (!support.ok) {
+			if (!unsupportedWarned) {
+				unsupportedWarned = true;
+				warn(`pi-caps-blink: disabled — ${support.reason}`);
+			}
+			return;
+		}
+
+		try {
+			const paths = resolveRuntimePaths();
+			const packageRoot = packageRootFrom(import.meta.url);
+			client = new CapsBlinkClient({
+				socketPath: paths.socketPath,
+				runtimeDir: paths.runtimeDir,
+				scriptPath: resolveDaemonScriptPath(packageRoot),
+				connect: defaultConnect,
+				spawnDaemon,
+				setTimeout: (fn, ms) => setTimeout(fn, ms),
+				clearTimeout: (id) => clearTimeout(id as NodeJS.Timeout),
+				random: Math.random,
+				now: () => Date.now(),
+				warn,
+			});
+		} catch (err) {
+			if (!unsupportedWarned) {
+				unsupportedWarned = true;
+				const detail = err instanceof Error ? err.message : String(err);
+				warn(`pi-caps-blink: disabled — ${detail}`);
+			}
+			return;
+		}
+
+		if (!ctx.isIdle()) {
+			client.setDesiredBusy(true);
+		}
+	});
+
+	pi.on("agent_start", () => {
+		client?.setDesiredBusy(true);
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (ctx.isIdle()) {
+			client?.setDesiredBusy(false);
+		}
+	});
+
+	pi.on("session_shutdown", () => {
+		client?.setDesiredBusy(false);
+		client?.dispose();
+		client = null;
+	});
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "pi-caps-blink",
+	"version": "0.1.0",
+	"description": "Blink the MacBook Caps Lock LED while any Pi agent is actively running.",
+	"type": "module",
+	"license": "MIT",
+	"author": "Boston Cartwright",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/bstncartwright/pi-caps-blink.git"
+	},
+	"bugs": {
+		"url": "https://github.com/bstncartwright/pi-caps-blink/issues"
+	},
+	"homepage": "https://github.com/bstncartwright/pi-caps-blink#readme",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"macos",
+		"caps-lock"
+	],
+	"files": [
+		"daemon",
+		"extensions",
+		"src"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/index.ts"
+		]
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit && xcrun swiftc -typecheck daemon/CapsBlinkDaemon.swift",
+		"test": "node --test --experimental-strip-types test/*.test.ts",
+		"check": "npm run typecheck && npm test",
+		"prepublishOnly": "npm run check"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^0.80.10",
+		"@types/node": "^24.10.0",
+		"typescript": "^5.9.3"
+	},
+	"engines": {
+		"node": ">=22.19"
+	},
+	"os": ["darwin"]
+}

package/src/client.ts

@@ -0,0 +1,351 @@
+import net from "node:net";
+import {
+	INITIAL_RETRY_MS,
+	MAX_RETRY_MS,
+	SPAWN_COOLDOWN_MS,
+} from "./constants.ts";
+
+/** Minimal lease handle: an open connection is the acquire. */
+export type LeaseSocket = {
+	destroy(): void;
+	on(event: "close", listener: () => void): void;
+	on(event: "error", listener: (err: Error) => void): void;
+	off?(event: "close", listener: () => void): void;
+	off?(event: "error", listener: (err: Error) => void): void;
+};
+
+export type SpawnDaemonArgs = {
+	runtimeDir: string;
+	scriptPath: string;
+	onError?: (err: Error) => void;
+};
+
+export type CapsBlinkClientDeps = {
+	socketPath: string;
+	runtimeDir: string;
+	scriptPath: string;
+	connect: (socketPath: string) => Promise<LeaseSocket>;
+	spawnDaemon: (args: SpawnDaemonArgs) => void;
+	setTimeout: (fn: () => void, ms: number) => unknown;
+	clearTimeout: (id: unknown) => void;
+	random: () => number;
+	now: () => number;
+	warn: (message: string) => void;
+	initialRetryMs?: number;
+	maxRetryMs?: number;
+	spawnCooldownMs?: number;
+};
+
+/**
+ * Default Unix-domain connect. Connection success is the lease; no protocol.
+ */
+export function defaultConnect(socketPath: string): Promise<LeaseSocket> {
+	return new Promise((resolve, reject) => {
+		const socket = net.createConnection({ path: socketPath });
+		const onError = (err: Error) => {
+			socket.off("connect", onConnect);
+			socket.destroy();
+			reject(err);
+		};
+		const onConnect = () => {
+			socket.off("error", onError);
+			// Prevent unhandled error events after lease is held; close drives retry.
+			socket.on("error", () => {});
+			resolve(socket);
+		};
+		socket.once("error", onError);
+		socket.once("connect", onConnect);
+	});
+}
+
+/**
+ * Explicit desiredBusy / socket / retry / generation state machine.
+ * Handlers should call {@link CapsBlinkClient.setDesiredBusy} without awaiting.
+ */
+export class CapsBlinkClient {
+	private desiredBusy = false;
+	private socket: LeaseSocket | null = null;
+	/** Generation of the in-flight connect, or null if none for the current lease cycle. */
+	private connectingGeneration: number | null = null;
+	private generation = 0;
+	private retryTimer: unknown = null;
+	private retryAttempt = 0;
+	private lastSpawnAt = Number.NEGATIVE_INFINITY;
+	private busySince = 0;
+	private warned = false;
+
+	private readonly socketPath: string;
+	private readonly runtimeDir: string;
+	private readonly scriptPath: string;
+	private readonly connectFn: CapsBlinkClientDeps["connect"];
+	private readonly spawnDaemonFn: CapsBlinkClientDeps["spawnDaemon"];
+	private readonly setTimeoutFn: CapsBlinkClientDeps["setTimeout"];
+	private readonly clearTimeoutFn: CapsBlinkClientDeps["clearTimeout"];
+	private readonly randomFn: CapsBlinkClientDeps["random"];
+	private readonly nowFn: CapsBlinkClientDeps["now"];
+	private readonly warnFn: CapsBlinkClientDeps["warn"];
+	private readonly initialRetryMs: number;
+	private readonly maxRetryMs: number;
+	private readonly spawnCooldownMs: number;
+
+	constructor(deps: CapsBlinkClientDeps) {
+		this.socketPath = deps.socketPath;
+		this.runtimeDir = deps.runtimeDir;
+		this.scriptPath = deps.scriptPath;
+		this.connectFn = deps.connect;
+		this.spawnDaemonFn = deps.spawnDaemon;
+		this.setTimeoutFn = deps.setTimeout;
+		this.clearTimeoutFn = deps.clearTimeout;
+		this.randomFn = deps.random;
+		this.nowFn = deps.now;
+		this.warnFn = deps.warn;
+		this.initialRetryMs = deps.initialRetryMs ?? INITIAL_RETRY_MS;
+		this.maxRetryMs = deps.maxRetryMs ?? MAX_RETRY_MS;
+		this.spawnCooldownMs = deps.spawnCooldownMs ?? SPAWN_COOLDOWN_MS;
+	}
+
+	/** Test/observation helpers. */
+	getDesiredBusy(): boolean {
+		return this.desiredBusy;
+	}
+
+	getGeneration(): number {
+		return this.generation;
+	}
+
+	hasSocket(): boolean {
+		return this.socket !== null;
+	}
+
+	isConnecting(): boolean {
+		return this.connectingGeneration !== null;
+	}
+
+	hasRetryTimer(): boolean {
+		return this.retryTimer !== null;
+	}
+
+	/**
+	 * Synchronously update desired busy state and fire-and-forget reconcile.
+	 * Never awaits daemon startup.
+	 */
+	setDesiredBusy(desired: boolean): void {
+		if (desired) {
+			if (
+				this.desiredBusy &&
+				(this.socket ||
+					this.connectingGeneration === this.generation ||
+					this.retryTimer)
+			) {
+				return;
+			}
+			if (!this.desiredBusy) {
+				this.busySince = this.nowFn();
+				this.warned = false;
+			}
+			this.desiredBusy = true;
+			this.reconcile();
+			return;
+		}
+
+		if (
+			!this.desiredBusy &&
+			!this.socket &&
+			this.connectingGeneration === null &&
+			!this.retryTimer
+		) {
+			return;
+		}
+
+		this.desiredBusy = false;
+		this.generation += 1;
+		this.clearRetryTimer();
+		this.retryAttempt = 0;
+		this.destroySocket();
+		// In-flight connect completions are generation-gated and will destroy.
+		// connectingGeneration stays until that attempt settles (may be stale).
+	}
+
+	/** Idempotent shutdown helper for session_shutdown. */
+	dispose(): void {
+		this.setDesiredBusy(false);
+	}
+
+	private reconcile(): void {
+		if (!this.desiredBusy) {
+			return;
+		}
+		if (this.socket) {
+			return;
+		}
+		// Only block on a connect for *this* generation; a stale pending connect
+		// must not prevent re-acquire after busy→false→true.
+		if (this.connectingGeneration === this.generation) {
+			return;
+		}
+		this.clearRetryTimer();
+		this.beginConnect(this.generation);
+	}
+
+	private beginConnect(generation: number): void {
+		if (!this.desiredBusy || generation !== this.generation) {
+			return;
+		}
+		if (this.socket || this.connectingGeneration === generation) {
+			return;
+		}
+
+		this.connectingGeneration = generation;
+		void this.connectFn(this.socketPath).then(
+			(socket) => this.onConnectSuccess(generation, socket),
+			(err: unknown) => this.onConnectFailure(generation, err),
+		);
+	}
+
+	private clearConnectingIf(generation: number): void {
+		if (this.connectingGeneration === generation) {
+			this.connectingGeneration = null;
+		}
+	}
+
+	private onConnectSuccess(generation: number, socket: LeaseSocket): void {
+		this.clearConnectingIf(generation);
+
+		if (!this.desiredBusy || generation !== this.generation) {
+			socket.destroy();
+			// Stale completion after re-acquire: ensure a current connect is running.
+			this.reconcile();
+			return;
+		}
+
+		this.socket = socket;
+		this.retryAttempt = 0;
+		this.clearRetryTimer();
+
+		const onClose = () => {
+			socket.off?.("close", onClose);
+			this.onSocketClose(generation, socket);
+		};
+		socket.on("close", onClose);
+		// Swallow post-lease errors; close drives reconnection.
+		socket.on("error", () => {});
+	}
+
+	private onConnectFailure(generation: number, err: unknown): void {
+		this.clearConnectingIf(generation);
+
+		if (!this.desiredBusy || generation !== this.generation) {
+			this.reconcile();
+			return;
+		}
+
+		// A missing socket is expected on first use: the daemon is on-demand.
+		// Warn only if startup has remained unavailable for a full spawn cooldown.
+		if (this.nowFn() - this.busySince >= this.spawnCooldownMs) {
+			this.warnOnce(
+				`pi-caps-blink: unavailable (${formatError(err)}); still retrying`,
+			);
+		}
+		this.maybeSpawnDaemon();
+		this.scheduleRetry(generation);
+	}
+
+	private onSocketClose(generation: number, socket: LeaseSocket): void {
+		if (this.socket === socket) {
+			this.socket = null;
+		}
+
+		// Retry daemon death only from close, only while same generation remains desired.
+		if (!this.desiredBusy || generation !== this.generation) {
+			return;
+		}
+
+		this.warnOnce("pi-caps-blink: lease socket closed; reconnecting");
+		this.maybeSpawnDaemon();
+		this.scheduleRetry(generation);
+	}
+
+	private scheduleRetry(generation: number): void {
+		if (!this.desiredBusy || generation !== this.generation) {
+			return;
+		}
+		if (
+			this.retryTimer !== null ||
+			this.connectingGeneration === generation ||
+			this.socket
+		) {
+			return;
+		}
+
+		const base = Math.min(
+			this.maxRetryMs,
+			this.initialRetryMs * 2 ** this.retryAttempt,
+		);
+		this.retryAttempt += 1;
+		const jitter = this.randomFn() * base;
+		const delay = Math.min(this.maxRetryMs, base * 0.5 + jitter * 0.5);
+
+		this.retryTimer = this.setTimeoutFn(() => {
+			this.retryTimer = null;
+			if (!this.desiredBusy || generation !== this.generation) {
+				return;
+			}
+			this.beginConnect(generation);
+		}, delay);
+	}
+
+	private maybeSpawnDaemon(): void {
+		const now = this.nowFn();
+		if (now - this.lastSpawnAt < this.spawnCooldownMs) {
+			return;
+		}
+		this.lastSpawnAt = now;
+		try {
+			this.spawnDaemonFn({
+				runtimeDir: this.runtimeDir,
+				scriptPath: this.scriptPath,
+				onError: (err) => {
+					this.warnOnce(
+						`pi-caps-blink: daemon spawn error (${formatError(err)})`,
+					);
+				},
+			});
+		} catch (err) {
+			this.warnOnce(`pi-caps-blink: failed to spawn daemon (${formatError(err)})`);
+		}
+	}
+
+	private destroySocket(): void {
+		const socket = this.socket;
+		this.socket = null;
+		if (socket) {
+			try {
+				socket.destroy();
+			} catch {
+				// ignore
+			}
+		}
+	}
+
+	private clearRetryTimer(): void {
+		if (this.retryTimer !== null) {
+			this.clearTimeoutFn(this.retryTimer);
+			this.retryTimer = null;
+		}
+	}
+
+	private warnOnce(message: string): void {
+		if (this.warned) {
+			return;
+		}
+		this.warned = true;
+		this.warnFn(message);
+	}
+}
+
+function formatError(err: unknown): string {
+	if (err instanceof Error) {
+		return err.message;
+	}
+	return String(err);
+}

package/src/constants.ts

@@ -0,0 +1,24 @@
+/** Fixed short runtime subdirectory under the Darwin per-user temp root. */
+export const RUNTIME_DIR_NAME = "pi-caps-blink-v1";
+
+/** Singleton lock file name inside the runtime directory (daemon-owned). */
+export const LOCK_NAME = "l";
+
+/** Unix-domain socket name inside the runtime directory. */
+export const SOCKET_NAME = "s";
+
+/**
+ * macOS `sockaddr_un.sun_path` capacity. Socket path UTF-8 byte length must be
+ * strictly less than this.
+ */
+export const MAX_SOCKET_PATH_BYTES = 104;
+
+/** Minimum Darwin kernel major corresponding to macOS 26. */
+export const MIN_DARWIN_MAJOR = 25;
+
+/** Packaged Swift coordinator script, relative to the package root. */
+export const DAEMON_SCRIPT_RELATIVE = "daemon/CapsBlinkDaemon.swift";
+
+export const INITIAL_RETRY_MS = 50;
+export const MAX_RETRY_MS = 2_000;
+export const SPAWN_COOLDOWN_MS = 10_000;

package/src/platform.ts

@@ -0,0 +1,39 @@
+import os from "node:os";
+import { MIN_DARWIN_MAJOR } from "./constants.ts";
+
+export type PlatformSupport =
+	| { ok: true }
+	| { ok: false; reason: string };
+
+export type PlatformInfo = {
+	platform: NodeJS.Platform;
+	/** Darwin kernel release string, e.g. `25.5.0`. */
+	release: string;
+};
+
+/**
+ * Caps Lock LED control is supported on macOS 26+ only (Darwin major >= 25).
+ */
+export function checkPlatformSupport(
+	info: PlatformInfo = {
+		platform: process.platform,
+		release: os.release(),
+	},
+): PlatformSupport {
+	if (info.platform !== "darwin") {
+		return {
+			ok: false,
+			reason: `pi-caps-blink is macOS-only (got ${info.platform})`,
+		};
+	}
+
+	const major = Number.parseInt(info.release.split(".")[0] ?? "", 10);
+	if (!Number.isFinite(major) || major < MIN_DARWIN_MAJOR) {
+		return {
+			ok: false,
+			reason: `pi-caps-blink requires macOS 26+ (Darwin ${MIN_DARWIN_MAJOR}+; got ${info.release})`,
+		};
+	}
+
+	return { ok: true };
+}

package/src/runtime-paths.ts

@@ -0,0 +1,61 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	MAX_SOCKET_PATH_BYTES,
+	RUNTIME_DIR_NAME,
+	SOCKET_NAME,
+} from "./constants.ts";
+
+export type RuntimePaths = {
+	/** Canonical Darwin per-user temp + `pi-caps-blink-v1`. */
+	runtimeDir: string;
+	/** Socket path: `{runtimeDir}/s`. */
+	socketPath: string;
+};
+
+export class RuntimePathError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RuntimePathError";
+	}
+}
+
+export type ResolveRuntimePathsOptions = {
+	/** Override `getconf DARWIN_USER_TEMP_DIR` result (tests). */
+	tempRoot?: string;
+	/** Override realpath (tests). */
+	realpath?: (input: string) => string;
+};
+
+/**
+ * Canonical runtime directory: realpath(`/usr/bin/getconf DARWIN_USER_TEMP_DIR`)
+ * + fixed `pi-caps-blink-v1`, with socket path UTF-8 length < 104.
+ */
+export function resolveRuntimePaths(
+	options: ResolveRuntimePathsOptions = {},
+): RuntimePaths {
+	const rawTemp =
+		options.tempRoot ??
+		execFileSync("/usr/bin/getconf", ["DARWIN_USER_TEMP_DIR"], {
+			encoding: "utf8",
+		}).trim();
+
+	if (!rawTemp) {
+		throw new RuntimePathError("getconf DARWIN_USER_TEMP_DIR returned empty");
+	}
+
+	const realpath = options.realpath ?? ((p: string) => fs.realpathSync(p));
+	const tempRoot = realpath(rawTemp);
+	const runtimeDir = path.join(tempRoot, RUNTIME_DIR_NAME);
+	const socketPath = path.join(runtimeDir, SOCKET_NAME);
+	const bytes = Buffer.byteLength(socketPath, "utf8");
+
+	if (bytes >= MAX_SOCKET_PATH_BYTES) {
+		throw new RuntimePathError(
+			`socket path is ${bytes} UTF-8 bytes; must be < ${MAX_SOCKET_PATH_BYTES}: ${socketPath}`,
+		);
+	}
+
+	return { runtimeDir, socketPath };
+}

package/src/spawn.ts

@@ -0,0 +1,46 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DAEMON_SCRIPT_RELATIVE } from "./constants.ts";
+
+export function packageRootFrom(importMetaUrl: string): string {
+	return path.resolve(path.dirname(fileURLToPath(importMetaUrl)), "..");
+}
+
+export function resolveDaemonScriptPath(packageRoot: string): string {
+	return path.join(packageRoot, DAEMON_SCRIPT_RELATIVE);
+}
+
+export type SpawnDaemonOptions = {
+	runtimeDir: string;
+	scriptPath: string;
+	/** Injectable spawn for tests. Defaults to detached `xcrun swift`. */
+	spawnImpl?: typeof spawn;
+	/**
+	 * Called if the child emits `error` (e.g. xcrun missing). Attaching this
+	 * prevents an async spawn failure from becoming an unhandled error event.
+	 */
+	onError?: (err: Error) => void;
+};
+
+/**
+ * Start the packaged Swift coordinator detached. Does not wait for readiness;
+ * callers retry connect with backoff.
+ */
+export function spawnDaemon(options: SpawnDaemonOptions): ChildProcess {
+	const spawnImpl = options.spawnImpl ?? spawn;
+	const child = spawnImpl(
+		"/usr/bin/xcrun",
+		["swift", options.scriptPath, "--runtime-dir", options.runtimeDir],
+		{
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true,
+		},
+	);
+	child.on("error", (err) => {
+		options.onError?.(err);
+	});
+	child.unref();
+	return child;
+}