fix(brainbar): harden reliability under db contention

brain-bar/Sources/BrainBar/BrainBarApp.swift

@@ -73,50 +73,51 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
             createLegacyStatusItem()
         }
 
-        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
-            guard let self else { return }
-
-            let dbPath = BrainBarServer.defaultDBPath()
-            NSLog("[BrainBar] Opening database at %@", dbPath)
-            let sharedDatabase = BrainDatabase(path: dbPath)
-
-            let server = BrainBarServer(database: sharedDatabase)
-            server.onDatabaseReady = { [weak self] database in
-                Task { @MainActor in
-                    self?.configureQuickCapture(database: database)
-                }
+        let dbPath = BrainBarServer.defaultDBPath()
+        NSLog("[BrainBar] Starting server before database readiness at %@", dbPath)
+        let server = BrainBarServer(dbPath: dbPath)
+        server.onStartRejected = { reason in
+            NSLog("[BrainBar] Startup rejected: %@", reason)
+            Task { @MainActor in
+                NSApp.terminate(nil)
             }
-
-            DispatchQueue.main.async { [weak self] in
+        }
+        server.onDatabaseReady = { [weak self] database in
+            Task { @MainActor in
                 guard let self else { return }
-                let collector = StatsCollector(
-                    dbPath: dbPath,
-                    daemonMonitor: DaemonHealthMonitor(targetPID: ProcessInfo.processInfo.processIdentifier)
-                )
-                let injectionStore = try? InjectionStore(databasePath: dbPath)
-
-                self.sharedDatabase = sharedDatabase
-                self.server = server
-                self.collector = collector
-                self.injectionStore = injectionStore
-
-                server.start()
-                runtime.install(
-                    collector: collector,
-                    injectionStore: injectionStore,
-                    database: sharedDatabase
+                self.sharedDatabase = database
+                self.configureQuickCapture(database: database)
+                self.runtime.install(
+                    collector: self.collector ?? StatsCollector(
+                        dbPath: dbPath,
+                        daemonMonitor: DaemonHealthMonitor(targetPID: ProcessInfo.processInfo.processIdentifier)
+                    ),
+                    injectionStore: self.injectionStore,
+                    database: database
                 )
-                flushPendingBrainBarURLs()
+                self.flushPendingBrainBarURLs()
+            }
+        }
 
-                if launchMode == .legacyStatusItem {
-                    installLegacyMenuBarSurface(with: collector)
-                }
+        let collector = StatsCollector(
+            dbPath: dbPath,
+            daemonMonitor: DaemonHealthMonitor(targetPID: ProcessInfo.processInfo.processIdentifier)
+        )
+        let injectionStore = try? InjectionStore(databasePath: dbPath)
 
-                collector.start()
-                configureQuickCaptureHotkey()
-                NSLog("[BrainBar] Backend ready — launchMode=%@", String(describing: launchMode))
-            }
+        self.server = server
+        self.collector = collector
+        self.injectionStore = injectionStore
+
+        server.start()
+
+        if launchMode == .legacyStatusItem {
+            installLegacyMenuBarSurface(with: collector)
         }
+
+        collector.start()
+        configureQuickCaptureHotkey()
+        NSLog("[BrainBar] Socket ready; database will self-heal — launchMode=%@", String(describing: launchMode))
     }
 
     func applicationWillTerminate(_ notification: Notification) {

brain-bar/Sources/BrainBar/BrainBarInstanceLock.swift

@@ -0,0 +1,66 @@
+import Darwin
+import Foundation
+import os
+
+final class BrainBarInstanceLock: @unchecked Sendable {
+    enum AcquireError: Error, Equatable {
+        case alreadyRunning
+        case openFailed(String)
+        case lockFailed(String)
+    }
+
+    private let fd: Int32
+    private let lockPath: String
+    private let releaseLock = OSAllocatedUnfairLock(initialState: false)
+
+    private init(fd: Int32, lockPath: String) {
+        self.fd = fd
+        self.lockPath = lockPath
+    }
+
+    deinit {
+        release()
+    }
+
+    static func acquire(lockPath: String) throws -> BrainBarInstanceLock {
+        let directory = URL(fileURLWithPath: lockPath).deletingLastPathComponent()
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+
+        let fd = open(lockPath, O_RDWR | O_CREAT, 0o600)
+        guard fd >= 0 else {
+            throw AcquireError.openFailed(String(cString: strerror(errno)))
+        }
+
+        guard flock(fd, LOCK_EX | LOCK_NB) == 0 else {
+            let lockErrno = errno
+            let message = String(cString: strerror(lockErrno))
+            close(fd)
+            if lockErrno == EWOULDBLOCK {
+                throw AcquireError.alreadyRunning
+            }
+            throw AcquireError.lockFailed(message)
+        }
+
+        var pidLine = "\(getpid())\n".data(using: .utf8) ?? Data()
+        ftruncate(fd, 0)
+        lseek(fd, 0, SEEK_SET)
+        _ = pidLine.withUnsafeMutableBytes { ptr in
+            write(fd, ptr.baseAddress, ptr.count)
+        }
+        fsync(fd)
+
+        return BrainBarInstanceLock(fd: fd, lockPath: lockPath)
+    }
+
+    func release() {
+        let shouldRelease = releaseLock.withLock { released -> Bool in
+            guard !released else { return false }
+            released = true
+            return true
+        }
+        guard shouldRelease else { return }
+        flock(fd, LOCK_UN)
+        close(fd)
+        try? FileManager.default.removeItem(atPath: lockPath)
+    }
+}

brain-bar/Sources/BrainBar/BrainBarServer.swift

 private func handleMessage(fd: Int32, request: [String: Any]) -> [String: Any] { 
 private func handleMessage(fd: Int32, request: [String: Any]) -> [String: Any] { 
@@ -91,6 +91,7 @@ final class BrainBarServer: @unchecked Sendable {
     private let dbPath: String
     private let providedDatabase: BrainDatabase?
     private let databaseRecoveryPolicy: DatabaseRecoveryPolicy
+    private let instanceLockPath: String
     private let queue = DispatchQueue(label: "com.brainlayer.brainbar.server", qos: .userInitiated)
     private var listenFD: Int32 = -1
     private var listenSource: DispatchSourceRead?
@@ -99,7 +100,10 @@ final class BrainBarServer: @unchecked Sendable {
     private var database: BrainDatabase!
     private var databaseRetryWorkItem: DispatchWorkItem?
     private var lastDatabaseRetryDelayMillis: UInt64?
+    private var databaseOpenInProgress = false
+    private var instanceLock: BrainBarInstanceLock?
     var onDatabaseReady: (@Sendable (BrainDatabase) -> Void)?
+    var onStartRejected: (@Sendable (String) -> Void)?
     /// Maximum EAGAIN retries before disconnecting a stalled client.
     /// Each retry sleeps 1ms, so 10 retries = 10ms max blocking the serial queue.
     static let maxWriteRetries = 10
@@ -137,12 +141,14 @@ final class BrainBarServer: @unchecked Sendable {
         socketPath: String? = nil,
         dbPath: String? = nil,
         database: BrainDatabase? = nil,
-        databaseRecoveryPolicy: DatabaseRecoveryPolicy = DatabaseRecoveryPolicy()
+        databaseRecoveryPolicy: DatabaseRecoveryPolicy = DatabaseRecoveryPolicy(),
+        instanceLockPath: String? = nil
     ) {
         self.socketPath = socketPath ?? Self.defaultSocketPath()
         self.dbPath = dbPath ?? Self.defaultDBPath()
         providedDatabase = database
         self.databaseRecoveryPolicy = databaseRecoveryPolicy
+        self.instanceLockPath = instanceLockPath ?? Self.defaultInstanceLockPath(socketPath: self.socketPath)
     }
 
     static func defaultSocketPath() -> String {
@@ -162,6 +168,10 @@ final class BrainBarServer: @unchecked Sendable {
         return "\(home)/.local/share/brainlayer/brainlayer.db"
     }
 
+    static func defaultInstanceLockPath(socketPath: String = defaultSocketPath()) -> String {
+        "\(socketPath).lock"
+    }
+
     func start() {
         queue.async { [weak self] in
             self?.startOnQueue()
@@ -175,6 +185,18 @@ final class BrainBarServer: @unchecked Sendable {
     }
 
     private func startOnQueue() {
+        do {
+            instanceLock = try BrainBarInstanceLock.acquire(lockPath: instanceLockPath)
+        } catch BrainBarInstanceLock.AcquireError.alreadyRunning {
+            NSLog("[BrainBar] Another BrainBar instance owns %@. Exiting this server.", instanceLockPath)
+            onStartRejected?("another BrainBar instance owns \(instanceLockPath)")
+            return
+        } catch {
+            NSLog("[BrainBar] Failed to acquire single-instance lock %@: %@", instanceLockPath, String(describing: error))
+            onStartRejected?("failed to acquire single-instance lock \(instanceLockPath): \(error)")
+            return
+        }
+
         // 1. Create router FIRST (no DB dependency).
         //    initialize + tools/list work without a database.
         router = MCPRouter()
@@ -253,12 +275,36 @@ final class BrainBarServer: @unchecked Sendable {
     }
 
     private func attemptDatabaseOpen() {
-        guard database == nil else { return }
+        guard database == nil, !databaseOpenInProgress else { return }
+
+        if let providedDatabase {
+            finishDatabaseOpen(providedDatabase)
+            return
+        }
+
+        databaseOpenInProgress = true
+        let dbPath = self.dbPath
+        let busyTimeoutMillis = databaseRecoveryPolicy.busyTimeoutMillis
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            let db = BrainDatabase(
+                path: dbPath,
+                openConfiguration: .init(busyTimeoutMillis: busyTimeoutMillis)
+            )
+            self?.queue.async { [weak self] in
+                self?.databaseOpenInProgress = false
+                self?.finishDatabaseOpen(db)
+            }
+        }
+    }
+
+    private func finishDatabaseOpen(_ db: BrainDatabase) {
+        guard listenSource != nil else {
+            if providedDatabase == nil {
+                db.close()
+            }
+            return
+        }
 
-        let db = providedDatabase ?? BrainDatabase(
-            path: dbPath,
-            openConfiguration: .init(busyTimeoutMillis: databaseRecoveryPolicy.busyTimeoutMillis)
-        )
         if db.isOpen {
             databaseRetryWorkItem?.cancel()
             databaseRetryWorkItem = nil
@@ -496,6 +542,9 @@ final class BrainBarServer: @unchecked Sendable {
             database?.close()
         }
         database = nil
+        databaseOpenInProgress = false
+        instanceLock?.release()
+        instanceLock = nil
         NSLog("[BrainBar] Server stopped")
     }
 

brain-bar/Sources/BrainBar/BrainDatabase.swift

@@ -168,6 +168,11 @@ final class BrainDatabase: @unchecked Sendable {
         let importance: Int
     }
 
+    enum StoreWriteOutcome: Sendable {
+        case stored(StoredChunk)
+        case queued
+    }
+
     struct PendingStoreItem: Codable, Sendable {
         let content: String
         let tags: [String]
@@ -702,7 +707,9 @@ final class BrainDatabase: @unchecked Sendable {
         importance: Int,
         source: String,
         queueID: String? = nil,
-        refreshStatistics: Bool = true
+        refreshStatistics: Bool = true,
+        retries: Int = 3,
+        busyTimeoutMillis: Int32? = nil
     ) throws -> StoredChunk {
         guard let db else { throw DBError.notOpen }
         let chunkID = "brainbar-\(UUID().uuidString.lowercased().prefix(12))"
@@ -712,7 +719,17 @@ final class BrainDatabase: @unchecked Sendable {
             INSERT INTO chunks (id, content, metadata, source_file, tags, importance, source, content_type, char_count, preview_text)
             VALUES (?, ?, ?, 'brainbar-store', ?, ?, ?, 'user_message', ?, ?)
         """
-        try runWriteStatement(on: db, sql: sql, retries: 3) { stmt in
+        let previousBusyTimeout = busyTimeoutMillis.flatMap { _ in queryPragma(db, name: "busy_timeout") }
+        if let busyTimeoutMillis {
+            try executeOnHandle(db, sql: "PRAGMA busy_timeout = \(max(1, busyTimeoutMillis))")
+        }
+        defer {
+            if let previousBusyTimeout {
+                try? executeOnHandle(db, sql: "PRAGMA busy_timeout = \(previousBusyTimeout)")
+            }
+        }
+
+        try runWriteStatement(on: db, sql: sql, retries: retries) { stmt in
             bindText(chunkID, to: stmt, index: 1)
             bindText(content, to: stmt, index: 2)
             bindText(metadataJSON, to: stmt, index: 3)
@@ -731,6 +748,33 @@ final class BrainDatabase: @unchecked Sendable {
         return StoredChunk(chunkID: chunkID, rowID: rowID)
     }
 
+    func storeOrQueueWithinBudget(
+        content: String,
+        tags: [String],
+        importance: Int,
+        source: String,
+        busyTimeoutMillis: Int32 = 50
+    ) throws -> StoreWriteOutcome {
+        do {
+            let stored = try store(
+                content: content,
+                tags: tags,
+                importance: importance,
+                source: source,
+                refreshStatistics: true,
+                retries: 0,
+                busyTimeoutMillis: busyTimeoutMillis
+            )
+            return .stored(stored)
+        } catch {
+            guard shouldQueueStoreError(error) else {
+                throw error
+            }
+            try queuePendingStore(content: content, tags: tags, importance: importance, source: source)
+            return .queued
+        }
+    }
+
     /// Async wrapper for store() — runs DB write off the main thread.
     func storeAsync(content: String, tags: [String], importance: Int, source: String) async throws -> StoredChunk {
         try await withCheckedThrowingContinuation { continuation in

brain-bar/Sources/BrainBar/MCPRouter.swift

@@ -285,8 +285,8 @@ final class MCPRouter: @unchecked Sendable {
         guard let db = database else {
             throw ToolError.noDatabase
         }
-        do {
-            let stored = try db.store(content: content, tags: tags, importance: importance, source: "mcp")
+        switch try db.storeOrQueueWithinBudget(content: content, tags: tags, importance: importance, source: "mcp") {
+        case .stored(let stored):
             let flushedStores = db.flushPendingStores()
             return ToolOutput(
                 text: Formatters.formatStoreResult(chunkId: stored.chunkID),
@@ -308,11 +308,7 @@ final class MCPRouter: @unchecked Sendable {
                     }
                 ]
             )
-        } catch {
-            guard db.shouldQueueStoreError(error) else {
-                throw error
-            }
-            try db.queuePendingStore(content: content, tags: tags, importance: importance, source: "mcp")
+        case .queued:
             return ToolOutput(
                 text: Formatters.formatStoreResult(chunkId: "", queued: true),
                 metadata: ["queued": true]