Discover the Homebrew simbroker binary from the macOS app.

Why:
Finish Local Broker Installation told strangers to brew install then
Refresh, but the app only looked at SIMBROKER_CLI_PATH, install.json,
and the clone-install default bin. Homebrew writes prefix bin/simbroker
and does not write install.json, so Refresh stayed on the missing-CLI
screen.

Changed:
CLI search now checks Homebrew prefix bin after explicit overrides and
install.json, then falls back to the clone-install default bin. Unit
tests pin that order.

Verification:
npm run agent:verify -- --profile spec-only --paths app/Sources/BrokerSnapshotLoader.swift,app/Tests/BrokerRuntimePathsTests.swift,CHANGELOG.md,spec/build-and-test.md --session-dir task-sessions/homebrew-cli-discovery-20260819
npm run agent:verify -- --profile implementation --paths app/Sources/BrokerSnapshotLoader.swift,app/Tests/BrokerRuntimePathsTests.swift,CHANGELOG.md,spec/build-and-test.md --session-dir task-sessions/homebrew-cli-discovery-20260819
npm run test:app:focus -- SimulatorBrokerAppTests/BrokerRuntimePathsTests

Affected:
app/Sources/BrokerSnapshotLoader.swift
app/Tests/BrokerRuntimePathsTests.swift
CHANGELOG.md
spec/build-and-test.md

Refs:
#14
spec/build-and-test.md

Session:
task-sessions/homebrew-cli-discovery-20260819

Author: VladimirBrejcha

CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   create simulators.
 - The app **Finish Local Broker Installation** copy leads with
   `brew install fiveonecode/simulator-broker/simbroker` and **Refresh**.
+  Refresh now discovers `simbroker` in Homebrew prefix `bin` (`/opt/homebrew`
+  and `/usr/local`) as well as `install.json` and `~/.local/bin`.
 - `host init --bootstrap-config` `runtime-not-found` errors name
   `--ios-version` and `xcrun simctl list runtimes`. Default starter iOS
   stays `18`.

app/Sources/BrokerSnapshotLoader.swift

@@ -50,6 +50,47 @@ struct BrokerRuntimePaths: Sendable {
       .appending(path: "simbroker")
   }
 
+  static func defaultHomebrewPrefixRoots(
+    environment: [String: String] = ProcessInfo.processInfo.environment
+  ) -> [URL] {
+    var roots: [URL] = []
+    if let prefix = environment["HOMEBREW_PREFIX"], prefix.isEmpty == false {
+      roots.append(URL(fileURLWithPath: (prefix as NSString).expandingTildeInPath))
+    }
+    roots.append(URL(fileURLWithPath: "/opt/homebrew"))
+    roots.append(URL(fileURLWithPath: "/usr/local"))
+    var seen = Set<String>()
+    return roots.filter { seen.insert($0.standardizedFileURL.path).inserted }
+  }
+
+  static func cliCandidateURLs(
+    configuredCLIURL: URL?,
+    installMetadataCLIPath: String?,
+    homebrewPrefixRoots: [URL] = defaultHomebrewPrefixRoots(),
+    defaultCLIURL: URL = defaultCLIURL()
+  ) -> [URL] {
+    var candidates: [URL] = []
+    if let configuredCLIURL {
+      candidates.append(configuredCLIURL)
+    }
+    if let installMetadataCLIPath, installMetadataCLIPath.isEmpty == false {
+      candidates.append(URL(fileURLWithPath: (installMetadataCLIPath as NSString).expandingTildeInPath))
+    }
+    for root in homebrewPrefixRoots {
+      candidates.append(root.appending(path: "bin").appending(path: "simbroker"))
+    }
+    candidates.append(defaultCLIURL)
+    var seen = Set<String>()
+    return candidates.filter { seen.insert($0.standardizedFileURL.path).inserted }
+  }
+
+  static func firstExecutableCLIURL(
+    among candidates: [URL],
+    isExecutable: (String) -> Bool = { FileManager.default.isExecutableFile(atPath: $0) }
+  ) -> URL? {
+    candidates.first { isExecutable($0.path) }
+  }
+
   static func defaultInstallRoot() -> URL {
     FileManager.default.homeDirectoryForCurrentUser
       .appending(path: "Library")
@@ -285,25 +326,12 @@ actor FileBrokerSnapshotLoader: BrokerSnapshotLoading {
   }
 
   private func resolveCLIPath(installMetadata: BrokerInstallMetadata?) -> URL? {
-    let fileManager = FileManager.default
-    let candidates = [
-      paths.configuredCLIURL,
-      installMetadata?.cliPath.flatMap { cliPath in
-        cliPath.isEmpty ? nil : URL(fileURLWithPath: (cliPath as NSString).expandingTildeInPath)
-      },
-      BrokerRuntimePaths.defaultCLIURL(),
-    ]
-
-    for candidate in candidates {
-      guard let candidate else {
-        continue
-      }
-      if fileManager.isExecutableFile(atPath: candidate.path) {
-        return candidate
-      }
-    }
-
-    return nil
+    BrokerRuntimePaths.firstExecutableCLIURL(
+      among: BrokerRuntimePaths.cliCandidateURLs(
+        configuredCLIURL: paths.configuredCLIURL,
+        installMetadataCLIPath: installMetadata?.cliPath
+      )
+    )
   }
 
   private func normalizedPath(_ rawPath: String) -> String {

app/Tests/BrokerRuntimePathsTests.swift

@@ -74,4 +74,70 @@ final class BrokerRuntimePathsTests: XCTestCase {
     XCTAssertEqual(launchContext.initialSelection.projectId, "sample-project")
     XCTAssertNil(launchContext.initialSelection.eventId)
   }
+
+  func testCLICandidatesPreferConfiguredThenInstallThenHomebrewThenLocalDefault() {
+    let configured = URL(fileURLWithPath: "/tmp/configured-simbroker")
+    let installPath = "/tmp/installed-simbroker"
+    let candidates = BrokerRuntimePaths.cliCandidateURLs(
+      configuredCLIURL: configured,
+      installMetadataCLIPath: installPath,
+      homebrewPrefixRoots: [
+        URL(fileURLWithPath: "/opt/homebrew"),
+        URL(fileURLWithPath: "/usr/local"),
+      ],
+      defaultCLIURL: URL(fileURLWithPath: "/tmp/home/.local/bin/simbroker")
+    )
+
+    XCTAssertEqual(
+      candidates.map(\.path),
+      [
+        "/tmp/configured-simbroker",
+        "/tmp/installed-simbroker",
+        "/opt/homebrew/bin/simbroker",
+        "/usr/local/bin/simbroker",
+        "/tmp/home/.local/bin/simbroker",
+      ]
+    )
+  }
+
+  func testFirstExecutableCLIPrefersHomebrewOverLocalDefault() {
+    let homebrew = URL(fileURLWithPath: "/opt/homebrew/bin/simbroker")
+    let localDefault = URL(fileURLWithPath: "/tmp/home/.local/bin/simbroker")
+    let candidates = BrokerRuntimePaths.cliCandidateURLs(
+      configuredCLIURL: nil,
+      installMetadataCLIPath: nil,
+      homebrewPrefixRoots: [URL(fileURLWithPath: "/opt/homebrew")],
+      defaultCLIURL: localDefault
+    )
+    let resolved = BrokerRuntimePaths.firstExecutableCLIURL(among: candidates) { path in
+      path == homebrew.path || path == localDefault.path
+    }
+
+    XCTAssertEqual(resolved, homebrew)
+  }
+
+  func testFirstExecutableCLIFallsBackToLocalDefaultWhenHomebrewIsMissing() {
+    let localDefault = URL(fileURLWithPath: "/tmp/home/.local/bin/simbroker")
+    let candidates = BrokerRuntimePaths.cliCandidateURLs(
+      configuredCLIURL: nil,
+      installMetadataCLIPath: nil,
+      homebrewPrefixRoots: [URL(fileURLWithPath: "/opt/homebrew")],
+      defaultCLIURL: localDefault
+    )
+    let resolved = BrokerRuntimePaths.firstExecutableCLIURL(among: candidates) { path in
+      path == localDefault.path
+    }
+
+    XCTAssertEqual(resolved, localDefault)
+  }
+
+  func testDefaultHomebrewPrefixesIncludeStandardRootsAndOptionalHOMEBREW_PREFIX() {
+    let prefixes = BrokerRuntimePaths.defaultHomebrewPrefixRoots(
+      environment: ["HOMEBREW_PREFIX": "/opt/homebrew"]
+    )
+    XCTAssertEqual(
+      prefixes.map(\.path),
+      ["/opt/homebrew", "/usr/local"]
+    )
+  }
 }

spec/build-and-test.md

@@ -24,7 +24,7 @@ A first extracted implementation slice now exists:
   stale-recovery, lock-race, scheduler, confirmed-cleanup, and failure coverage
 - tracked-text public-surface scanning with an ignored local denylist extension
 - app-side operator controls for pin create and clear, lease release, and lifecycle actions over the shared broker authority
-- app launch-time fixture overrides through `--state-root`, `--host-config`, optional `--cli-path`, plus direct pane/detail targeting for deterministic screenshot and smoke scenarios
+- app launch-time fixture overrides through `--state-root`, `--host-config`, optional `--cli-path`, plus direct pane/detail targeting for deterministic screenshot and smoke scenarios. When `--cli-path` / `SIMBROKER_CLI_PATH` and `install.json` are unset, the app also looks for an executable `simbroker` in Homebrew prefix `bin` (`/opt/homebrew`, `/usr/local`, and `HOMEBREW_PREFIX`) before `~/.local/bin`
 - broker-owned state artifacts are restricted to the current user, and lease, containment, pin, and lifecycle mutations share the broker mutation authority whether invoked directly, through the service, or from the app
 - inactive local project registrations can be removed only through the explicit, locked `project forget --project-id <id>` command; it is idempotent, refreshes the shared app snapshot, preserves the repository and audit history, and rejects projects with active leases or pins
 - the macOS app test wrapper now supports build-only reruns, focused `-only-testing` filters, and stable `xcresult` output for runtime triage