fix(event-log): session_meta carries at-launch SSID + gateway_ip (v1.7.1) (#121)

Pre-existing race shipped with v1.6.0 (when session_meta first
landed) and surfaced by the v1.7.0 release-binary smoke audit:

```jsonl
# Captured `diting monitor` against a host actually associated to tedo_5G:
{"type":"session_meta","ssid":null,"gateway_ip":null, …}   ← stale at write time
{"type":"link_state","ssid":"tedo_5G","bssid":"40:fe:95:8a:3c:58", …}  ← ms later, real state
```

`session_meta` is the first line of the JSONL stream and is supposed
to carry the at-launch context downstream readers (the analyzer's
"Scene + connection" header, the `--for-llm` prompt bundle, any
third-party `jq` script) use to interpret the session. Writing
`null` for SSID / gateway when the host is in fact associated made
the analyzer report "session started disassociated" — wrong by
construction.

Root cause: both call sites — `_run_monitor` in `cli.py` and
`DitingApp.__init__` in `tui.py` — invoked `emit_session_meta`
synchronously during startup, but the first WiFiPoller snapshot
(which populates `_latest_connection`) hadn't run yet. SSID +
gateway_ip were never threaded into the call, so they defaulted
to None.

Fix: both call sites now invoke `backend.get_connection()` once,
synchronously, BEFORE emitting `session_meta`. `get_connection()`
on `MacOSWiFiBackend` is sync and cheap (reads SCDynamicStore /
helper subprocess result, ~5ms). Failures (helper not ready, no
Wi-Fi yet) are absorbed via try/except → values default to None,
preserving the disassociated-at-launch path that no-Wi-Fi cold
launches need.

Verified against the live network:

```jsonl
{"type":"session_meta","scene":"home","scene_source":"auto",
 "diting_version":"1.7.1","ssid":"tedo_5G","gateway_ip":"192.168.124.1",
 "hostname":"…"}
```

Tests (+2 new, 1049/1049 total):

- `test_app_session_meta_carries_startup_ssid_and_gateway` — direct
  regression: DitingApp with a `_FakeBackend` that returns
  Connection(ssid="testnet", router_ip="10.0.0.1") writes a
  session_meta carrying both.
- `test_app_session_meta_absorbs_get_connection_failure` —
  adversarial: backend whose `get_connection()` raises
  `OSError("helper not ready")` still produces a valid
  session_meta with ssid / gateway_ip = None and doesn't crash
  app startup.

CHANGELOG + ZH CHANGELOG + TESTING.md (EN + ZH) updated.

Version: `pyproject.toml` 1.7.0 → 1.7.1.

Validates: pytest 1049/1049 ✓
           openspec validate --specs --strict (22/22) ✓

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

Author: chenchaoyi

CHANGELOG.md

@@ -11,6 +11,26 @@ behaviours between releases.
 
 ## [Unreleased]
 
+## [1.7.1] — 2026-05-23
+
+Patch release. **`session_meta` JSONL header now carries the at-
+launch SSID + gateway_ip** — pre-v1.7.1 the call ran before the
+first WiFi poll completed and the first line of every session log
+reported `ssid: null` / `gateway_ip: null` even when the host was
+associated. Downstream consumers (the analyzer, the `--for-llm`
+prompt bundle, third-party `jq` scripts) would misread the
+session as having started disassociated.
+
+### Fixed
+- **`emit_session_meta` populates SSID + gateway from a synchronous
+  startup `get_connection()`.** Both call sites (`_run_monitor` in
+  `cli.py`, `DitingApp.__init__` in `tui.py`) now fetch the
+  connection once before the JSONL header is written. Failure
+  (helper not ready, no Wi-Fi yet) is absorbed as `None` so the
+  no-Wi-Fi cold-launch path keeps working. Pre-existing race
+  shipped with v1.6.0; surfaced by the v1.7.0 release-binary
+  smoke audit.
+
 ## [1.7.0] — 2026-05-23
 
 Minor release. **LAN identification expansion** — the LAN view now

docs/zh/CHANGELOG.md

@@ -10,6 +10,13 @@
 
 ## [Unreleased]
 
+## [1.7.1] — 2026-05-23
+
+Patch release。**`session_meta` JSONL 头部现在带启动时的 SSID + 网关 IP** —— v1.7.1 之前，emit_session_meta 在第一次 WiFi 轮询完成前调用，每个 session log 的首行都把 `ssid` / `gateway_ip` 写成 `null`，哪怕主机一直是连着 Wi-Fi 的。下游消费者（analyzer、`--for-llm` 提示包、第三方 `jq` 脚本）会把会话误读为"启动时未关联 Wi-Fi"。
+
+### 修复
+- **`emit_session_meta` 在写头部前同步取一次 `get_connection()`，把 SSID + 网关填进去。** `_run_monitor`（cli.py）和 `DitingApp.__init__`（tui.py）两个调用点都改了。`get_connection()` 抛错时（helper 未就绪 / 没 Wi-Fi）吞掉异常，回退为 `None`，所以未关联场景的冷启动路径继续可用。这个时序 race 自 v1.6.0 起就有，由 v1.7.0 发版后的 release-binary 烟雾审计发现。
+
 ## [1.7.0] — 2026-05-23
 
 Minor release。**LAN 识别能力扩展** —— LAN 视图现在能识别国内

docs/zh/TESTING.md

@@ -196,6 +196,7 @@
 | Requirement | 测试 |
 |---|---|
 | `session_meta` 在第一行；带 scene + scene_source + diting_version + ssid + gateway_ip + hostname；emit 幂等；disabled logger 是 no-op；SSID / gateway 允许 null 写入 | `test_event_log.py::test_session_meta_writes_header_with_all_fields`、`::test_session_meta_is_first_when_emitted_first`、`::test_session_meta_is_idempotent`、`::test_session_meta_disabled_logger_is_no_op`、`::test_session_meta_accepts_null_ssid_and_gateway` |
+| **v1.7.1** —— `DitingApp.__init__` 和 `_run_monitor` 都在 emit `session_meta` 之前同步 `backend.get_connection()`，让 JSONL 头部带启动时的 SSID + 网关 IP，而不是 null。Backend 抛错（helper 未就绪、还没 Wi-Fi）时回退为 None | `test_tui_smoke.py::test_app_session_meta_carries_startup_ssid_and_gateway`、`::test_app_session_meta_absorbs_get_connection_failure` |
 | `--log` 与 `diting monitor` 输出字节相等 | `test_event_log.py::test_to_path_writes_appendable_jsonl`、`::test_unicode_user_strings_survive_readable`（共享 writer 类） |
 | 每个事件后强制 flush | `test_event_log.py::test_line_buffered_writes_are_visible_before_close` |
 | atexit 钩子优雅关闭 writer | (gap — 没有专门的测试；行为在 `test_line_buffered_writes_are_visible_before_close` 里间接覆盖) |

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "diting"
-version = "1.7.0"
+version = "1.7.1"
 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

@@ -286,10 +286,24 @@ async def _run_monitor(
     # to the TUI's --log path so downstream readers don't branch on
     # source. Scene was resolved by main() before dispatching; we
     # only thread the source through here.
+    #
+    # Synchronously fetch the connection ONCE before emitting so
+    # session_meta carries the at-launch SSID + gateway_ip rather
+    # than null. Pre-v1.7.1 this call ran before any poll
+    # completed and every session_meta line reported `ssid: null`
+    # even when the host was associated. Failure (no Wi-Fi yet,
+    # helper not ready) is absorbed as None so the disassociated-
+    # at-launch path keeps working.
     from . import scene as _scene_mod
+    try:
+        startup_conn = backend.get_connection()
+    except Exception:
+        startup_conn = None
     logger.emit_session_meta(
         scene=_scene_mod.get_scene(),
         scene_source=scene_source,
+        ssid=startup_conn.ssid if startup_conn else None,
+        gateway_ip=startup_conn.router_ip if startup_conn else None,
     )
 
     poller = WiFiPoller(backend)

src/diting/tui.py

@@ -6211,13 +6211,28 @@ def __init__(
             else EventLogger.disabled()
         )
         # Session header — written immediately so any subsequent
-        # emit_* (which may fire before the first ConnectionUpdate
-        # gives us SSID / gateway) lands AFTER the session_meta
-        # line. SSID / gateway are filled in here if known at this
-        # point, else null; downstream consumers expect the field
-        # to exist either way. No-op on the disabled logger.
+        # emit_* lands AFTER the session_meta line. Synchronously
+        # fetch the current connection ONCE here (before the
+        # WiFiPoller's async loop has had a chance to publish its
+        # first snapshot) so SSID + gateway_ip carry the actual
+        # at-launch values rather than null. Pre-v1.7.1 the call
+        # ran before the first poll completed, so every session_meta
+        # reported `ssid: null` / `gateway_ip: null` even when the
+        # user was associated — broke the analyzer's "session
+        # started on AP X" timeline. `get_connection()` is sync
+        # and cheap; failure (no Wi-Fi yet, helper not ready) is
+        # absorbed as None so the no-Wi-Fi path keeps working.
+        try:
+            startup_conn = backend.get_connection()
+        except Exception:
+            startup_conn = None
+        startup_ssid = startup_conn.ssid if startup_conn else None
+        startup_gateway = startup_conn.router_ip if startup_conn else None
         self._event_logger.emit_session_meta(
-            scene=scene, scene_source=scene_source,
+            scene=scene,
+            scene_source=scene_source,
+            ssid=startup_ssid,
+            gateway_ip=startup_gateway,
         )
         self._event_log_path = event_log_path
         # Per-(event_type, target) last-emit monotonic timestamp,

tests/TESTING.md

@@ -205,6 +205,7 @@ When a new Requirement lands in any spec, an entry MUST be added here
 | Requirement | Test |
 |---|---|
 | `session_meta` line is first; carries scene + scene_source + diting_version + ssid + gateway_ip + hostname; emit is idempotent; disabled logger is no-op; null SSID / gateway are written through | `test_event_log.py::test_session_meta_writes_header_with_all_fields`, `::test_session_meta_is_first_when_emitted_first`, `::test_session_meta_is_idempotent`, `::test_session_meta_disabled_logger_is_no_op`, `::test_session_meta_accepts_null_ssid_and_gateway` |
+| **v1.7.1** — Both `DitingApp.__init__` and `_run_monitor` synchronously fetch `backend.get_connection()` BEFORE emitting `session_meta`, so the JSONL header carries the at-launch SSID + gateway_ip rather than null. Backend failures (helper not ready, no Wi-Fi yet) are absorbed as None | `test_tui_smoke.py::test_app_session_meta_carries_startup_ssid_and_gateway`, `::test_app_session_meta_absorbs_get_connection_failure` |
 | `--log` and `diting monitor` produce byte-identical streams | `test_event_log.py::test_to_path_writes_appendable_jsonl`, `::test_unicode_user_strings_survive_readable` (single shared writer class) |
 | Writer flushes after every event | `test_event_log.py::test_line_buffered_writes_are_visible_before_close` |
 | atexit hook closes writer cleanly | (gap — no direct test; behaviour validated by `test_line_buffered_writes_are_visible_before_close`) |

tests/test_tui_smoke.py

@@ -1126,3 +1126,70 @@ async def go():
             await pilot.press("q")
 
     asyncio.run(go())
+
+
+# ---------- v1.7.1 regression: session_meta carries at-launch SSID + gateway ----------
+
+
+def test_app_session_meta_carries_startup_ssid_and_gateway(tmp_path):
+    """v1.7.1 regression: DitingApp.__init__ must synchronously fetch
+    backend.get_connection() and pass ssid + gateway_ip into
+    emit_session_meta. Pre-v1.7.1 the call ran before the first
+    WiFi poll completed and every session_meta carried `ssid: null`
+    / `gateway_ip: null` even when the host was associated."""
+    import json
+
+    log_path = tmp_path / "events.jsonl"
+    DitingApp(
+        _FakeBackend(),
+        _INVENTORY,
+        event_log_path=str(log_path),
+    )
+    # __init__ alone (no .run()) is enough — emit_session_meta is
+    # called synchronously inside __init__.
+    [first] = log_path.read_text().splitlines()
+    meta = json.loads(first)
+    assert meta["type"] == "session_meta"
+    assert meta["ssid"] == "testnet"          # from _FakeBackend.get_connection
+    assert meta["gateway_ip"] == "10.0.0.1"   # ditto
+    assert meta["diting_version"]  # populated
+    assert meta["scene"] == "home"           # DitingApp default
+
+
+class _BackendThatRaisesOnGetConnection(WiFiBackend):
+    """Backend whose get_connection raises (helper not ready, etc.).
+    The session_meta path must absorb the exception and write null
+    for ssid / gateway_ip rather than crashing app startup."""
+
+    name = "raising"
+
+    def __init__(self) -> None:
+        self._helper_path = None
+
+    def get_connection(self) -> Connection | None:
+        raise OSError("helper not ready")
+
+    def scan(self) -> list[ScanResult]:
+        return []
+
+    def permission_state(self) -> Any:
+        return "unknown"
+
+
+def test_app_session_meta_absorbs_get_connection_failure(tmp_path):
+    """When backend.get_connection() raises (e.g. helper bundle not
+    finished launching), session_meta still writes successfully with
+    ssid / gateway_ip set to None — the app startup must not crash."""
+    import json
+
+    log_path = tmp_path / "events.jsonl"
+    DitingApp(
+        _BackendThatRaisesOnGetConnection(),
+        _INVENTORY,
+        event_log_path=str(log_path),
+    )
+    [first] = log_path.read_text().splitlines()
+    meta = json.loads(first)
+    assert meta["type"] == "session_meta"
+    assert meta["ssid"] is None
+    assert meta["gateway_ip"] is None