@lattices/cli 0.3.0 → 0.4.0

package/app/Sources/ScreenMapWindowController.swift

@@ -78,6 +78,28 @@ final class ScreenMapWindowController: ObservableObject {
         show()
     }
 
+    /// Open screen map focused on a specific window.
+    func showWindow(wid: UInt32) {
+        activePage = .screenMap
+        show()
+
+        // Avoid overlapping the voice panel — nudge screen map below it
+        if let w = window, let voicePanel = VoiceCommandWindow.shared.panel, voicePanel.isVisible {
+            let voiceBottom = voicePanel.frame.minY
+            let mapFrame = w.frame
+            if mapFrame.maxY > voiceBottom - 10 {
+                // Position just below the voice panel
+                let newY = voiceBottom - mapFrame.height - 16
+                w.setFrameOrigin(NSPoint(x: mapFrame.origin.x, y: max(newY, 40)))
+            }
+        }
+
+        // Select after a brief delay so the controller has time to populate
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.15) { [weak self] in
+            self?.controller?.selectSingle(wid)
+        }
+    }
+
     func close() {
         controller?.endPreview()
         window?.orderOut(nil)

package/app/Sources/SessionLayerStore.swift

@@ -0,0 +1,285 @@
+import AppKit
+
+// MARK: - WindowRef
+
+struct WindowRef: Codable, Identifiable {
+    let id: String
+
+    // ── Intent (stable, survives restarts) ──
+    var app: String
+    var contentHint: String?
+    var tile: String?
+    var display: Int?
+
+    // ── Runtime (ephemeral, filled when window is live) ──
+    var wid: UInt32?
+    var pid: Int32?
+    var title: String?
+    var frame: WindowFrame?
+
+    init(id: String = UUID().uuidString, app: String, contentHint: String? = nil,
+         tile: String? = nil, display: Int? = nil,
+         wid: UInt32? = nil, pid: Int32? = nil, title: String? = nil, frame: WindowFrame? = nil) {
+        self.id = id
+        self.app = app
+        self.contentHint = contentHint
+        self.tile = tile
+        self.display = display
+        self.wid = wid
+        self.pid = pid
+        self.title = title
+        self.frame = frame
+    }
+}
+
+// MARK: - SessionLayer
+
+struct SessionLayer: Identifiable, Codable {
+    let id: String
+    var name: String
+    var windows: [WindowRef]
+
+    init(id: String = UUID().uuidString, name: String, windows: [WindowRef] = []) {
+        self.id = id
+        self.name = name
+        self.windows = windows
+    }
+}
+
+// MARK: - SessionLayerStore
+
+final class SessionLayerStore: ObservableObject {
+    static let shared = SessionLayerStore()
+
+    @Published var layers: [SessionLayer] = []
+    @Published var activeIndex: Int = -1
+
+    private init() {
+        // Listen for window changes to reconcile stale refs
+        EventBus.shared.subscribe { [weak self] event in
+            if case .windowsChanged = event {
+                DispatchQueue.main.async {
+                    self?.reconcile()
+                }
+            }
+        }
+    }
+
+    // MARK: - CRUD
+
+    @discardableResult
+    func create(name: String, windows: [WindowRef] = []) -> SessionLayer {
+        let layer = SessionLayer(name: name, windows: windows)
+        layers.append(layer)
+        DiagnosticLog.shared.info("SessionLayerStore: created '\(name)' with \(windows.count) refs")
+        // If this is the first layer, activate it
+        if layers.count == 1 { activeIndex = 0 }
+        return layer
+    }
+
+    func delete(id: String) {
+        guard let idx = layers.firstIndex(where: { $0.id == id }) else { return }
+        // Clear layer tags for windows in this layer
+        for ref in layers[idx].windows {
+            if let wid = ref.wid {
+                DesktopModel.shared.removeLayerTag(wid: wid)
+            }
+        }
+        layers.remove(at: idx)
+        // Adjust activeIndex
+        if layers.isEmpty {
+            activeIndex = -1
+        } else if activeIndex >= layers.count {
+            activeIndex = layers.count - 1
+        }
+    }
+
+    func rename(id: String, name: String) {
+        guard let idx = layers.firstIndex(where: { $0.id == id }) else { return }
+        layers[idx].name = name
+    }
+
+    func clear() {
+        DesktopModel.shared.clearLayerTags()
+        layers.removeAll()
+        activeIndex = -1
+        LayerBezel.shared.invalidateCache()
+    }
+
+    func layerById(_ id: String) -> SessionLayer? {
+        layers.first { $0.id == id }
+    }
+
+    func layerByName(_ name: String) -> SessionLayer? {
+        layers.first { $0.name.localizedCaseInsensitiveCompare(name) == .orderedSame }
+    }
+
+    // MARK: - Window Management
+
+    func assign(ref: WindowRef, toLayerId id: String) {
+        guard let idx = layers.firstIndex(where: { $0.id == id }) else { return }
+        layers[idx].windows.append(ref)
+        if let wid = ref.wid {
+            DesktopModel.shared.assignLayer(wid: wid, layerId: layers[idx].name)
+        }
+    }
+
+    func assignByWid(_ wid: UInt32, toLayerId id: String) {
+        guard let idx = layers.firstIndex(where: { $0.id == id }) else { return }
+        guard let entry = DesktopModel.shared.windows[wid] else { return }
+        // Don't add duplicates
+        if layers[idx].windows.contains(where: { $0.wid == wid }) { return }
+        let ref = WindowRef(
+            app: entry.app,
+            contentHint: entry.title,
+            wid: entry.wid,
+            pid: entry.pid,
+            title: entry.title,
+            frame: entry.frame
+        )
+        layers[idx].windows.append(ref)
+        DesktopModel.shared.assignLayer(wid: wid, layerId: layers[idx].name)
+    }
+
+    func remove(refId: String, fromLayerId id: String) {
+        guard let idx = layers.firstIndex(where: { $0.id == id }) else { return }
+        if let refIdx = layers[idx].windows.firstIndex(where: { $0.id == refId }) {
+            if let wid = layers[idx].windows[refIdx].wid {
+                DesktopModel.shared.removeLayerTag(wid: wid)
+            }
+            layers[idx].windows.remove(at: refIdx)
+        }
+    }
+
+    func tagFrontmostWindow() {
+        guard let frontApp = NSWorkspace.shared.frontmostApplication,
+              frontApp.bundleIdentifier != "com.arach.lattices" else { return }
+
+        let pid = frontApp.processIdentifier
+        // Find the frontmost window for this app
+        guard let entry = DesktopModel.shared.windows.values
+            .first(where: { $0.pid == pid }) else { return }
+
+        // If no layers exist, create one
+        if layers.isEmpty {
+            create(name: "Layer 1")
+        }
+
+        // If no active layer, use first
+        let targetIndex = activeIndex >= 0 ? activeIndex : 0
+        guard targetIndex < layers.count else { return }
+
+        let layerId = layers[targetIndex].id
+        assignByWid(entry.wid, toLayerId: layerId)
+        DiagnosticLog.shared.info("SessionLayerStore: tagged \(entry.app) '\(entry.title)' → '\(layers[targetIndex].name)'")
+
+        // Show bezel feedback
+        let allNames = layers.map(\.name)
+        LayerBezel.shared.show(
+            label: layers[targetIndex].name,
+            index: targetIndex,
+            total: layers.count,
+            allLabels: allNames
+        )
+    }
+
+    // MARK: - Switching
+
+    func switchTo(index: Int) {
+        guard index >= 0, index < layers.count else { return }
+        activeIndex = index
+
+        DesktopModel.shared.poll()
+
+        var resolved: [(wid: UInt32, pid: Int32)] = []
+        for i in layers[index].windows.indices {
+            if let r = resolve(&layers[index].windows[i]) {
+                resolved.append(r)
+            }
+        }
+
+        if !resolved.isEmpty {
+            WindowTiler.raiseWindowsAndReactivate(windows: resolved)
+        }
+
+        let allNames = layers.map(\.name)
+        LayerBezel.shared.show(
+            label: layers[index].name,
+            index: index,
+            total: layers.count,
+            allLabels: allNames
+        )
+
+        DiagnosticLog.shared.info("SessionLayerStore: switched to '\(layers[index].name)' (\(resolved.count)/\(layers[index].windows.count) resolved)")
+    }
+
+    func cycleNext() {
+        guard !layers.isEmpty else { return }
+        let next = (activeIndex + 1) % layers.count
+        switchTo(index: next)
+    }
+
+    func cyclePrev() {
+        guard !layers.isEmpty else { return }
+        let prev = activeIndex <= 0 ? layers.count - 1 : activeIndex - 1
+        switchTo(index: prev)
+    }
+
+    // MARK: - Resolution
+
+    private func resolve(_ ref: inout WindowRef) -> (wid: UInt32, pid: Int32)? {
+        // 1. Fast path: wid still valid
+        if let wid = ref.wid, let entry = DesktopModel.shared.windows[wid] {
+            ref.pid = entry.pid
+            ref.title = entry.title
+            ref.frame = entry.frame
+            return (wid, entry.pid)
+        }
+
+        // 2. Re-resolve by app + contentHint
+        if let entry = DesktopModel.shared.windowForApp(app: ref.app, title: ref.contentHint) {
+            ref.wid = entry.wid
+            ref.pid = entry.pid
+            ref.title = entry.title
+            ref.frame = entry.frame
+            DesktopModel.shared.assignLayer(wid: entry.wid, layerId: layerNameForRef(ref))
+            return (entry.wid, entry.pid)
+        }
+
+        // 3. Window not found — dormant
+        ref.wid = nil
+        ref.pid = nil
+        ref.title = nil
+        ref.frame = nil
+        return nil
+    }
+
+    private func layerNameForRef(_ ref: WindowRef) -> String {
+        for layer in layers {
+            if layer.windows.contains(where: { $0.id == ref.id }) {
+                return layer.name
+            }
+        }
+        return ""
+    }
+
+    // MARK: - Reconciliation
+
+    func reconcile() {
+        let desktop = DesktopModel.shared
+        for layerIdx in layers.indices {
+            for refIdx in layers[layerIdx].windows.indices {
+                let ref = layers[layerIdx].windows[refIdx]
+                guard let wid = ref.wid else { continue }
+                if desktop.windows[wid] == nil {
+                    // Window gone — clear runtime, keep intent
+                    layers[layerIdx].windows[refIdx].wid = nil
+                    layers[layerIdx].windows[refIdx].pid = nil
+                    layers[layerIdx].windows[refIdx].title = nil
+                    layers[layerIdx].windows[refIdx].frame = nil
+                    desktop.removeLayerTag(wid: wid)
+                }
+            }
+        }
+    }
+}

package/app/Sources/SessionManager.swift

@@ -2,12 +2,15 @@ import AppKit
 
 enum SessionManager {
     private static let latticesPath = "/opt/homebrew/bin/lattices"
-    private static let tmuxPath = "/opt/homebrew/bin/tmux"
+    private static var tmuxPath: String { TmuxQuery.resolvedPath ?? "/opt/homebrew/bin/tmux" }
 
     /// Launch or reattach — if session is running, find and focus the existing window
     static func launch(project: Project) {
         let terminal = Preferences.shared.terminal
         if project.isRunning {
+            if let window = DesktopModel.shared.windowForSession(project.sessionName) {
+                DesktopModel.shared.markInteraction(wid: window.wid)
+            }
             terminal.focusOrAttach(session: project.sessionName)
         } else {
             terminal.launch(command: latticesPath, in: project.path)

package/app/Sources/SettingsView.swift

@@ -71,6 +71,7 @@ struct SettingsContentView: View {
             // Tab bar
             HStack(spacing: 2) {
                 settingsTab(label: "General", id: "general")
+                settingsTab(label: "AI", id: "ai")
                 settingsTab(label: "Search & OCR", id: "search")
                 settingsTab(label: "Shortcuts", id: "shortcuts")
                 Spacer()
@@ -84,6 +85,7 @@ struct SettingsContentView: View {
             switch selectedTab {
             case "shortcuts": shortcutsContent
             case "search":    searchOcrContent
+            case "ai":        aiContent
             default:          generalContent
             }
         }
@@ -269,6 +271,167 @@ struct SettingsContentView: View {
         }
     }
 
+    // MARK: - AI
+
+    private var aiContent: some View {
+        ScrollView {
+            VStack(spacing: 12) {
+                // ── Claude CLI ──
+                settingsCard {
+                    VStack(alignment: .leading, spacing: 10) {
+                        HStack(spacing: 8) {
+                            Image(systemName: "sparkles")
+                                .font(.system(size: 11, weight: .medium))
+                                .foregroundColor(Palette.running)
+                            Text("Claude CLI")
+                                .font(Typo.mono(12))
+                                .foregroundColor(Palette.text)
+                        }
+
+                        HStack(spacing: 6) {
+                            TextField("Auto-detected", text: $prefs.claudePath)
+                                .textFieldStyle(.plain)
+                                .font(Typo.mono(11))
+                                .foregroundColor(Palette.text)
+                                .padding(.horizontal, 8)
+                                .padding(.vertical, 5)
+                                .background(
+                                    RoundedRectangle(cornerRadius: 5)
+                                        .fill(Color.white.opacity(0.06))
+                                        .overlay(RoundedRectangle(cornerRadius: 5).strokeBorder(Color.white.opacity(0.08), lineWidth: 0.5))
+                                )
+
+                            Button {
+                                if let resolved = Preferences.resolveClaudePath() {
+                                    prefs.claudePath = resolved
+                                }
+                            } label: {
+                                Text("Detect")
+                                    .font(Typo.monoBold(10))
+                                    .foregroundColor(Palette.text)
+                                    .padding(.horizontal, 10)
+                                    .padding(.vertical, 4)
+                                    .background(
+                                        RoundedRectangle(cornerRadius: 4)
+                                            .fill(Palette.surfaceHov)
+                                            .overlay(RoundedRectangle(cornerRadius: 4).strokeBorder(Palette.borderLit, lineWidth: 0.5))
+                                    )
+                            }
+                            .buttonStyle(.plain)
+                        }
+
+                        let resolved = Preferences.resolveClaudePath()
+                        if let path = resolved {
+                            Text("Found: \(path)")
+                                .font(Typo.caption(9))
+                                .foregroundColor(Palette.running.opacity(0.8))
+                        } else {
+                            Text("Not found — install with: npm i -g @anthropic-ai/claude-code")
+                                .font(Typo.caption(9))
+                                .foregroundColor(Palette.detach)
+                        }
+                    }
+                }
+
+                // ── Advisor ──
+                settingsCard {
+                    VStack(alignment: .leading, spacing: 10) {
+                        Text("Voice advisor")
+                            .font(Typo.mono(11))
+                            .foregroundColor(Palette.text)
+
+                        HStack {
+                            Text("Model")
+                                .font(Typo.mono(10))
+                                .foregroundColor(Palette.textDim)
+                            Spacer()
+                            Picker("", selection: $prefs.advisorModel) {
+                                Text("Haiku").tag("haiku")
+                                Text("Sonnet").tag("sonnet")
+                            }
+                            .pickerStyle(.segmented)
+                            .labelsHidden()
+                            .frame(width: 160)
+                        }
+
+                        Text("Haiku is fast and cheap. Sonnet is smarter but slower.")
+                            .font(Typo.caption(9))
+                            .foregroundColor(Palette.textMuted.opacity(0.7))
+
+                        cardDivider
+
+                        HStack {
+                            Text("Budget per session")
+                                .font(Typo.mono(10))
+                                .foregroundColor(Palette.textDim)
+                            Spacer()
+                            HStack(spacing: 4) {
+                                Text("$")
+                                    .font(Typo.mono(11))
+                                    .foregroundColor(Palette.textDim)
+                                TextField("0.50", value: $prefs.advisorBudgetUSD, formatter: {
+                                    let f = NumberFormatter()
+                                    f.numberStyle = .decimal
+                                    f.minimumFractionDigits = 2
+                                    f.maximumFractionDigits = 2
+                                    return f
+                                }())
+                                .textFieldStyle(.plain)
+                                .font(Typo.monoBold(11))
+                                .foregroundColor(Palette.text)
+                                .multilineTextAlignment(.center)
+                                .frame(width: 50)
+                                .padding(.horizontal, 4)
+                                .padding(.vertical, 3)
+                                .background(
+                                    RoundedRectangle(cornerRadius: 5)
+                                        .fill(Color.white.opacity(0.06))
+                                        .overlay(RoundedRectangle(cornerRadius: 5).strokeBorder(Color.white.opacity(0.08), lineWidth: 0.5))
+                                )
+                            }
+                        }
+
+                        Text("Max spend per Claude CLI invocation")
+                            .font(Typo.caption(9))
+                            .foregroundColor(Palette.textMuted.opacity(0.7))
+
+                        cardDivider
+
+                        // Session stats
+                        let stats = AgentPool.shared.haiku.sessionStats
+                        HStack(spacing: 12) {
+                            if stats.contextWindow > 0 {
+                                HStack(spacing: 4) {
+                                    Circle()
+                                        .fill(stats.contextUsage > 0.6 ? Palette.detach : Palette.running)
+                                        .frame(width: 5, height: 5)
+                                    Text("Context: \(Int(stats.contextUsage * 100))%")
+                                        .font(Typo.mono(10))
+                                        .foregroundColor(Palette.textMuted)
+                                }
+                            }
+                            if stats.costUSD > 0 {
+                                Text("Session cost: $\(String(format: "%.3f", stats.costUSD))")
+                                    .font(Typo.mono(10))
+                                    .foregroundColor(Palette.textMuted)
+                            }
+
+                            Spacer()
+
+                            let learningCount = AdvisorLearningStore.shared.entryCount
+                            if learningCount > 0 {
+                                Text("\(learningCount) learned")
+                                    .font(Typo.mono(9))
+                                    .foregroundColor(Palette.textMuted.opacity(0.6))
+                            }
+                        }
+                    }
+                }
+            }
+            .padding(16)
+        }
+    }
+
     // MARK: - Search & OCR
 
     private func ocrNumField(_ value: Binding<Double>, width: CGFloat = 50) -> some View {
@@ -950,6 +1113,26 @@ struct SettingsContentView: View {
                     .padding(.vertical, 12)
                 }
 
+                Section(header: stickyHeader("Voice commands")) {
+                    VStack(alignment: .leading, spacing: 8) {
+                        flowStep("⌥", "Hold Option key to speak, release to stop")
+                        flowStep("⇥", "Tab to arm/disarm the mic")
+                        flowStep("⎋", "Escape to dismiss")
+
+                        Text("Built-in commands: find, show, open, tile, kill, scan")
+                            .font(Typo.caption(10.5))
+                            .foregroundColor(Palette.textMuted)
+                            .padding(.top, 4)
+
+                        Text("When local matching fails, Claude Haiku advises with follow-up suggestions. Configure the AI model and budget in Settings → AI.")
+                            .font(Typo.caption(10.5))
+                            .foregroundColor(Palette.textMuted)
+                            .lineSpacing(2)
+                    }
+                    .padding(.horizontal, 20)
+                    .padding(.vertical, 12)
+                }
+
                 Section(header: stickyHeader("Reference")) {
                     HStack(spacing: 8) {
                         docsLinkButton(icon: "doc.text", label: "Config format", file: "config.md")
@@ -1015,13 +1198,13 @@ struct SettingsContentView: View {
     }
 
     private func resolveDocsFile(_ file: String) -> String {
-        let devPath = "/Users/arach/dev/lattice/docs/\(file)"
-        if FileManager.default.fileExists(atPath: devPath) { return devPath }
         let bundle = Bundle.main.bundlePath
         let appDir = (bundle as NSString).deletingLastPathComponent
         let docsPath = ((appDir as NSString).appendingPathComponent("../docs/\(file)") as NSString).standardizingPath
         if FileManager.default.fileExists(atPath: docsPath) { return docsPath }
-        return devPath
+        // Fallback: look relative to the repo root (dev builds)
+        let repoGuess = ((appDir as NSString).appendingPathComponent("../../docs/\(file)") as NSString).standardizingPath
+        return FileManager.default.fileExists(atPath: repoGuess) ? repoGuess : docsPath
     }
 
     // MARK: - Shared helpers

package/app/Sources/Theme.swift

@@ -3,17 +3,18 @@ import SwiftUI
 // MARK: - Colors
 
 enum Palette {
-    // Base surfaces — warm dark
-    static let bg         = Color(red: 0.11, green: 0.11, blue: 0.12)   // #1C1C1E
-    static let surface    = Color(red: 0.15, green: 0.15, blue: 0.16)   // Raised cards
-    static let surfaceHov = Color(red: 0.18, green: 0.18, blue: 0.19)   // Hovered cards
-    static let border     = Color.white.opacity(0.05)
-    static let borderLit  = Color.white.opacity(0.10)
+    // Base surfaces
+    static let bg         = Color(red: 0.08, green: 0.08, blue: 0.09)   // #141416
+    static let bgSidebar  = Color(red: 0.08, green: 0.08, blue: 0.09)   // same as bg
+    static let surface    = Color(white: 0.10)                           // Raised cards
+    static let surfaceHov = Color(white: 0.14)                           // Hovered cards
+    static let border     = Color.white.opacity(0.08)
+    static let borderLit  = Color.white.opacity(0.14)
 
     // Text
     static let text       = Color.white.opacity(0.92)
-    static let textDim    = Color.white.opacity(0.50)
-    static let textMuted  = Color.white.opacity(0.30)
+    static let textDim    = Color.white.opacity(0.58)
+    static let textMuted  = Color.white.opacity(0.40)
 
     // Functional accents
     static let running  = Color(red: 0.20, green: 0.78, blue: 0.45)   // Green

package/app/Sources/TmuxModel.swift

@@ -4,10 +4,17 @@ final class TmuxModel: ObservableObject {
     static let shared = TmuxModel()
 
     @Published private(set) var sessions: [TmuxSession] = []
+    @Published private(set) var isAvailable: Bool = TmuxQuery.isAvailable
     private var timer: Timer?
 
     func start(interval: TimeInterval = 3.0) {
         guard timer == nil else { return }
+
+        if !isAvailable {
+            DiagnosticLog.shared.warn("TmuxModel: tmux not found — session features disabled")
+            return
+        }
+
         DiagnosticLog.shared.info("TmuxModel: starting (interval=\(interval)s)")
         poll()
         timer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) { [weak self] _ in

package/app/Sources/TmuxQuery.swift

@@ -23,20 +23,44 @@ struct TmuxPane: Identifiable {
 // MARK: - Query
 
 enum TmuxQuery {
-    private static let tmuxPath = "/opt/homebrew/bin/tmux"
+    /// Resolved path to the tmux binary, or nil if not found
+    static let resolvedPath: String? = {
+        let candidates = [
+            "/opt/homebrew/bin/tmux",   // Apple Silicon Homebrew
+            "/usr/local/bin/tmux",      // Intel Homebrew
+            "/usr/bin/tmux",            // unlikely on macOS, but check
+            "/opt/local/bin/tmux",      // MacPorts
+        ]
+        for path in candidates {
+            if FileManager.default.isExecutableFile(atPath: path) {
+                return path
+            }
+        }
+        // Fall back to PATH lookup via /usr/bin/which
+        let result = ProcessQuery.shell(["/usr/bin/which", "tmux"]).trimmingCharacters(in: .whitespacesAndNewlines)
+        if !result.isEmpty && FileManager.default.isExecutableFile(atPath: result) {
+            return result
+        }
+        return nil
+    }()
+
+    /// Whether tmux is available on this system
+    static var isAvailable: Bool { resolvedPath != nil }
 
     /// List all tmux sessions with their panes in exactly 2 shell calls
     static func listSessions() -> [TmuxSession] {
+        guard let tmux = resolvedPath else { return [] }
+
         // Query 1: all sessions
         let sessionsRaw = shell([
-            tmuxPath, "list-sessions", "-F",
+            tmux, "list-sessions", "-F",
             "#{session_name}\t#{session_windows}\t#{session_created}\t#{session_attached}"
         ])
         guard !sessionsRaw.isEmpty else { return [] }
 
         // Query 2: all panes across all sessions
         let panesRaw = shell([
-            tmuxPath, "list-panes", "-a", "-F",
+            tmux, "list-panes", "-a", "-F",
             "#{session_name}\t#{window_index}\t#{window_name}\t#{pane_id}\t#{pane_title}\t#{pane_current_command}\t#{pane_pid}\t#{pane_active}"
         ])