release: v0.3.1 — gesture stream recovery (touch-stream resilience)

Field bug (second laptop, diagnosed from power-debug logs 2026-07-16): the
MultitouchSupport stream died 2026-07-15 with NO system sleep afterwards, so
v0.3.0's wake-only recovery never fired and gestures stayed dead until relaunch
while permissions showed green (input side dead, not policy — route() logged
nothing). The specific killer is unconfirmed (owner: probably no display
change), so recovery now detects death by evidence instead of one cause:

- StreamHealthPolicy (TilerCore, TDD, 15 tests): device-drift set-compare +
  silence self-heal gates (silent ≥ 10 min, pointer/scroll HID ≤ 60 s old,
  unlocked, ≥ 10 min cooldown — external-mouse churn capped).
- TouchStream: optional MTDeviceGetDeviceID symbol (probe-verified present,
  IDs stable), attachedSignature captured at start, currentSignature() fresh
  enumeration (count-only fallback if the symbol ever vanishes), frame
  liveness clock stamped by the C callback (NSLock-guarded).
- AppDelegate guardian: shared rebuildTouchStream(reason:) — wake path folded
  in; debounced display-reconfiguration rebuild; unlock drift check; 60 s
  watchdog (drift, then self-heal policy); screen-lock tracking.
- Diagnostics (owner: "не жалей отладки"): stream start/rebuild lines with
  device IDs and reasons, drift old→new, display-change screen counts,
  self-heal evidence; healthy ticks log nothing; NSLog mirrors rebuilds.

Specs: app-shell "Gesture recovery after system wake" broadened to "Gesture
stream recovery" (4 triggers, no-false-positive rule); power diagnostic
logging gains the stream lifecycle. Change archived as
2026-07-16-fix-touch-stream-resilience; version 0.3.0 → 0.3.1.

Verified: 162 non-AX tests green; power-acceptance + run-acceptance (signed
.app) ALL PASS; smoke on the signed build — launch v0.3.1 + device-ID line
logged, zero spurious rebuilds across a watchdog tick. Field verification of
the original death happens on the second laptop after this release.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: alexnskcody

CLAUDE.md

@@ -3,12 +3,12 @@
 **Start here every session:**
 1. Read `openspec/project.md` (context, environment, workflow rules).
 2. Check the active change listed in `openspec/project.md`. Currently:
-   **none** — `add-power-control` shipped as v0.3.0 (2026-07-10) and is archived
-   under `openspec/changes/archive/2026-07-10-add-power-control/` with full design
-   history. Start new work as a fresh change folder. v0.1 (MVP), v0.2 (shell +
-   calibration), and v0.3 (power control) are all archived under
-   `openspec/changes/archive/`; `openspec/specs/` is the current merged truth
-   (scenarios = required tests). The owner's verbatim original assignment is
+   **none** — latest shipped: `fix-touch-stream-resilience` as v0.3.1 (2026-07-16,
+   gesture stream recovery; field verification on the owner's second laptop still
+   pending) and `add-power-control` as v0.3.0 (2026-07-10), both archived under
+   `openspec/changes/archive/` with full design history. Start new work as a fresh
+   change folder. `openspec/specs/` is the current merged truth (scenarios =
+   required tests). The owner's verbatim original assignment is
    `archive/2026-07-04-add-tiler-mvp/brief.md`.
 3. New work starts as a new change folder (kebab-case) with proposal/design/tasks/spec
    deltas; update `tasks.md` checkboxes **as you work** and keep specs in sync with

Scripts/make-app.sh

@@ -13,7 +13,7 @@ cd "$(dirname "$0")/.."
 
 IDENTITY="Apple Development: alexnsk@gmail.com (PHYV972T38)"
 BUNDLE_ID="pro.amilabs.tilerx"
-VERSION="0.3.0"
+VERSION="0.3.1"
 BUILD_DATE="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 APP="build/Tiler.app"
 

Sources/Tiler/AppDelegate.swift

@@ -5,7 +5,7 @@ import TilerSystem
 
 @MainActor
 final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
-    static let version = "0.3.0"
+    static let version = "0.3.1"
 
     private var statusItem: NSStatusItem?
     private var touchStream: TouchStream?
@@ -52,6 +52,11 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
     private var lastLoggedPower: String?
     private var lastOnBattery = false
     private var debugStateTimer: DispatchSourceTimer?   // 30 s idle-state log while debug logging is on
+    // Touch-stream guardian (gesture stream recovery spec).
+    private var streamGuardTimer: DispatchSourceTimer?
+    private var displayChangeDebounce: DispatchWorkItem?
+    private var lastStreamRebuild = Date.distantPast
+    private var screenLockedNow = false
 
     func applicationDidFinishLaunching(_ notification: Notification) {
         setUpStatusItem()
@@ -65,10 +70,14 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
         handleDebugWindowArgs()
     }
 
-    /// The MultitouchSupport contact stream goes stale across a real system sleep
-    /// (its device refs die), so gestures stop working until relaunch — observed in
-    /// the diagnostic log at gate 4.2. Rebuild the stream shortly after wake (a small
-    /// delay lets the HID stack re-enumerate the trackpad first).
+    /// The MultitouchSupport contact stream goes stale without the app crashing:
+    /// across a real system sleep (gate 4.2), and — observed in the field
+    /// 2026-07-15 — with no system sleep at all, after which v0.3.0's wake-only
+    /// recovery never fired and gestures stayed dead until relaunch. The guardian
+    /// rebuilds the stream on every trigger that can invalidate device refs (wake,
+    /// display reconfiguration) and detects silent death by evidence: device-ID
+    /// drift, or prolonged frame silence while the cursor is demonstrably moving
+    /// (StreamHealthPolicy decides; ~60 s watchdog).
     private func setUpTouchWakeRecovery() {
         NSWorkspace.shared.notificationCenter.addObserver(
             forName: NSWorkspace.didWakeNotification, object: nil, queue: .main
@@ -77,20 +86,104 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
                 self?.reconcileStuckSleepDisabled()   // clear a leftover clamshell flag on wake
                 self?.logSleepBlockers("wake")
                 DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) {
-                    self?.restartTouchStreamAfterWake()
+                    self?.rebuildTouchStream(reason: "wake")
                 }
             }
         }
+        // Dock/undock/resolution changes re-enumerate HID devices; the events come
+        // in bursts, so debounce before the (unconditional) rebuild.
+        NotificationCenter.default.addObserver(
+            forName: NSApplication.didChangeScreenParametersNotification, object: nil, queue: .main
+        ) { [weak self] _ in
+            MainActor.assumeIsolated {
+                guard let self else { return }
+                self.displayChangeDebounce?.cancel()
+                let work = DispatchWorkItem { [weak self] in
+                    guard let self else { return }
+                    self.plog("display change screens=\(NSScreen.screens.count)")
+                    self.rebuildTouchStream(reason: "display change")
+                }
+                self.displayChangeDebounce = work
+                DispatchQueue.main.asyncAfter(deadline: .now() + 1.5, execute: work)
+            }
+        }
+        // Screen lock state feeds the self-heal policy; unlock also drift-checks
+        // (a topology change while locked would otherwise wait for the watchdog).
+        let dnc = DistributedNotificationCenter.default()
+        dnc.addObserver(forName: Notification.Name("com.apple.screenIsLocked"),
+                        object: nil, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated { self?.screenLockedNow = true }
+        }
+        dnc.addObserver(forName: Notification.Name("com.apple.screenIsUnlocked"),
+                        object: nil, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated {
+                self?.screenLockedNow = false
+                DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
+                    self?.rebuildTouchStreamIfDrifted(context: "unlock")
+                }
+            }
+        }
+        let timer = DispatchSource.makeTimerSource(queue: .main)
+        timer.schedule(deadline: .now() + 60, repeating: 60)
+        timer.setEventHandler { [weak self] in MainActor.assumeIsolated { self?.streamGuardTick() } }
+        timer.resume()
+        streamGuardTimer = timer
+    }
+
+    /// One watchdog pass: a precise drift check first, then the silence heuristic.
+    private func streamGuardTick() {
+        guard let stream = touchStream else { return }   // no trackpad → nothing to guard
+        if rebuildTouchStreamIfDrifted(context: "watchdog") { return }
+        guard let silent = stream.silentSeconds() else { return }
+        let hidAgo = Self.secondsSinceHIDActivity()
+        if StreamHealthPolicy.shouldSelfHeal(
+            silentFor: silent,
+            hidAgo: hidAgo,
+            sinceLastRebuild: Date().timeIntervalSince(lastStreamRebuild),
+            screenLocked: screenLockedNow
+        ) {
+            plog("touch self-heal: silent=\(Int(silent))s hid=\(hidAgo.map { String(Int($0)) } ?? "?")s")
+            rebuildTouchStream(reason: "self-heal")
+        }
     }
 
-    private func restartTouchStreamAfterWake() {
+    /// Seconds since the session last saw pointer/scroll HID activity — the
+    /// "user is at the machine" evidence for the self-heal policy.
+    private static func secondsSinceHIDActivity() -> Double? {
+        let types: [CGEventType] = [.mouseMoved, .scrollWheel]
+        let ages = types.map {
+            CGEventSource.secondsSinceLastEventType(.combinedSessionState, eventType: $0)
+        }.filter { $0 >= 0 }
+        return ages.min()
+    }
+
+    /// Drift check: rebuild only when a fresh enumeration differs from the devices
+    /// the stream attached to. Returns true when a rebuild was performed.
+    @discardableResult
+    private func rebuildTouchStreamIfDrifted(context: String) -> Bool {
+        guard let stream = touchStream else { return false }
+        let attached = stream.attachedSignature
+        let current = stream.currentSignature()
+        guard StreamHealthPolicy.deviceDrift(attached: attached, current: current) else { return false }
+        plog("touch stream drift (\(context)): \(attached) -> \(current ?? [])")
+        rebuildTouchStream(reason: "device drift")
+        return true
+    }
+
+    /// Shared rebuild path for every trigger (wake / display change / drift /
+    /// self-heal): stop + start builds a fresh device list; on failure fall back to
+    /// a full pipeline rebuild.
+    private func rebuildTouchStream(reason: String) {
         guard let stream = touchStream else { return }   // no trackpad → nothing to do
+        lastStreamRebuild = Date()
         stream.stop()
         do {
-            try stream.start()   // start() builds a fresh device list
-            plog("touch stream restarted after wake")
+            try stream.start()
+            NSLog("Tiler: touch stream rebuilt (%@)", reason)
+            plog("touch stream rebuilt (\(reason)) devices=\(stream.attachedSignature)")
         } catch {
-            plog("touch stream restart failed, rebuilding pipeline: \(error)")
+            NSLog("Tiler: touch stream rebuild failed (%@): %@", reason, "\(error)")
+            plog("touch stream rebuild failed (\(reason)): \(error), rebuilding pipeline")
             startTouchPipeline()
         }
     }
@@ -288,6 +381,8 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
              + "power=\(power.percent.map(String.init) ?? "-")% \(power.onBattery ? "battery" : "AC") "
              + "lid=\(SystemPower.lidClosed() ? "closed" : "open") floor=\(settings.batteryFloorPercent) "
              + "display=\(settings.keepDisplayAwake) sleepDisabled=\(DisableSleepGovernor.sleepDisabledNow())")
+        // The pipeline started before powerLog existed — record the stream identity now.
+        if let stream = touchStream { plog("touch stream devices=\(stream.attachedSignature)") }
         observeSystemPowerEvents()
         logSleepBlockers("launch")
         refreshDebugStateTimer()
@@ -745,6 +840,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate, NSMenuDelegate {
             try stream.start()
             touchStream = stream
             NSLog("Tiler: touch stream started")
+            plog("touch stream started devices=\(stream.attachedSignature)")
         } catch {
             // No trackpad / framework change: gestures unavailable, app stays alive.
             NSLog("Tiler: touch stream unavailable: \(error)")

Sources/TilerCore/StreamHealthPolicy.swift

@@ -0,0 +1,38 @@
+import Foundation
+
+/// Pure decisions for touch-stream recovery (app-shell "Gesture stream recovery").
+/// The system layer feeds in device signatures and ages; this decides whether the
+/// stream must be rebuilt. Field context: the MultitouchSupport stream can die
+/// without a system sleep (observed 2026-07-15), so recovery cannot key on wake
+/// alone — it detects death by evidence: stale device identity, or prolonged frame
+/// silence while the user is demonstrably at the machine.
+public enum StreamHealthPolicy {
+
+    /// A fresh enumeration that differs from what the stream attached to means the
+    /// attached refs are stale — rebuild. Signatures are device-ID multisets
+    /// (sorted-compare; order carries no meaning). `current == nil` means the fresh
+    /// enumeration failed: no information, never drift.
+    public static func deviceDrift(attached: [UInt64], current: [UInt64]?) -> Bool {
+        guard let current else { return false }
+        return attached.sorted() != current.sorted()
+    }
+
+    /// Silence self-heal: rebuild only when the stream has been frame-silent for
+    /// `minSilence` while pointer/scroll HID activity is at most `maxHIDAge` old
+    /// (the user is moving the cursor, we hear nothing) on an unlocked screen, and
+    /// the previous rebuild is at least `cooldown` behind — an external-mouse-only
+    /// user legitimately produces "silent trackpad + live cursor" forever, and the
+    /// cooldown caps that churn at one idempotent stop/start per period.
+    public static func shouldSelfHeal(
+        silentFor: TimeInterval,
+        hidAgo: TimeInterval?,
+        sinceLastRebuild: TimeInterval,
+        screenLocked: Bool,
+        minSilence: TimeInterval = 600,
+        maxHIDAge: TimeInterval = 60,
+        cooldown: TimeInterval = 600
+    ) -> Bool {
+        guard !screenLocked, let hidAgo else { return false }
+        return silentFor >= minSilence && hidAgo <= maxHIDAge && sinceLastRebuild >= cooldown
+    }
+}

Sources/TilerSystem/TouchStream.swift

@@ -13,6 +13,7 @@ public final class TouchStream: @unchecked Sendable {
     typealias RegisterCallbackFn = @convention(c) (TLMTDeviceRef, TLMTContactCallback?) -> Void
     typealias StartFn = @convention(c) (TLMTDeviceRef, Int32) -> Void
     typealias StopFn = @convention(c) (TLMTDeviceRef) -> Void
+    typealias GetDeviceIDFn = @convention(c) (TLMTDeviceRef, UnsafeMutablePointer<UInt64>) -> Int32
 
     public enum StreamError: Error, CustomStringConvertible {
         case frameworkUnavailable(String)
@@ -35,10 +36,18 @@ public final class TouchStream: @unchecked Sendable {
     private var deviceList: CFMutableArray?
     private var running = false
 
+    // Liveness/identity state for the stream guardian. Written from the C callback's
+    // MultitouchSupport thread and start(); read from the main actor — lock-guarded.
+    private let stateLock = NSLock()
+    private var lastFrameTime: CFAbsoluteTime?
+    private var startedTime: CFAbsoluteTime?
+    private var attachedIDs: [UInt64] = []
+
     private let createList: CreateListFn
     private let registerCallback: RegisterCallbackFn
     private let startDevice: StartFn
     private let stopDevice: StopFn
+    private let getDeviceID: GetDeviceIDFn?   // optional: absent symbol degrades drift to count-only
 
     /// `handler` is called on the stream's serial queue for every contact frame.
     public init(handler: @escaping @Sendable (TouchFrame) -> Void) throws {
@@ -60,6 +69,7 @@ public final class TouchStream: @unchecked Sendable {
         registerCallback = try sym("MTRegisterContactFrameCallback", RegisterCallbackFn.self)
         startDevice = try sym("MTDeviceStart", StartFn.self)
         stopDevice = try sym("MTDeviceStop", StopFn.self)
+        getDeviceID = dlsym(lib, "MTDeviceGetDeviceID").map { unsafeBitCast($0, to: GetDeviceIDFn.self) }
     }
 
     public func start() throws {
@@ -79,6 +89,13 @@ public final class TouchStream: @unchecked Sendable {
             startDevice(dev, 0)
         }
         running = true
+
+        let signature = signature(of: devices)
+        stateLock.lock()
+        attachedIDs = signature
+        startedTime = CFAbsoluteTimeGetCurrent()
+        lastFrameTime = nil
+        stateLock.unlock()
     }
 
     public func stop() {
@@ -97,10 +114,56 @@ public final class TouchStream: @unchecked Sendable {
         stop()
     }
 
+    // MARK: - Guardian support (identity + liveness)
+
+    /// Device signature: sorted real device IDs when `MTDeviceGetDeviceID` is
+    /// available, else the degenerate `[count]` (drift then means count change only).
+    private func signature(of devs: [TLMTDeviceRef]) -> [UInt64] {
+        guard let getDeviceID else { return [UInt64(devs.count)] }
+        return devs.compactMap { dev in
+            var id: UInt64 = 0
+            return getDeviceID(dev, &id) == 0 ? id : nil
+        }.sorted()
+    }
+
+    /// The signature captured by the last successful start().
+    public var attachedSignature: [UInt64] {
+        stateLock.lock(); defer { stateLock.unlock() }
+        return attachedIDs
+    }
+
+    /// Fresh enumeration, same encoding as `attachedSignature`; nil when the device
+    /// list cannot be built (no information — the policy never treats nil as drift).
+    public func currentSignature() -> [UInt64]? {
+        guard let listUnmanaged = createList() else { return nil }
+        let list = listUnmanaged.takeRetainedValue()
+        let count = CFArrayGetCount(list)
+        let devs = (0..<count).map { i in
+            TLMTDeviceRef(mutating: CFArrayGetValueAtIndex(list, i)!)
+        }
+        return signature(of: devs)
+    }
+
+    /// Seconds since the stream last delivered a contact frame — counted from the
+    /// last start() when no frame arrived yet, so a fresh stream is never
+    /// instantly "long silent". Nil before the first start().
+    public func silentSeconds(now: CFAbsoluteTime = CFAbsoluteTimeGetCurrent()) -> Double? {
+        stateLock.lock(); defer { stateLock.unlock() }
+        guard let reference = lastFrameTime ?? startedTime else { return nil }
+        return max(0, now - reference)
+    }
+
+    private func noteFrame() {
+        stateLock.lock()
+        lastFrameTime = CFAbsoluteTimeGetCurrent()
+        stateLock.unlock()
+    }
+
     // MARK: - C callback plumbing
 
     private static let contactCallback: TLMTContactCallback = { device, touches, numTouches, timestamp, _ in
         guard let stream = TouchStream.current else { return 0 }
+        stream.noteFrame()
         let deviceID = UInt64(UInt(bitPattern: device))
         var contacts: [Contact] = []
         if let touches, numTouches > 0 {