@lattices/cli 0.4.0 → 0.4.2

package/app/Sources/HandsOffSession.swift

@@ -97,6 +97,15 @@ final class HandsOffSession: ObservableObject {
     private var workerBuffer = ""
     private let workerQueue = DispatchQueue(label: "com.lattices.handsoff-worker", qos: .userInitiated)
     private var lastCueAt: Date = .distantPast
+    private var workerRoot: String? {
+        if let idx = CommandLine.arguments.firstIndex(of: "--lattices-cli-root"),
+           CommandLine.arguments.indices.contains(idx + 1) {
+            return CommandLine.arguments[idx + 1]
+        }
+
+        let devRoot = NSHomeDirectory() + "/dev/lattices"
+        return FileManager.default.fileExists(atPath: devRoot) ? devRoot : nil
+    }
 
     /// JSONL log for full turn data — ~/.lattices/handsoff.jsonl
     private let turnLogPath = NSHomeDirectory() + "/.lattices/handsoff.jsonl"
@@ -122,7 +131,7 @@ final class HandsOffSession: ObservableObject {
     // MARK: - Lifecycle
 
     func start() {
-        startWorker()
+        // Worker startup is lazy — only start it when a voice turn or cached cue needs it.
     }
 
     func setAudibleFeedbackEnabled(_ enabled: Bool) {
@@ -170,9 +179,10 @@ final class HandsOffSession: ObservableObject {
         }
     }
 
-    private func startWorker() {
+    @discardableResult
+    private func startWorker() -> Bool {
         if workerProcess?.isRunning == true, workerStdin != nil {
-            return
+            return true
         }
 
         let bunPaths = [
@@ -182,19 +192,24 @@ final class HandsOffSession: ObservableObject {
         ]
         guard let bunPath = bunPaths.first(where: { FileManager.default.isExecutableFile(atPath: $0) }) else {
             DiagnosticLog.shared.warn("HandsOff: bun not found, worker disabled")
-            return
+            return false
+        }
+
+        guard let workerRoot else {
+            DiagnosticLog.shared.warn("HandsOff: worker root not found, worker disabled")
+            return false
         }
 
-        let scriptPath = NSHomeDirectory() + "/dev/lattices/bin/handsoff-worker.ts"
+        let scriptPath = workerRoot + "/bin/handsoff-worker.ts"
         guard FileManager.default.fileExists(atPath: scriptPath) else {
             DiagnosticLog.shared.warn("HandsOff: worker script not found at \(scriptPath)")
-            return
+            return false
         }
 
         let proc = Process()
         proc.executableURL = URL(fileURLWithPath: bunPath)
         proc.arguments = ["run", scriptPath]
-        proc.currentDirectoryURL = URL(fileURLWithPath: NSHomeDirectory() + "/dev/lattices")
+        proc.currentDirectoryURL = URL(fileURLWithPath: workerRoot)
 
         var env = ProcessInfo.processInfo.environment
         env.removeValue(forKey: "CLAUDECODE")
@@ -211,7 +226,7 @@ final class HandsOffSession: ObservableObject {
             try proc.run()
         } catch {
             DiagnosticLog.shared.warn("HandsOff: failed to start worker — \(error)")
-            return
+            return false
         }
 
         workerProcess = proc
@@ -235,22 +250,29 @@ final class HandsOffSession: ObservableObject {
 
         // Handle worker crash → restart
         proc.terminationHandler = { [weak self] proc in
-            DiagnosticLog.shared.warn("HandsOff: worker exited (code \(proc.terminationStatus)), restarting in 2s")
-            self?.workerProcess = nil
-            self?.workerStdin = nil
+            guard let self else { return }
+            let keepWarm = self.audibleFeedbackEnabled || self.state != .idle
+            let suffix = keepWarm ? ", restarting in 2s" : ", staying idle"
+            DiagnosticLog.shared.warn("HandsOff: worker exited (code \(proc.terminationStatus))\(suffix)")
+            self.workerProcess = nil
+            self.workerStdin = nil
+            guard keepWarm else { return }
             DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
-                self?.startWorker()
+                self.startWorker()
             }
         }
 
         // Ping to verify
         sendToWorker(["cmd": "ping"])
         DiagnosticLog.shared.info("HandsOff: worker started (pid \(proc.processIdentifier))")
+        return true
     }
 
     // MARK: - Worker communication
 
     private var pendingCallback: (([String: Any]) -> Void)?
+    private var turnTimeoutWork: DispatchWorkItem?
+    private static let turnTimeoutSeconds: TimeInterval = 30
 
     private func sendToWorker(_ dict: [String: Any]) {
         guard let data = try? JSONSerialization.data(withJSONObject: dict),
@@ -335,17 +357,34 @@ final class HandsOffSession: ObservableObject {
         case .listening:
             finishListening()
         case .thinking:
-            DiagnosticLog.shared.info("HandsOff: busy, ignoring toggle")
+            cancelTurn()
         case .connecting:
             cancel()
         }
     }
 
     func cancel() {
+        cancelVoxSession()
         state = .idle
         DiagnosticLog.shared.info("HandsOff: cancelled")
     }
 
+    private func cancelTurn() {
+        turnTimeoutWork?.cancel()
+        turnTimeoutWork = nil
+        pendingCallback = nil
+        state = .idle
+        DiagnosticLog.shared.warn("HandsOff: turn cancelled by user")
+        playSound("Funk")
+    }
+
+    /// Cancel any active Vox recording session without transcribing.
+    private func cancelVoxSession() {
+        guard VoxClient.shared.activeSessionId != nil else { return }
+        DiagnosticLog.shared.info("HandsOff: cancelling Vox session")
+        VoxClient.shared.cancelSession()
+    }
+
     // MARK: - Voice capture
 
     private func beginListening() {
@@ -377,24 +416,46 @@ final class HandsOffSession: ObservableObject {
         }
     }
 
+    /// Guard against double-processing the transcript (session.final + completion can both deliver it).
+    private var turnProcessed = false
+
     private func startDictation() {
         state = .listening
         lastTranscript = nil
+        turnProcessed = false
         playSound("Tink")
 
         DiagnosticLog.shared.info("HandsOff: listening...")
 
         // Vox live session: startSession opens the mic, events flow on the start call ID.
-        // No partial transcripts — Vox transcribes after recording stops.
+        // session.final arrives via onProgress, then the same data arrives via completion.
+        // We process the transcript from whichever arrives first to be resilient against
+        // connection drops between the two.
         VoxClient.shared.startSession(
             onProgress: { [weak self] event, data in
                 DispatchQueue.main.async {
-                    if event == "session.state" {
+                    guard let self else { return }
+                    switch event {
+                    case "session.state":
                         let sessionState = data["state"] as? String ?? ""
                         DiagnosticLog.shared.info("HandsOff: session → \(sessionState)")
-                    }
-                    if event == "session.final", let text = data["text"] as? String {
-                        self?.lastTranscript = text
+                        // Vox cancelled the session (e.g. recording timeout)
+                        if sessionState == "cancelled" {
+                            let reason = data["reason"] as? String ?? "unknown"
+                            DiagnosticLog.shared.warn("HandsOff: Vox cancelled session — \(reason)")
+                            if self.state == .listening {
+                                self.state = .idle
+                                self.playSound("Basso")
+                            }
+                        }
+                    case "session.final":
+                        // Primary transcript delivery — process immediately
+                        if let text = data["text"] as? String, !text.isEmpty {
+                            self.lastTranscript = text
+                            self.deliverTranscript(text)
+                        }
+                    default:
+                        break
                     }
                 }
             },
@@ -405,24 +466,36 @@ final class HandsOffSession: ObservableObject {
                     case .success(let data):
                         let text = data["text"] as? String ?? ""
                         if text.isEmpty {
-                            self.state = .idle
-                            DiagnosticLog.shared.info("HandsOff: no speech detected")
+                            if !self.turnProcessed {
+                                self.state = .idle
+                                DiagnosticLog.shared.info("HandsOff: no speech detected")
+                            }
                         } else {
+                            // Fallback — deliver if session.final didn't already
                             self.lastTranscript = text
-                            DiagnosticLog.shared.info("HandsOff: heard → '\(text)'")
-                            self.appendChat(.user, text: text)
-                            self.processTurn(text)
+                            self.deliverTranscript(text)
                         }
                     case .failure(let error):
-                        self.state = .idle
-                        DiagnosticLog.shared.warn("HandsOff: session error — \(error.localizedDescription)")
-                        self.playSound("Basso")
+                        if !self.turnProcessed {
+                            self.state = .idle
+                            DiagnosticLog.shared.warn("HandsOff: session error — \(error.localizedDescription)")
+                            self.playSound("Basso")
+                        }
                     }
                 }
             }
         )
     }
 
+    /// Deliver transcript exactly once — called from both session.final and completion.
+    private func deliverTranscript(_ text: String) {
+        guard !turnProcessed else { return }
+        turnProcessed = true
+        DiagnosticLog.shared.info("HandsOff: heard → '\(text)'")
+        appendChat(.user, text: text)
+        processTurn(text)
+    }
+
     func finishListening() {
         guard state == .listening else { return }
         playSound("Tink")
@@ -433,6 +506,12 @@ final class HandsOffSession: ObservableObject {
 
     private func processTurn(_ transcript: String) {
         state = .thinking
+        guard startWorker() else {
+            state = .idle
+            DiagnosticLog.shared.warn("HandsOff: worker unavailable")
+            playSound("Basso")
+            return
+        }
         turnCount += 1
 
         let turnStart = Date()
@@ -449,9 +528,25 @@ final class HandsOffSession: ObservableObject {
             "history": conversationHistory,
         ]
 
+        // Start turn timeout — forcibly reset if worker never responds
+        turnTimeoutWork?.cancel()
+        let timeout = DispatchWorkItem { [weak self] in
+            guard let self, self.state == .thinking else { return }
+            DiagnosticLog.shared.warn("HandsOff: ⏱ turn \(self.turnCount) timed out after \(Int(Self.turnTimeoutSeconds))s")
+            self.pendingCallback = nil
+            self.state = .idle
+            self.playSound("Basso")
+        }
+        turnTimeoutWork = timeout
+        DispatchQueue.main.asyncAfter(deadline: .now() + Self.turnTimeoutSeconds, execute: timeout)
+
         sendToWorkerWithCallback(turnCmd) { [weak self] response in
             guard let self else { return }
 
+            // Cancel the timeout — we got a response
+            self.turnTimeoutWork?.cancel()
+            self.turnTimeoutWork = nil
+
             let turnMs = Int(Date().timeIntervalSince(turnStart) * 1000)
             DiagnosticLog.shared.info("HandsOff: ⏱ turn \(self.turnCount) complete — \(turnMs)ms")
 

package/app/Sources/HotkeyStore.swift

@@ -24,6 +24,7 @@ enum HotkeyAction: String, CaseIterable, Codable {
     case handsOff
     case unifiedWindow
     case hud
+    case mouseFinder
     // Layers
     case layer1, layer2, layer3, layer4, layer5, layer6, layer7, layer8, layer9
     case layerNext, layerPrev, layerTag
@@ -45,6 +46,7 @@ enum HotkeyAction: String, CaseIterable, Codable {
         case .handsOff:        return "Hands-Off Mode"
         case .unifiedWindow:   return "Unified Window"
         case .hud:             return "HUD"
+        case .mouseFinder:     return "Find Mouse"
         case .layer1:          return "Layer 1"
         case .layer2:          return "Layer 2"
         case .layer3:          return "Layer 3"
@@ -76,7 +78,7 @@ enum HotkeyAction: String, CaseIterable, Codable {
 
     var group: HotkeyGroup {
         switch self {
-        case .palette, .screenMap, .bezel, .cheatSheet, .desktopInventory, .omniSearch, .voiceCommand, .handsOff, .unifiedWindow, .hud: return .app
+        case .palette, .screenMap, .bezel, .cheatSheet, .desktopInventory, .omniSearch, .voiceCommand, .handsOff, .unifiedWindow, .hud, .mouseFinder: return .app
         case .layer1, .layer2, .layer3, .layer4, .layer5,
              .layer6, .layer7, .layer8, .layer9,
              .layerNext, .layerPrev, .layerTag: return .layers
@@ -96,6 +98,7 @@ enum HotkeyAction: String, CaseIterable, Codable {
         case .handsOff:        return 206
         case .unifiedWindow:   return 207
         case .hud:             return 208
+        case .mouseFinder:     return 209
         case .layer1:          return 101
         case .layer2:          return 102
         case .layer3:          return 103
@@ -231,6 +234,7 @@ class HotkeyStore: ObservableObject {
         bind(.handsOff, 46, cmdCtrl)          // Ctrl+Cmd+M
         bind(.omniSearch, 23, hyper)       // Hyper+5
         bind(.cheatSheet, 22, hyper)       // Hyper+6
+        bind(.mouseFinder, 26, hyper)      // Hyper+7
 
         // Layers: Cmd+Option+1-9
         let layerKeyCodes: [UInt32] = [18, 19, 20, 21, 23, 22, 26, 28, 25]

package/app/Sources/IntentEngine.swift

@@ -723,6 +723,43 @@ final class IntentEngine {
             }
         ))
 
+        // ── Find / Summon Mouse ────────────────────────────────
+
+        register(IntentDef(
+            name: "find_mouse",
+            description: "Show a sonar pulse at the current mouse cursor position",
+            examples: [
+                "where's my mouse",
+                "find the cursor",
+                "I lost my mouse",
+                "find mouse",
+                "show cursor"
+            ],
+            slots: [],
+            handler: { _ in
+                DispatchQueue.main.async { MouseFinder.shared.find() }
+                let pos = NSEvent.mouseLocation
+                return .object(["ok": .bool(true), "x": .int(Int(pos.x)), "y": .int(Int(pos.y))])
+            }
+        ))
+
+        register(IntentDef(
+            name: "summon_mouse",
+            description: "Warp the mouse cursor to the center of the screen",
+            examples: [
+                "summon mouse",
+                "bring the cursor here",
+                "center the mouse",
+                "mouse come here",
+                "bring mouse back"
+            ],
+            slots: [],
+            handler: { _ in
+                DispatchQueue.main.async { MouseFinder.shared.summon() }
+                return .object(["ok": .bool(true)])
+            }
+        ))
+
         // ── Undo / Restore ─────────────────────────────────────
 
         register(IntentDef(

package/app/Sources/LatticesApi.swift

@@ -1818,6 +1818,46 @@ final class LatticesApi {
 
         // ── Meta endpoint ───────────────────────────────────────
 
+        // ── Mouse Finder ────────────────────────────────────────
+
+        api.register(Endpoint(
+            method: "mouse.find",
+            description: "Show a sonar pulse at the current mouse cursor position",
+            access: .read,
+            params: [],
+            returns: .ok,
+            handler: { _ in
+                DispatchQueue.main.async { MouseFinder.shared.find() }
+                let pos = NSEvent.mouseLocation
+                return .object(["ok": .bool(true), "x": .int(Int(pos.x)), "y": .int(Int(pos.y))])
+            }
+        ))
+
+        api.register(Endpoint(
+            method: "mouse.summon",
+            description: "Warp the mouse cursor to screen center (or a given point) and show a sonar pulse",
+            access: .mutate,
+            params: [
+                Param(name: "x", type: "int", required: false, description: "Target X coordinate (screen, bottom-left origin)"),
+                Param(name: "y", type: "int", required: false, description: "Target Y coordinate (screen, bottom-left origin)"),
+            ],
+            returns: .ok,
+            handler: { params in
+                let target: CGPoint?
+                if let x = params?["x"]?.intValue, let y = params?["y"]?.intValue {
+                    target = CGPoint(x: CGFloat(x), y: CGFloat(y))
+                } else {
+                    target = nil
+                }
+                DispatchQueue.main.async { MouseFinder.shared.summon(to: target) }
+                let pos = target ?? {
+                    let screen = NSScreen.main ?? NSScreen.screens[0]
+                    return CGPoint(x: screen.frame.midX, y: screen.frame.midY)
+                }()
+                return .object(["ok": .bool(true), "x": .int(Int(pos.x)), "y": .int(Int(pos.y))])
+            }
+        ))
+
         api.register(Endpoint(
             method: "api.schema",
             description: "Get the full API schema including all methods and models",

package/app/Sources/MainView.swift

@@ -283,27 +283,50 @@ struct MainView: View {
 
     private var actionsSection: some View {
         VStack(spacing: 0) {
-            ActionRow(shortcut: "1", label: "Command Palette", hotkey: hotkeyLabel(.palette), icon: "command", accentColor: Palette.running) {
-                CommandPaletteWindow.shared.toggle()
-            }
-            ActionRow(shortcut: "2", label: "Screen Map", hotkey: hotkeyLabel(.screenMap), icon: "rectangle.3.group") {
-                ScreenMapWindowController.shared.toggle()
-            }
-            ActionRow(shortcut: "3", label: "Desktop Inventory", hotkey: hotkeyLabel(.desktopInventory), icon: "rectangle.split.2x1") {
-                CommandModeWindow.shared.toggle()
-            }
-            ActionRow(shortcut: "4", label: "Window Bezel", hotkey: hotkeyLabel(.bezel), icon: "macwindow") {
-                WindowBezel.showBezelForFrontmostWindow()
+            HStack {
+                Text("Quick Actions")
+                    .font(Typo.monoBold(10))
+                    .foregroundColor(Palette.textMuted)
+
+                Spacer()
+
+                Button("Help & shortcuts") {
+                    ScreenMapWindowController.shared.showPage(.docs)
+                }
+                .buttonStyle(.plain)
+                .font(Typo.mono(9))
+                .foregroundColor(Palette.textMuted)
             }
-            ActionRow(shortcut: "5", label: "Cheat Sheet", hotkey: hotkeyLabel(.cheatSheet), icon: "keyboard") {
-                CheatSheetHUD.shared.toggle()
+            .padding(.horizontal, 14)
+            .padding(.top, 10)
+            .padding(.bottom, 6)
+
+            ActionRow(
+                label: "Command Palette",
+                detail: "Launch, attach, and control projects",
+                hotkeyTokens: hotkeyTokens(.palette),
+                icon: "command",
+                accentColor: Palette.running
+            ) {
+                CommandPaletteWindow.shared.toggle()
             }
-            ActionRow(shortcut: "6", label: "Omni Search", hotkey: hotkeyLabel(.omniSearch), icon: "magnifyingglass", accentColor: Palette.running) {
-                OmniSearchWindow.shared.toggle()
+            ActionRow(
+                label: "Workspace",
+                detail: "Screen map, inventory, and window context",
+                hotkeyTokens: hotkeyTokens(.unifiedWindow),
+                icon: "square.grid.2x2",
+                accentColor: Palette.text
+            ) {
+                ScreenMapWindowController.shared.showPage(.home)
             }
-            ActionRow(shortcut: "7", label: "Voice Command", hotkey: hotkeyLabel(.voiceCommand), icon: "mic", accentColor: AudioLayer.shared.isListening ? Palette.running : Palette.textDim) {
-                let audio = AudioLayer.shared
-                if audio.isListening { audio.stopVoiceCommand() } else { audio.startVoiceCommand() }
+            ActionRow(
+                label: "Assistant",
+                detail: "Search now, or use voice when you need it",
+                hotkeyTokens: hotkeyTokens(.omniSearch),
+                icon: "magnifyingglass",
+                accentColor: AudioLayer.shared.isListening ? Palette.running : Palette.textDim
+            ) {
+                showAssistant()
             }
         }
         .padding(.vertical, 4)
@@ -351,9 +374,38 @@ struct MainView: View {
         .buttonStyle(.plain)
     }
 
-    private func hotkeyLabel(_ action: HotkeyAction) -> String? {
-        guard let binding = HotkeyStore.shared.bindings[action] else { return nil }
-        return binding.displayParts.joined(separator: "")
+    private func hotkeyTokens(_ action: HotkeyAction) -> [String] {
+        guard let binding = HotkeyStore.shared.bindings[action],
+              let key = binding.displayParts.last else { return [] }
+
+        let modifiers = Set(binding.displayParts.dropLast())
+        if modifiers == Set(["Ctrl", "Option", "Shift", "Cmd"]) {
+            return ["Hyper", shortenHotkeyToken(key)]
+        }
+
+        return binding.displayParts.map(shortenHotkeyToken)
+    }
+
+    private func shortenHotkeyToken(_ token: String) -> String {
+        switch token {
+        case "Cmd": return "⌘"
+        case "Shift": return "⇧"
+        case "Option": return "⌥"
+        case "Ctrl": return "⌃"
+        case "Return": return "↩"
+        case "Escape": return "Esc"
+        case "Space": return "Space"
+        default: return token
+        }
+    }
+
+    private func showAssistant() {
+        if AudioLayer.shared.isListening || VoiceCommandWindow.shared.isVisible {
+            VoiceCommandWindow.shared.toggle()
+            return
+        }
+
+        OmniSearchWindow.shared.show()
     }
 
     // MARK: - Empty state