fix: address PR #42 review findings

Addresses CodeRabbit's 5 findings (cubic.dev was clean):

1. docs/changelog.md — clarify the live TUI events cap is now
   min(30, visible_panel_rows), not a flat 30, since the second
   commit made it height-bound.

2. docs/configuration.md — make all four example commands use the
   same `sudo eneru ...` invocation form. Earlier draft mixed the
   wrapper-path form with the bare command; maintainer prefers
   the bare form (PATH-resolved) consistently.

3. src/eneru/tui.py — three-tier trim instead of two: POWER_EVENTS
   always survive; LIFECYCLE_EVENTS fill next; chatter rounds out
   only if room remains. In --verbose mode the previous code let
   chatter evict lifecycle rows when the cap was hit; the new tier
   matches the user-facing priority hierarchy.

4. tests/test_tui.py — rename single-letter loop var `l` to `line`
   in five spots (Ruff E741).

5. tests/e2e/groups/stats.sh — wrap the `--length 5` invocation in
   `if cmd; then ... fi`. Under `set -e` the previous bare
   `[ $? -ne 0 ]` branch would never run because the script aborts
   on the first non-zero exit, masking any regression with no log
   dump.

Plus one new unit test (`test_tiered_trim_lifecycle_outranks_chatter`)
covering the new 3-tier semantics: 1 power + 30 chatter + 4 lifecycle
at cap=7 produces 1 power + 4 lifecycle + 2 chatter, NOT 1 power +
6 chatter.

982 unit tests pass (was 981).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: m4r1k

docs/changelog.md

@@ -35,7 +35,9 @@ Bug-fix release. Drop-in upgrade.
 ### Changed
 - `--time` and `<T>` apply to the graph only. Use `--length` for events.
 - Events panel defaults to priority-only.
-- Live TUI events cap raised from 8 to 30 rows.
+- Live TUI events cap raised (now `min(30, visible_panel_rows)` so
+  power events stay inside the visible window on smaller terminals;
+  `<M>` still expands to 500 rows for full scrollable history).
 
 ### Migration notes
 - Scripts grepping `--events-only` output for low-priority event

docs/configuration.md

@@ -442,5 +442,5 @@ Example package commands:
 sudo eneru validate --config /etc/ups-monitor/config.yaml
 sudo eneru run --dry-run --config /etc/ups-monitor/config.yaml
 sudo eneru monitor --once --events-only --config /etc/ups-monitor/config.yaml
-sudo /opt/ups-monitor/eneru.py monitor --once --events-only --verbose --length 100 --config /etc/ups-monitor/config.yaml
+sudo eneru monitor --once --events-only --verbose --length 100 --config /etc/ups-monitor/config.yaml
 ```

src/eneru/tui.py

@@ -429,11 +429,11 @@ def query_events_for_display(
 
     ``max_events=None`` (or 0) disables the row cap entirely.
 
-    Trim is **tiered**: when capping, every row in :data:`POWER_EVENTS`
-    is preserved, then remaining slots are filled with the most-recent
-    :data:`LIFECYCLE_EVENTS` and other priority rows. Daemon noise can
-    therefore never push power events off-screen, even when the cap is
-    20 and the most recent 50 events are all daemon restarts.
+    Trim is **3-tier**: POWER_EVENTS always survive the cap; remaining
+    slots are filled first with most-recent LIFECYCLE_EVENTS, then with
+    chatter (only reachable when ``priority_only=False`` widens the
+    upstream filter). Power events are never evicted; lifecycle context
+    outranks voltage-flap chatter when the cap is hit in verbose mode.
     """
     multi_ups = config.multi_ups
     rows: List[tuple] = []  # (ts, label, event_type, detail)
@@ -470,22 +470,33 @@ def query_events_for_display(
 
     rows.sort(key=lambda r: r[0])
 
-    # Tiered trim: power events always survive the cap. ``max_events``
-    # in (None, 0) means no cap.
+    # Three-tier trim: POWER_EVENTS always survive; if room left,
+    # LIFECYCLE_EVENTS fill next; only then chatter (other rows that
+    # made it through ``priority_only=False``). This matches the
+    # priority hierarchy users care about: power transitions are
+    # never evicted, daemon-lifecycle context is preferred over
+    # voltage-flap chatter, and chatter rounds out the cap when
+    # ``--verbose`` is on. ``max_events`` in (None, 0) means no cap.
     if max_events and len(rows) > max_events:
         power = [r for r in rows if r[2] in POWER_EVENTS]
-        non_power = [r for r in rows if r[2] not in POWER_EVENTS]
+        lifecycle = [r for r in rows if r[2] in LIFECYCLE_EVENTS]
+        chatter = [r for r in rows
+                   if r[2] not in POWER_EVENTS and r[2] not in LIFECYCLE_EVENTS]
         if len(power) >= max_events:
             # Pathological: more power events than the cap. Show the
             # most-recent N -- still better than evicting them.
             kept = power[-max_events:]
         else:
             remaining = max_events - len(power)
-            kept_non_power = non_power[-remaining:]
+            # Lifecycle fills first; chatter only if room remains.
+            kept_lifecycle = lifecycle[-remaining:]
+            remaining -= len(kept_lifecycle)
+            kept_chatter = chatter[-remaining:] if remaining > 0 else []
             # Re-sort by ts so the panel never displays out-of-time-order
             # rows after the tier merge. Python's sort is stable, so
-            # equal-timestamp rows preserve insertion order (power first).
-            kept = sorted(power + kept_non_power, key=lambda r: r[0])
+            # equal-timestamp rows preserve insertion order.
+            kept = sorted(power + kept_lifecycle + kept_chatter,
+                          key=lambda r: r[0])
         rows = kept
 
     return [_format_event_line(ts, label, etype, detail, multi_ups)

tests/e2e/groups/stats.sh

@@ -264,8 +264,12 @@ echo "  PASS: priority-only filter hides chatter, keeps DAEMON_START"
 # --length 5 caps output. There's only one daemon-lifecycle event in the
 # stats DB at this point (from the daemon's own DAEMON_START), so we
 # can't easily count to 5 here -- just confirm --length runs cleanly.
-eneru monitor --once --events-only --length 5 --config "$E2E_DIR/config-e2e-stats.yaml" > /tmp/test31-length.log 2>&1
-if [ $? -ne 0 ]; then
+# Wrap the invocation in the `if` directly: under `set -e` a separate
+# `[ $? -ne 0 ]` branch would never run because the script aborts on
+# the first non-zero exit, masking any regression with no log dump.
+if ! eneru monitor --once --events-only --length 5 \
+    --config "$E2E_DIR/config-e2e-stats.yaml" \
+    > /tmp/test31-length.log 2>&1; then
   echo "FAIL: --length 5 returned non-zero"
   cat /tmp/test31-length.log
   exit 1

tests/test_tui.py

@@ -1239,16 +1239,16 @@ def test_tiered_trim_preserves_power_events(self, tmp_path):
 
         lines = query_events_for_display(config, max_events=20)
         # All 3 power-event rows MUST survive the cap.
-        assert any("ON_BATTERY: real outage" in l for l in lines), (
+        assert any("ON_BATTERY: real outage" in line for line in lines), (
             f"ON_BATTERY pushed off by daemon noise -- tiered trim regressed. "
             f"Got: {lines}"
         )
-        assert any("POWER_RESTORED: outage 10m" in l for l in lines)
-        assert any("EMERGENCY_SHUTDOWN_INITIATED" in l for l in lines)
+        assert any("POWER_RESTORED: outage 10m" in line for line in lines)
+        assert any("EMERGENCY_SHUTDOWN_INITIATED" in line for line in lines)
         # Result respects the cap.
         assert len(lines) == 20
         # Remaining 17 slots are most-recent daemon rows.
-        daemon_lines = [l for l in lines if "DAEMON_RESTARTED" in l]
+        daemon_lines = [line for line in lines if "DAEMON_RESTARTED" in line]
         assert len(daemon_lines) == 17
 
     @pytest.mark.unit
@@ -1271,9 +1271,48 @@ def test_tiered_trim_pathological_more_power_than_cap(self, tmp_path):
         lines = query_events_for_display(config, max_events=10)
         # 10 most-recent ON_BATTERY rows; daemon entirely evicted.
         assert len(lines) == 10
-        assert all("ON_BATTERY" in l for l in lines)
-        assert any("outage-49" in l for l in lines)  # latest power event
-        assert any("outage-40" in l for l in lines)  # 10th-latest
+        assert all("ON_BATTERY" in line for line in lines)
+        assert any("outage-49" in line for line in lines)  # latest power event
+        assert any("outage-40" in line for line in lines)  # 10th-latest
+
+    @pytest.mark.unit
+    def test_tiered_trim_lifecycle_outranks_chatter(self, tmp_path):
+        """5.2.2 (CodeRabbit refinement): in --verbose mode (priority_only
+        =False), chatter rows reach the trim layer alongside lifecycle
+        rows. Lifecycle is more important than per-condition chatter --
+        when the cap evicts non-power rows, lifecycle should survive
+        first, then chatter fills any leftover slots."""
+        from eneru.tui import query_events_for_display
+        import time as _time
+        config = _events_config(tmp_path)
+        now = int(_time.time())
+        # 1 power event + 30 chatter rows + 4 lifecycle rows.
+        # Cap = 7. Result must be: 1 power + 4 lifecycle + 2 chatter,
+        # NOT: 1 power + 6 chatter (chatter evicting lifecycle).
+        events = [(now - 5000, "ON_BATTERY", "outage")]
+        for i in range(30):
+            events.append(
+                (now - 1000 + i, "VOLTAGE_FLAP_SUPPRESSED", f"flap-{i}")
+            )
+        for i in range(4):
+            events.append(
+                (now - 100 + i * 10, "DAEMON_RESTARTED", f"d-{i}")
+            )
+        _seed_events(config, config.ups_groups[0], events)
+
+        lines = query_events_for_display(
+            config, max_events=7, priority_only=False,
+        )
+        assert len(lines) == 7
+        assert sum("ON_BATTERY" in line for line in lines) == 1, (
+            f"power event must survive: {lines}"
+        )
+        assert sum("DAEMON_RESTARTED" in line for line in lines) == 4, (
+            f"all 4 lifecycle rows must outrank chatter; got: {lines}"
+        )
+        assert sum("VOLTAGE_FLAP_SUPPRESSED" in line for line in lines) == 2, (
+            f"chatter fills only the 2 leftover slots; got: {lines}"
+        )
 
 
 class TestRobustBounds: