fix(helper): scan unredacts + popup localised + longer auto-close (#42)

v1.0.2 finally landed working release assets, but the install-and-run
flow hung at "需要以下权限：定位服务" because the helper's `scan`
subcommand kept returning ssid/bssid as null even after the user
clicked Allow. Locally verified all three fixes against the
dev-rebuilt bundle: BSSID + SSID + Beacon IE fields all flow.

Three changes in helper/Sources/diting-tianer/main.swift + a small
launcher patch in src/diting/cli.py:

1. **Scan unredacts under install-script TCC grants.** Two parallel
   issues kept BSSIDs/SSIDs null:

   a. The `scan` subcommand inherited responsibility from its
      terminal parent, so tccd attributed the Location request to
      Terminal (no NSLocationUsageDescription), and CWNetwork
      silently redacted ssid/bssid. The BLE path has done a
      responsibility_spawnattrs_setdisclaim re-exec since v0.5.0;
      `scan` now does the same hop.

   b. macOS 14.4+ / 26 requires an active CLLocationManager in
      the calling process at the moment of scanForNetworks — the
      bundle's TCC grant on disk is necessary but not sufficient.
      The `scan` subcommand now initialises a CLLocationManager
      and calls startUpdatingLocation() before the CoreWLAN call,
      mirroring what the GUI bundle has always done.

   The earlier code comment claiming CoreLocation was "more lenient
   than CoreBluetooth" was wrong; CoreWLAN on macOS 26 enforces
   both conditions.

2. **Helper popup is localised.** When DITING_LANG=zh (passed via
   `open --env` from Python's launcher) or when macOS's
   Locale.preferredLanguages starts with "zh", the popup shows
   Chinese instead of English. Title becomes "diting 天耳"; intro,
   status lines, and the "All permissions granted" message all
   translate. Resolution order (env var first, system preference
   second) matches the Python CLI's i18n.

3. **Popup auto-close delay extended 1.5s → 4s.** Users reported
   the "All permissions granted" confirmation flashed by too fast
   to read.

4. **Python launcher passes DITING_LANG to `open`.** Without this,
   the bundle inherits the user's login session env (which doesn't
   know about `diting --lang zh`) and the popup would show English
   even when diting is running in Chinese.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chenchaoyi

CHANGELOG.md

@@ -9,6 +9,49 @@ the project follows [Semantic Versioning](https://semver.org/) where
 practical. The leading `v0.x` line is allowed to break minor
 behaviours between releases.
 
+## [1.0.3] — 2026-05-13
+
+First end-user-installed release surfaced a long-latent CoreWLAN
+bug that only bites under the install.sh flow, plus two small
+helper-popup UX issues. v1.0.2's install path worked but `diting`
+itself hung at "需要以下权限：定位服务" because the helper's `scan`
+subcommand kept returning redacted BSSIDs even after the user
+clicked Allow.
+
+### Fixed
+- **Wi-Fi scan unredacts under install-script TCC grants.** Two
+  parallel issues kept BSSIDs / SSIDs `null`:
+  1. The helper's `scan` subcommand inherited responsibility from
+     its terminal parent, so tccd attributed the request to
+     Terminal (no `NSLocationUsageDescription`) instead of the
+     bundle. The BLE path has done a
+     `responsibility_spawnattrs_setdisclaim` re-exec since
+     v0.5.0; `scan` now does the same hop.
+  2. macOS 14.4+ / 26 requires an active `CLLocationManager` in
+     the calling process at the moment of `scanForNetworks` — the
+     bundle's TCC grant on disk is necessary but not sufficient.
+     The `scan` subcommand now initialises a `CLLocationManager`
+     and calls `startUpdatingLocation()` before the CoreWLAN
+     call, mirroring what the GUI bundle has always done.
+  The earlier code comment claiming CoreLocation was "more
+  lenient than CoreBluetooth" was wrong — verified locally that
+  with both fixes BSSIDs / SSIDs / IE diagnostics flow as
+  expected.
+
+### Changed
+- **Helper popup window is localised.** When `DITING_LANG=zh` (passed
+  via `open --env` from Python's launcher) or when macOS's
+  `Locale.preferredLanguages` starts with `zh`, the popup window
+  shows Chinese instead of English. Title becomes "diting 天耳",
+  body / status lines translate accordingly. The first-launch
+  install.sh popup also picks up zh automatically for users on a
+  Chinese-locale Mac.
+- **Helper popup auto-close delay 1.5s → 4s.** Users reported the
+  "All permissions granted" confirmation flashed by too fast to
+  read; 4 s is long enough to comfortably take in without being
+  annoying. The Python launcher's polling loop picks up the
+  grants immediately regardless of how long the window stays up.
+
 ## [1.0.2] — 2026-05-13
 
 Second hot-fix to the v1.0.0 release pipeline. v1.0.1 unblocked the

docs/zh/CHANGELOG.md

@@ -8,6 +8,41 @@
 [Semantic Versioning](https://semver.org/)。`v0.x` 阶段允许破坏性的次要
 行为变更。
 
+## [1.0.3] — 2026-05-13
+
+第一个真正可被最终用户装出来的 release。装出来之后 `diting` 一直卡
+在「需要以下权限：定位服务」，原因是 helper 的 `scan` 子命令即使在
+用户点了 Allow 之后，依然返回被 TCC 屏蔽的 BSSID/SSID。同时修了两
+个 helper 弹窗的小 UX 问题。
+
+### 修复
+- **install.sh 安装路径下 Wi-Fi 扫描真正解除 TCC 屏蔽**。两个并行的
+  问题让 BSSID / SSID 都是 `null`：
+  1. helper 的 `scan` 子命令继承了 terminal 父进程的 responsibility，
+     tccd 把 Location 请求算到 Terminal 头上（Terminal 没有
+     `NSLocationUsageDescription`），CWNetwork 直接静默屏蔽
+     ssid / bssid。BLE 路径自 v0.5.0 起就用
+     `responsibility_spawnattrs_setdisclaim` 重启自己来打断这条
+     继承；`scan` 现在做同样的 hop。
+  2. macOS 14.4+ / 26 要求**当前进程**在 `scanForNetworks` 调用
+     的瞬间有活动的 `CLLocationManager`，bundle 的 TCC 授权只是必
+     要条件不是充分条件。`scan` 子命令现在在调 CoreWLAN 之前先
+     `CLLocationManager` + `startUpdatingLocation()`，跟 GUI bundle
+     一直在做的同。
+  代码里原来注释说 CoreLocation 比 CoreBluetooth「宽松」是错的——
+  本地验证两个修复同时上之后，BSSID / SSID / Beacon IE 数据如期
+  流出。
+
+### 变更
+- **helper 弹窗本地化**。`DITING_LANG=zh`（Python 启动器通过
+  `open --env` 传过来）或 macOS 的 `Locale.preferredLanguages` 以
+  `zh` 开头时，弹窗切到中文：标题改为「diting 天耳」，正文 / 状态
+  行也都翻译过来。中文 locale 用户跑 install.sh 时弹的第一个窗也
+  自动是中文。
+- **弹窗自动关闭从 1.5 s 改到 4 s**。多位用户反馈「全部权限已授予」
+  闪一下就消失，看不清；4 s 既够看完，又不至于让人觉得磨蹭。Python
+  启动器的轮询不依赖窗口停留时长，授权一落地立刻被识别。
+
 ## [1.0.2] — 2026-05-13
 
 第二个针对 v1.0.0 发布流水线的热修复。v1.0.1 解开了 Swift helper 构建

helper/Sources/diting-tianer/main.swift

@@ -54,6 +54,43 @@ import IOBluetooth
 // ---------------------------------------------------------------------
 
 func runScanAndDumpJSON() -> Never {
+    // macOS 14.4+ gates CWNetwork.ssid / .bssid behind Location Services
+    // at the calling process level — having the bundle's TCC grant on
+    // disk is not enough. Two things have to be true at scanForNetworks
+    // time:
+    //
+    //   1. The TCC subject seen by macOS is the helper bundle (not the
+    //      terminal that launched us). Inherited responsibility from
+    //      Terminal → diting → diting-tianer breaks this on macOS 26 —
+    //      tccd attributes the request to Terminal, which has no
+    //      NSLocationUsageDescription, and CWNetwork redacts ssid /
+    //      bssid silently. The fix is to disclaim our parent so we
+    //      become our own responsible process, same hop the ble-scan
+    //      subcommand has done since v0.5.0.
+    //
+    //   2. A CLLocationManager has called startUpdatingLocation() in
+    //      this process. The bundle grant alone isn't enough; CoreWLAN
+    //      checks for an active location signal at the moment of
+    //      scanForNetworks(). We init the manager, kick it, hold a
+    //      reference for the lifetime of the function so the runtime
+    //      can't release it before the scan call hits CoreWLAN.
+    //
+    // The earlier code comment claiming CoreLocation was "more lenient"
+    // than CoreBluetooth was wrong; CoreWLAN on macOS 26 enforces both.
+    if ProcessInfo.processInfo.environment[kDisclaimEnv] == nil {
+        reExecWithDisclaimedResponsibility()
+    }
+
+    let locationManager = CLLocationManager()
+    locationManager.requestWhenInUseAuthorization()
+    locationManager.startUpdatingLocation()
+    // Brief settle so CoreLocation's TCC registration lands before
+    // CoreWLAN inspects it. Empirically ~50ms is enough on M-series
+    // Macs; 300ms gives headroom on slower hardware without making
+    // the user wait an obvious extra beat.
+    Thread.sleep(forTimeInterval: 0.3)
+    _ = locationManager  // hold the reference until the scan returns
+
     let client = CWWiFiClient.shared()
     guard let iface = client.interface() else {
         emitError("no Wi-Fi interface")
@@ -854,6 +891,73 @@ func runBluetoothStatusProbe() -> Never {
     dispatchMain()
 }
 
+// ---------------------------------------------------------------------
+// App-mode localization
+//
+// Resolution order matches the Python CLI's i18n: DITING_LANG env var
+// first (so `open --env DITING_LANG=zh bundle.app` from the Python
+// launcher wins), then the user's macOS locale preference. install.sh's
+// first-launch `open -g` can't pass env, so the macOS preference is the
+// fallback that gets the first popup right for a Chinese-locale user.
+// ---------------------------------------------------------------------
+
+private enum HelperLang { case en, zh }
+
+private func detectHelperLang() -> HelperLang {
+    if let env = ProcessInfo.processInfo.environment["DITING_LANG"]?.lowercased() {
+        return env == "zh" ? .zh : .en
+    }
+    if let pref = Locale.preferredLanguages.first?.lowercased(),
+       pref.hasPrefix("zh") {
+        return .zh
+    }
+    return .en
+}
+
+private struct HelperStrings {
+    let lang: HelperLang
+    var title: String        { lang == .zh ? "diting 天耳" : "diting tianer" }
+    var intro: String {
+        switch lang {
+        case .zh:
+            return "这个辅助 .app 让 diting（Python TUI）能够读取附近 Wi-Fi 的 SSID / BSSID，并扫描附近 BLE 设备 —— 否则 macOS 的「定位服务」和「蓝牙」权限会拦下 Python 进程。下面的弹窗点 Allow 各一次（只用一次），授权完毕关闭此窗口即可。"
+        case .en:
+            return "This helper exists so diting (the Python TUI) can read nearby Wi-Fi network names / BSSIDs and scan for nearby BLE devices without being blocked by macOS Location Services or Bluetooth permissions. Grant the prompts below — a one-time action — and you can close this window."
+        }
+    }
+    var requestingStatus: String { lang == .zh ? "正在请求权限…" : "Requesting permissions..." }
+    var allGranted: String {
+        switch lang {
+        case .zh:
+            return "全部权限已授予。本窗口将在几秒后自动关闭…"
+        case .en:
+            return "All permissions granted. This window will close automatically in a few seconds..."
+        }
+    }
+    // Location lines
+    func locationWaiting() -> String { lang == .zh ? "定位服务：等待用户决定…" : "Location: waiting for permission decision..." }
+    func locationRestricted() -> String { lang == .zh ? "定位服务：被系统策略限制。" : "Location: restricted by a system policy." }
+    func locationDenied() -> String {
+        lang == .zh
+            ? "定位服务：被拒绝。请到 系统设置 → 隐私与安全性 → 定位服务 → diting-tianer 启用。"
+            : "Location: denied. Enable it in System Settings → Privacy & Security → Location Services → diting-tianer."
+    }
+    func locationGranted() -> String { lang == .zh ? "定位服务：已授权。" : "Location: granted." }
+    func locationUnknown(_ raw: Int) -> String { lang == .zh ? "定位服务：未知状态 \(raw)。" : "Location: unknown state \(raw)." }
+    // Bluetooth lines
+    func bluetoothQuerying() -> String { lang == .zh ? "蓝牙：正在查询状态…" : "Bluetooth: querying state..." }
+    func bluetoothResetting() -> String { lang == .zh ? "蓝牙：正在重置…" : "Bluetooth: resetting..." }
+    func bluetoothUnsupported() -> String { lang == .zh ? "蓝牙：本机硬件不支持。" : "Bluetooth: unsupported on this hardware." }
+    func bluetoothUnauthorized() -> String {
+        lang == .zh
+            ? "蓝牙：被拒绝。请到 系统设置 → 隐私与安全性 → 蓝牙 → diting-tianer 启用。"
+            : "Bluetooth: denied. Enable it in System Settings → Privacy & Security → Bluetooth → diting-tianer."
+    }
+    func bluetoothOff() -> String { lang == .zh ? "蓝牙：已关闭。请在控制中心打开蓝牙。" : "Bluetooth: turned off. Toggle it on in Control Center." }
+    func bluetoothGranted() -> String { lang == .zh ? "蓝牙：已授权。" : "Bluetooth: granted." }
+    func bluetoothUnknown(_ raw: Int) -> String { lang == .zh ? "蓝牙：未知状态 \(raw)。" : "Bluetooth: unknown state \(raw)." }
+}
+
 // ---------------------------------------------------------------------
 // App mode (Finder launch / open)
 // ---------------------------------------------------------------------
@@ -865,6 +969,8 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, CLLocationManage
     private var bluetoothManager: CBCentralManager!
     private var locationGranted = false
     private var bluetoothGranted = false
+    private var autoCloseScheduled = false
+    private let strings = HelperStrings(lang: detectHelperLang())
 
     func applicationDidFinishLaunching(_ notification: Notification) {
         let frame = NSRect(x: 0, y: 0, width: 520, height: 280)
@@ -874,7 +980,7 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, CLLocationManage
             backing: .buffered,
             defer: false
         )
-        window.title = "diting tianer"
+        window.title = strings.title
         window.center()
 
         let body = NSStackView(frame: NSRect(x: 24, y: 24, width: 472, height: 232))
@@ -883,21 +989,15 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, CLLocationManage
         body.spacing = 12
         body.translatesAutoresizingMaskIntoConstraints = false
 
-        let title = NSTextField(labelWithString: "diting tianer")
+        let title = NSTextField(labelWithString: strings.title)
         title.font = NSFont.systemFont(ofSize: 18, weight: .semibold)
         body.addArrangedSubview(title)
 
-        let intro = NSTextField(wrappingLabelWithString:
-            "This helper exists so diting (the Python TUI) can read " +
-            "nearby Wi-Fi network names / BSSIDs and scan for nearby BLE " +
-            "devices without being blocked by macOS Location Services or " +
-            "Bluetooth permissions. Grant the prompts below — a one-time " +
-            "action — and you can close this window."
-        )
+        let intro = NSTextField(wrappingLabelWithString: strings.intro)
         intro.preferredMaxLayoutWidth = 472
         body.addArrangedSubview(intro)
 
-        statusLabel = NSTextField(wrappingLabelWithString: "Requesting permissions...")
+        statusLabel = NSTextField(wrappingLabelWithString: strings.requestingStatus)
         statusLabel.font = NSFont.systemFont(ofSize: 13, weight: .regular)
         statusLabel.preferredMaxLayoutWidth = 472
         body.addArrangedSubview(statusLabel)
@@ -953,13 +1053,17 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, CLLocationManage
         lines.append(bluetoothLine(btState))
         statusLabel.stringValue = lines.joined(separator: "\n")
 
-        if locationGranted && bluetoothGranted {
-            statusLabel.stringValue += "\n\nAll permissions granted. This window will close automatically..."
-            // Give the user ~1.5 s to read the message, then exit so
-            // they do not have to find Cmd+Q. The TCC grants are
-            // persistent — diting's Python TUI immediately picks
-            // them up the next time it polls the helper.
-            DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) {
+        if locationGranted && bluetoothGranted && !autoCloseScheduled {
+            autoCloseScheduled = true
+            statusLabel.stringValue += "\n\n" + strings.allGranted
+            // 4 s gives the user a beat to actually read "All
+            // permissions granted" before the window vanishes. The
+            // 1.5 s default felt too snappy and a few users
+            // reported being confused that the window blinked
+            // closed. TCC grants are persistent — diting's Python
+            // launcher will pick them up on its next poll cycle
+            // regardless of how long this window stays up.
+            DispatchQueue.main.asyncAfter(deadline: .now() + 4.0) {
                 NSApp.terminate(nil)
             }
         }
@@ -968,34 +1072,34 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, CLLocationManage
     private func locationLine(_ status: CLAuthorizationStatus) -> String {
         switch status {
         case .notDetermined:
-            return "Location: waiting for permission decision..."
+            return strings.locationWaiting()
         case .restricted:
-            return "Location: restricted by a system policy."
+            return strings.locationRestricted()
         case .denied:
-            return "Location: denied. Enable it in System Settings → Privacy & Security → Location Services → diting-tianer."
+            return strings.locationDenied()
         case .authorizedAlways, .authorizedWhenInUse:
-            return "Location: granted."
+            return strings.locationGranted()
         @unknown default:
-            return "Location: unknown state \(status.rawValue)."
+            return strings.locationUnknown(Int(status.rawValue))
         }
     }
 
     private func bluetoothLine(_ state: CBManagerState) -> String {
         switch state {
         case .unknown:
-            return "Bluetooth: querying state..."
+            return strings.bluetoothQuerying()
         case .resetting:
-            return "Bluetooth: resetting..."
+            return strings.bluetoothResetting()
         case .unsupported:
-            return "Bluetooth: unsupported on this hardware."
+            return strings.bluetoothUnsupported()
         case .unauthorized:
-            return "Bluetooth: denied. Enable it in System Settings → Privacy & Security → Bluetooth → diting-tianer."
+            return strings.bluetoothUnauthorized()
         case .poweredOff:
-            return "Bluetooth: turned off. Toggle it on in Control Center."
+            return strings.bluetoothOff()
         case .poweredOn:
-            return "Bluetooth: granted."
+            return strings.bluetoothGranted()
         @unknown default:
-            return "Bluetooth: unknown state \(state.rawValue)."
+            return strings.bluetoothUnknown(Int(state.rawValue))
         }
     }
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "diting"
-version = "1.0.2"
+version = "1.0.3"
 description = "macOS terminal listening post for Wi-Fi, BLE, link health, and the RF environment — your Mac hears more than it tells you"
 readme = "README.md"
 license = "MIT"

src/diting/cli.py

@@ -891,8 +891,24 @@ def _ensure_helper_ready() -> str | None:
     print(t("(Ctrl+C to skip and start the TUI with degraded views.)"))
     print()
     try:
+        # `open --env KEY=VALUE` bridges our process env into the
+        # LaunchServices-spawned bundle. Without this, the bundle would
+        # inherit the user's login session env, which doesn't know
+        # anything about diting's --lang flag, and the popup window
+        # would show English even when the user is running
+        # `diting --lang zh`. We pass DITING_LANG explicitly so the
+        # Swift HelperAppDelegate's HelperStrings struct picks the
+        # right localisation. The bundle falls back to
+        # `Locale.preferredLanguages` if we don't set this, which
+        # covers install.sh's first-launch `open -g` call (no Python
+        # in the chain to know about --lang yet).
+        open_argv = [
+            "/usr/bin/open",
+            "--env", f"DITING_LANG={i18n.get_lang()}",
+            bundle,
+        ]
         subprocess.Popen(
-            ["/usr/bin/open", bundle],
+            open_argv,
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
         )
     except OSError as e: