Refactor: extract Sparkle self-update into CmuxUpdater package (WIP)

CLAUDE.md

@@ -368,7 +368,7 @@ When **extracting** existing code that uses a forbidden primitive into a package
 - **Combine for change propagation.** No `@Published`, no `ObservableObject`, no `PassthroughSubject`/`CurrentValueSubject`, no `AnyCancellable` for change observation. Use `@Observable` (Observation framework, Swift 5.9+) for SwiftUI state, or `AsyncStream`/`AsyncSequence` for cross-actor change propagation.
 - **Completion-handler APIs.** Authoring a new public API with a `(Result<T, Error>) -> Void` or `(T?, Error?) -> Void` callback is forbidden. Use `async throws -> T`. When wrapping a legacy callback at the boundary, use `withCheckedContinuation`/`withCheckedThrowingContinuation` and keep it confined to that one seam.
 - **`DispatchQueue.main.async { ... }`.** Annotate the destination with `@MainActor`. Call sites either `await` the main-isolated function or are themselves `@MainActor`.
-- **`Task.sleep` in app/runtime code.** Already forbidden by the cmuxterm-hq top-level rule against sleep-based timing. Allowed in tests only.
+- **Sleeping as a synchronization substitute.** `Task.sleep` / `Clock.sleep` (or any sleep) used to *poll* for a condition, to let state "settle" before reading it, or to *race* a callback/animation is forbidden — use a real signal (`AsyncStream`, `NSKeyValueObservation`, a completion, a state change). `DispatchQueue.asyncAfter` is banned outright (it is neither cancellable-by-structure nor testable). A *bounded, cancellable, intended* delay or deadline is allowed under the `Clock.sleep` carve-out below.
 
 **Required shape:**
 
@@ -383,7 +383,8 @@ These low-level primitives have no async-native replacement. They must be hidden
 
 - `DispatchSource.makeFileSystemObjectSource` for file watching (no Foundation async equivalent).
 - `DispatchSource.makeReadSource`/`makeWriteSource` for low-level socket I/O.
-- `DispatchSource.makeTimerSource` (one-shot) for a genuine deadline/timeout, e.g. a subprocess time limit. A real deadline needs a timer, and the async-native timers are disallowed here (`Task.sleep` is banned in runtime code; `DispatchQueue.asyncAfter` is a forbidden timing hack). Hide the timer behind the type and cancel it on the non-timeout path. This is for true deadlines only, never to poll or to fake a sleep.
+- **A bounded, cancellable `Clock.sleep` (preferred) or `Task.sleep` for a genuine delay/deadline** that is itself the intended behavior — a minimum display duration, an auto-dismiss, a check timeout. Drive it from an *injected* `Clock` (or a duration) so tests advance virtual time with no real waiting, and wire the sleeping `Task`'s cancellation to the relevant lifecycle so a state transition cancels the pending delay (store the `Task`, cancel it on transition; or use `withTaskCancellationHandler`). For true delays/deadlines only, never to poll, settle, or race — those still require a real signal. One-line justification on the call site.
+- `DispatchSource.makeTimerSource` (one-shot) **only when a genuine deadline must fire outside any async context** — a non-`async` type with no `Task` to host the sleep. Prefer the `Clock.sleep` carve-out above whenever the code is already on an actor or in async code (it is cancellation-integrated and testable; a raw `DispatchSource` timer is not, and has suspend/resume/cancel footguns). Hide the timer behind the type, cancel it on the non-timeout path, and never use it to poll or fake a sleep.
 - A **lock for a synchronous compare-and-set called from non-async callbacks**, where promoting to an `actor` would only add `Task`/`await` hops and reentrancy. The canonical case is a one-shot resume guard: several synchronous `Process`/`DispatchSource` callbacks race to resume one `withCheckedContinuation` exactly once. `OSAllocatedUnfairLock(initialState:)` guarding a `Bool` (claimed once, checked synchronously in each callback) is correct, deterministic, and lets the callback resume the continuation inline. This carve-out is for short, non-blocking critical sections over a tiny flag/counter — not for guarding ongoing domain state (that is still an `actor`). Keep it private to the type, with a one-line justification.
 - `NSKeyValueObservation` token (the closure-based API) when wrapping a Foundation/AppKit type that exposes change only via KVO.
 
@@ -405,7 +406,7 @@ Without a justification comment, the diff is rejected. `@unchecked Sendable` on
 
 - Applies to: every new file in `Packages/`, every new file in the app target, every meaningful rewrite of an existing Swift file.
 - Existing app target code may continue to use the old primitives until rewritten. Do not retrofit blindly.
-- Code review checklist (Codex, CodeRabbit, Greptile, and human reviewers): reject diffs that introduce `@Published`/`ObservableObject`/`DispatchQueue.main.async`/`addObserver(_:forKeyPath:...)`/`Task.sleep` outside tests in new code. Reject a lock (`NSLock`/`OSAllocatedUnfairLock`/etc.) or `@unchecked Sendable`/`nonisolated(unsafe)` unless it falls under a documented carve-out *and* carries a one-line justification — and reject a single-method `actor` that exists only to guard a flag (use the lock carve-out instead).
+- Code review checklist (Codex, CodeRabbit, Greptile, and human reviewers): reject diffs that introduce `@Published`/`ObservableObject`/`DispatchQueue.main.async`/`addObserver(_:forKeyPath:...)`/`DispatchQueue.asyncAfter` in new code, or `Task.sleep`/`Clock.sleep` used to poll, settle, or race rather than as a bounded, cancellable, injected-clock delay with justification. Reject a lock (`NSLock`/`OSAllocatedUnfairLock`/etc.) or `@unchecked Sendable`/`nonisolated(unsafe)` unless it falls under a documented carve-out *and* carries a one-line justification — and reject a single-method `actor` that exists only to guard a flag (use the lock carve-out instead).
 
 ## Test quality policy
 

Packages/CmuxUpdater/Package.swift

@@ -0,0 +1,41 @@
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+    name: "CmuxUpdater",
+    platforms: [
+        .macOS(.v14),
+    ],
+    products: [
+        .library(
+            name: "CmuxUpdater",
+            targets: ["CmuxUpdater"]
+        ),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/sparkle-project/Sparkle", from: "2.5.1"),
+    ],
+    targets: [
+        .target(
+            name: "CmuxUpdater",
+            dependencies: [
+                .product(name: "Sparkle", package: "Sparkle"),
+            ],
+            swiftSettings: [
+                .swiftLanguageMode(.v6),
+                .enableUpcomingFeature("ExistentialAny"),
+                .enableUpcomingFeature("InternalImportsByDefault"),
+            ]
+        ),
+        .testTarget(
+            name: "CmuxUpdaterTests",
+            dependencies: ["CmuxUpdater"],
+            swiftSettings: [
+                .swiftLanguageMode(.v6),
+                .enableUpcomingFeature("ExistentialAny"),
+                .enableUpcomingFeature("InternalImportsByDefault"),
+            ]
+        ),
+    ]
+)

Packages/CmuxUpdater/Sources/CmuxUpdater/TestSupport/UpdateTestSupport.swift

@@ -0,0 +1,123 @@
+#if DEBUG
+import Foundation
+@preconcurrency import Sparkle
+
+/// Drives the ``UpdateStateModel`` into specific states for UI tests, and can run a mock feed
+/// check against an in-process appcast (``UpdateTestURLProtocol``).
+///
+/// DEBUG-only test scaffolding, gated on `CMUX_UI_TEST_*` environment variables. Constructed by
+/// the host with the live model and logger.
+@MainActor
+public struct UpdateTestSupport {
+    let model: UpdateStateModel
+    let log: any UpdateLogging
+
+    /// Creates the test-support helper bound to a model and logger.
+    public init(model: UpdateStateModel, log: any UpdateLogging) {
+        self.model = model
+        self.log = log
+    }
+
+    /// Applies an initial detected-update banner and/or a forced state from the environment.
+    public func applyIfNeeded() {
+        let env = ProcessInfo.processInfo.environment
+        guard env["CMUX_UI_TEST_MODE"] == "1" else { return }
+
+        if let detectedVersion = env["CMUX_UI_TEST_DETECTED_UPDATE_VERSION"],
+           !detectedVersion.isEmpty {
+            if let item = Self.makeAppcastItem(displayVersion: detectedVersion) {
+                model.recordDetectedUpdate(item)
+            } else {
+                model.debugSetDetectedVersion(UpdateStateModel.normalizedDetectedUpdateVersion(from: detectedVersion))
+            }
+        }
+
+        guard let state = env["CMUX_UI_TEST_UPDATE_STATE"] else { return }
+        switch state {
+        case "available":
+            let version = env["CMUX_UI_TEST_UPDATE_VERSION"] ?? "9.9.9"
+            transition(to: .updateAvailable(.init(
+                appcastItem: Self.makeAppcastItem(displayVersion: version) ?? SUAppcastItem.empty(),
+                reply: { _ in }
+            )))
+        case "notFound":
+            transition(to: .notFound(.init(acknowledgement: {})))
+        case "downloading":
+            transition(to: .downloading(.init(cancel: {}, expectedLength: 100, progress: 50)))
+        case "extracting":
+            transition(to: .extracting(.init(progress: 0.5)))
+        case "installing":
+            transition(to: .installing(.init(isAutoUpdate: false, retryTerminatingApplication: {}, dismiss: {})))
+        case "error":
+            let message = env["CMUX_UI_TEST_UPDATE_ERROR_MESSAGE"] ?? "Test update error"
+            let error = NSError(domain: "cmux.update.uitest", code: 1, userInfo: [NSLocalizedDescriptionKey: message])
+            transition(to: .error(.init(
+                error: error,
+                retry: {},
+                dismiss: {},
+                technicalDetails: "ui-test error",
+                feedURLString: env["CMUX_UI_TEST_FEED_URL"]
+            )))
+        default:
+            break
+        }
+    }
+
+    /// Runs a mock feed check against `CMUX_UI_TEST_FEED_URL` if requested. Returns whether it ran.
+    public func performMockFeedCheckIfNeeded() -> Bool {
+        let env = ProcessInfo.processInfo.environment
+        guard env["CMUX_UI_TEST_TRIGGER_UPDATE_CHECK"] == "1" else { return false }
+        guard let feedURLString = env["CMUX_UI_TEST_FEED_URL"],
+              let feedURL = URL(string: feedURLString) else { return false }
+
+        log.append("ui test mock feed check: \(feedURLString)")
+        UpdateTestURLProtocol.registerIfNeeded()
+        model.applyDriverState(.checking(.init(cancel: {})))
+
+        let model = self.model
+        let task = URLSession.shared.dataTask(with: feedURL) { data, _, _ in
+            let xml = data.flatMap { String(data: $0, encoding: .utf8) } ?? ""
+            let version = env["CMUX_UI_TEST_UPDATE_VERSION"] ?? "9.9.9"
+            let hasItem = xml.contains("<item>")
+            let delayMilliseconds = Int(env["CMUX_UI_TEST_MOCK_FEED_DELAY_MS"] ?? "") ?? 0
+            Task { @MainActor in
+                if delayMilliseconds > 0 {
+                    try? await Task.sleep(for: .milliseconds(delayMilliseconds))
+                }
+                if hasItem {
+                    let appcastItem = Self.makeAppcastItem(displayVersion: version) ?? SUAppcastItem.empty()
+                    model.applyDriverState(.updateAvailable(.init(appcastItem: appcastItem, reply: { _ in })))
+                } else {
+                    model.applyDriverState(.notFound(.init(acknowledgement: {})))
+                }
+            }
+        }
+        task.resume()
+        return true
+    }
+
+    private func transition(to state: UpdateState) {
+        model.applyDriverState(.checking(.init(cancel: {})))
+        let model = self.model
+        Task { @MainActor in
+            try? await Task.sleep(for: .milliseconds(200))
+            model.applyDriverState(state)
+        }
+    }
+
+    private static func makeAppcastItem(displayVersion: String) -> SUAppcastItem? {
+        let enclosure: [String: Any] = [
+            "url": "https://example.com/cmux.zip",
+            "length": "1024",
+            "sparkle:version": displayVersion,
+            "sparkle:shortVersionString": displayVersion,
+        ]
+        let dict: [String: Any] = [
+            "title": "cmux \(displayVersion)",
+            "pubDate": "Wed, 25 Mar 2026 12:00:00 +0000",
+            "enclosure": enclosure,
+        ]
+        return SUAppcastItem(dictionary: dict)
+    }
+}
+#endif

Sources/Update/UpdateTestURLProtocol.swift → Packages/CmuxUpdater/Sources/CmuxUpdater/TestSupport/UpdateTestURLProtocol.swift

@@ -1,17 +1,21 @@
 #if DEBUG
 import Foundation
 
+/// A `URLProtocol` that serves a synthetic Sparkle appcast (and update archive) for UI tests,
+/// so an end-to-end update check can run against an in-process feed.
+///
+/// DEBUG-only test scaffolding. The feed contents are driven by `CMUX_UI_TEST_*` environment
+/// variables.
 final class UpdateTestURLProtocol: URLProtocol {
     static let host = "cmux.test"
     static let appcastPath = "/appcast.xml"
     static let updatePath = "/cmux-test.zip"
 
-    private static var isRegistered = false
-    private static let registrationLock = NSLock()
+    @MainActor private static var isRegistered = false
 
+    /// Registers the protocol once. Main-actor isolated so the one-time flag needs no lock.
+    @MainActor
     static func registerIfNeeded() {
-        registrationLock.lock()
-        defer { registrationLock.unlock() }
         guard !isRegistered else { return }
         URLProtocol.registerClass(UpdateTestURLProtocol.self)
         isRegistered = true

Packages/CmuxUpdater/Sources/CmuxUpdater/UpdateActionDelegate.swift

@@ -0,0 +1,17 @@
+/// The host-application actions the updater needs but cannot perform itself.
+///
+/// This is the dependency-inversion seam between the `CmuxUpdater` package and the app: the
+/// package calls up through this protocol instead of reaching `AppDelegate`/`TerminalController`
+/// directly. The app's delegate conforms and is injected into ``UpdateController`` (which holds
+/// it `weak`).
+@MainActor
+public protocol UpdateActionDelegate: AnyObject {
+    /// The user asked to retry after an update error. The host should re-initiate a check
+    /// through its normal entry point.
+    func updaterRequestsRetryCheckForUpdates()
+
+    /// Sparkle is about to relaunch the app to finish installing. The host should persist
+    /// session state, stop its terminal/runtime, and invalidate restorable state so the
+    /// relaunched instance starts cleanly.
+    func updaterWillRelaunchApplication()
+}

Packages/CmuxUpdater/Sources/CmuxUpdater/UpdateClock.swift

@@ -0,0 +1,23 @@
+/// An injectable clock for the updater's bounded, cancellable UI delays (minimum check
+/// display, "no updates" auto-dismiss, ready-timeout).
+///
+/// Production uses ``SystemUpdateClock`` (a real `Task.sleep`); tests inject a fake that
+/// returns immediately or coordinates timing, so delay-driven behavior is verified with no
+/// real waiting. The delays this clock drives are *intended* delays, never a poll or a
+/// "let state settle" hack.
+public protocol UpdateClock: Sendable {
+    /// Suspends for `duration`, throwing `CancellationError` if the surrounding task is
+    /// cancelled first.
+    func sleep(for duration: Duration) async throws
+}
+
+/// The production ``UpdateClock``, backed by `Task.sleep`.
+public struct SystemUpdateClock: UpdateClock {
+    /// Creates a system clock.
+    public init() {}
+
+    public func sleep(for duration: Duration) async throws {
+        // Bounded, cancellable, intended delay behind the UpdateClock seam (policy carve-out).
+        try await Task.sleep(for: duration)
+    }
+}