feat(cli): upgrade status to an active telemetry dashboard (#50)

JacksonFergusonDev · web-flow · commit deceea94c47b · 2026-02-20T17:07:38.000-08:00
- refactor(core): decouple large file detection (`has_large_files`) from daemon into `ops.py` for safe CLI querying.
- feat(cli): surface real-time power telemetry (Eco-Mode/Critical states) in the system status panel.
- feat(cli): integrate zero-latency cached remote drift warnings and pipeline blocker alerts into the repo status dashboard.
- fix(test): dynamically mock the system strategy factory to prevent `MacOSStrategy` from leaking AppleScript notifications during test execution.
- test: add parameterized coverage for dynamic health thresholds and UI telemetry rendering.
- docs: update architecture maps and documentation to reflect the new Active Observability feature.
diff --git a/README.md b/README.md
@@ -62,6 +62,7 @@ In a distributed environment (Laptop ↔ Desktop), state drift is inevitable.
 - **Out-of-Band Indexing:** Backups are stored in a configured namespace (default: `refs/heads/wip/pulsar/...`). Your `git status`, `git branch`, and `git log` remain completely clean.
 - **Distributed Sessions:** Hop between machines. Pulsar tracks sessions per device and lets you `sync` to pick up exactly where you left off.
 - **State-Aware Diagnostics:** The `doctor` command correlates transient log events with active system health to prevent alert fatigue, and proactively scans for pipeline blockers like strict git hooks or broken `systemd` configurations.
+- **Active Observability:** The `status` dashboard provides zero-latency power telemetry (e.g., Eco-Mode throttling) and immediately surfaces cached warnings for remote session drift and oversized files.
 - **Zero-Interference:**
   - Uses a temporary index so it never messes up your partial `git add`.
   - Detects if you are rebasing or merging and waits for you to finish.
@@ -186,7 +187,7 @@ This bootstraps the current directory with:
 
 | Command | Description |
 | :--- | :--- |
-| `git pulsar status` | Show detailed daemon state and repository-specific commit/push history. |
+| `git pulsar status` | Show real-time daemon telemetry, active health blockers, and repository status. |
 | `git pulsar config` | Open the global configuration file in your default editor. |
 | `git pulsar list` | Show all watched repositories and their status. |
 | `git pulsar pause` | Temporarily suspend backups for this repo. |
diff --git a/src/README.md b/src/README.md
@@ -12,7 +12,7 @@ The `src/` directory contains the package source code. The architecture strictly
   - **Safety:** Implements `GIT_INDEX_FILE` isolation to ensure it never locks or corrupts the user's active git index.
 - **`git_pulsar/ops.py`**: High-level Business Logic.
   - **Role:** The "Controller." It orchestrates complex multi-step operations like `finalize` (Octopus Merges), `restore`, and drift detection.
-  - **Logic:** Calculates the "Zipper Graph" topology to merge shadow commits back into the main branch, and manages atomic file I/O for cross-process state tracking.
+  - **Logic:** Calculates the "Zipper Graph" topology to merge shadow commits back into the main branch, manages atomic file I/O for cross-process state tracking, and evaluates pipeline blockers (e.g., oversized files).
 - **`git_pulsar/config.py`**: Configuration Engine.
   - **Role:** The "Source of Truth."
   - **Logic:** Implements a cascading hierarchy (Defaults → Global → Local) to merge settings from `~/.config/git-pulsar/config.toml` and project-level `pulsar.toml` or `pyproject.toml`.
@@ -35,8 +35,8 @@ The `src/` directory contains the package source code. The architecture strictly
 ### 4. The Interface
 
 - **`git_pulsar/cli.py`**: The User Entry Point & Diagnostic Engine.
-  - **Role:** Argument parsing, UI rendering, and system health evaluation.
-  - **Logic:** Uses `rich` for terminal visualization. Beyond routing subcommands to `ops.py` and `daemon.py`, it presents the `doctor` diagnostics. It correlates repository state against transient event logs, and relies on `ops.py` to evaluate topological drift across distributed sessions and scan for host-environment pipeline blockers (e.g., strict git hooks, missing `systemd` linger).
+  - **Role:** Argument parsing, UI rendering, real-time observability, and system health evaluation.
+  - **Logic:** Uses `rich` for terminal visualization. Beyond routing subcommands to `ops.py` and `daemon.py`, it presents the `doctor` diagnostics and the zero-latency `status` dashboard (surfacing power telemetry, dynamic health constraints, and cached drift warnings). It correlates repository state against transient event logs, and relies on `ops.py` to evaluate topological drift across distributed sessions and scan for host-environment pipeline blockers (e.g., strict git hooks, missing `systemd` linger).
 
 ---
 
@@ -46,4 +46,4 @@ The `src/` directory contains the package source code. The architecture strictly
 2. **Zero-Destruction:** The `prune` logic in `ops.py` relies on strictly namespaced refspecs (`refs/heads/wip/pulsar/...`) and never touches standard heads.
 3. **Identity Stability:** The `system` module guarantees that a Machine ID persists across reboots, preventing "Split Brain" backup histories.
 4. **Configuration Precedence:** Local project configuration MUST always override global user settings to ensure repo-specific constraints (e.g., large file limits) are respected.
-5. **State Over Events:** The diagnostic engine (`cli.py`) MUST prioritize current repository and environmental state over historical log events to prevent alert fatigue from self-healing anomalies.
+5. **State Over Events (Zero-Latency):** The diagnostic engine (`cli.py`) MUST prioritize current repository state and local caches (e.g., `.git/pulsar_drift_state`) over historical log events or live network calls, ensuring the CLI never blocks the user's terminal while evaluating system health.
diff --git a/src/git_pulsar/cli.py b/src/git_pulsar/cli.py
@@ -89,11 +89,12 @@ def _analyze_logs(seconds: int = 86400) -> list[str]:
     return errors
 
 
-def _check_repo_health(path: Path) -> str | None:
+def _check_repo_health(path: Path, config: Config) -> str | None:
     """Evaluates the health of a repository, checking for stale backups or stalled states.
 
     Args:
         path (Path): The file system path to the repository.
+        config (Config): The configuration instance for the repository.
 
     Returns:
         str | None: A warning message if an issue is detected,
@@ -119,11 +120,12 @@ def _check_repo_health(path: Path) -> str | None:
             logger.debug(f"Failed to retrieve backup timestamp for {path.name}: {e}")
             return f"Has changes, but NO backup found. (Error: {e})"
 
-        # Check against the stale threshold (e.g., 2 hours).
+        # Check against the dynamic stale threshold (2x commit interval).
         # If changes are pending and no backup has occurred recently,
         # the daemon may be stalled.
-        if time.time() - last_backup_ts > 7200:
-            return "Stalled: Changes pending > 2 hours."
+        stale_threshold = config.daemon.commit_interval * 2
+        if time.time() - last_backup_ts > stale_threshold:
+            return f"Stalled: Changes pending > {stale_threshold // 60} mins."
 
     except Exception as e:
         return f"Unable to verify git status: {e}"
@@ -189,7 +191,26 @@ def show_status() -> None:
 
     system_content = Text()
     system_content.append("Daemon: ", style="bold")
-    system_content.append(status_text, style=status_style)
+    system_content.append(status_text + "\n", style=status_style)
+
+    # --- Power Telemetry Integration ---
+    conf = Config.load()
+    sys_strat = system.get_system()
+    pct, plugged = sys_strat.get_battery()
+
+    system_content.append("Power:  ", style="bold")
+    if plugged:
+        system_content.append("AC (Unrestricted)", style="green")
+    elif pct < conf.daemon.min_battery_percent:
+        system_content.append(
+            f"Critical {pct}% (All Backups Suspended)", style="bold red"
+        )
+    elif pct < conf.daemon.eco_mode_percent:
+        system_content.append(
+            f"Eco-Mode {pct}% (Pushes Suspended)", style="bold yellow"
+        )
+    else:
+        system_content.append(f"Battery {pct}% (Normal)", style="green")
 
     console.print(Panel(system_content, title="System Status", expand=False))
 
@@ -254,8 +275,46 @@ def show_status() -> None:
         else:
             repo_content.append("Mode:        Active", style="green")
 
+        # --- 1. Health Integration ---
+        health_warning = None
+        if ops.has_large_files(cwd, conf):
+            limit_mb = int(conf.limits.large_file_threshold / (1024 * 1024))
+            health_warning = (
+                f"Daemon stalled.\n  File >{limit_mb}MB detected. "
+                "Run 'git pulsar doctor' for details."
+            )
+        else:
+            health_warning = _check_repo_health(cwd, conf)
+
+        if health_warning:
+            repo_content.append("\n\n⚠ WARNING: ", style="bold yellow")
+            repo_content.append(health_warning, style="yellow")
+
         console.print(Panel(repo_content, title="Repository Status", expand=False))
 
+        # --- 2. Roaming Radar Integration (Cached) ---
+        _, warned_ts = ops.get_drift_state(cwd)
+
+        # Ensure we only warn if the cached remote timestamp is strictly newer
+        # than our local backup reference.
+        if warned_ts > 0 and commit_str != "Never" and warned_ts > int(commit_ts):
+            minutes_ago = int((time.time() - warned_ts) / 60)
+            drift_content = Text()
+            drift_content.append(
+                "⚠ A remote machine pushed a newer session\n", style="bold yellow"
+            )
+            drift_content.append(
+                f"  ~{minutes_ago} mins ago. Run 'git pulsar sync'", style="yellow"
+            )
+            console.print(
+                Panel(
+                    drift_content,
+                    title="Session Drift",
+                    border_style="yellow",
+                    expand=False,
+                )
+            )
+
     # Display global repository count if not currently in a repository.
     elif REGISTRY_FILE.exists():
         count = len(system.get_registered_repos())
@@ -508,7 +567,8 @@ def run_doctor() -> None:
             issues = []
             for p in paths:
                 if p.exists():
-                    if problem := _check_repo_health(p):
+                    repo_config = Config.load(p)
+                    if problem := _check_repo_health(p, repo_config):
                         issues.append(f"{p.name}: {problem}")
 
                     for hook_warning in _check_git_hooks(p):
diff --git a/src/git_pulsar/daemon.py b/src/git_pulsar/daemon.py
@@ -189,46 +189,6 @@ def is_repo_busy(repo_path: Path, interactive: bool = False) -> bool:
     return False
 
 
-def has_large_files(repo_path: Path, config: Config) -> bool:
-    """Scans untracked or modified files for sizes exceeding the limit.
-
-    Args:
-        repo_path (Path): The path to the repository.
-        config (Config): The configuration instance for this repository.
-
-    Returns:
-        bool: True if a large file is found, False otherwise.
-    """
-    limit = config.limits.large_file_threshold
-
-    # Only scan files git knows about or sees as untracked.
-    try:
-        cmd = ["git", "ls-files", "--others", "--modified", "--exclude-standard"]
-        candidates = subprocess.check_output(cmd, cwd=repo_path, text=True).splitlines()
-    except subprocess.CalledProcessError as e:
-        logger.warning(f"Large file scan failed for {repo_path.name}: {e}")
-        return False
-
-    for name in candidates:
-        file_path = repo_path / name
-        try:
-            if file_path.stat().st_size > limit:
-                # Dynamic size formatting (Bytes -> MB)
-                limit_mb = int(limit / (1024 * 1024))
-
-                logger.warning(
-                    f"WARNING {repo_path.name}: Large file detected ({name}). "
-                    "Backup aborted."
-                )
-                SYSTEM.notify("Backup Aborted", f"File >{limit_mb}MB detected: {name}")
-                return True
-        except OSError as e:
-            logger.warning(f"Failed to check size of file {name}: {e}")
-            continue
-
-    return False
-
-
 def prune_registry(original_path_str: str) -> None:
     """Removes a missing repository path from the registry file.
 
@@ -386,7 +346,7 @@ def run_backup(original_path_str: str, interactive: bool = False) -> None:
         return
 
     # Pass config to has_large_files (re-added safety check)
-    if has_large_files(repo_path, config):
+    if ops.has_large_files(repo_path, config):
         return
 
     try:
diff --git a/src/git_pulsar/ops.py b/src/git_pulsar/ops.py
@@ -13,6 +13,7 @@
 from rich.panel import Panel
 
 from . import system
+from .config import Config
 from .constants import APP_NAME, BACKUP_NAMESPACE
 from .git_wrapper import GitRepo
 
@@ -598,3 +599,45 @@ def add_ignore(pattern: str) -> None:
     except Exception as e:
         logger.warning(f"Failed to remove tracked files: {e}")
         pass
+
+
+def has_large_files(repo_path: Path, config: Config) -> bool:
+    """Scans untracked or modified files for sizes exceeding the limit.
+
+    Args:
+        repo_path (Path): The path to the repository.
+        config (Config): The configuration instance for this repository.
+
+    Returns:
+        bool: True if a large file is found, False otherwise.
+    """
+    limit = config.limits.large_file_threshold
+
+    # Only scan files git knows about or sees as untracked.
+    try:
+        cmd = ["git", "ls-files", "--others", "--modified", "--exclude-standard"]
+        candidates = subprocess.check_output(cmd, cwd=repo_path, text=True).splitlines()
+    except subprocess.CalledProcessError as e:
+        logger.warning(f"Large file scan failed for {repo_path.name}: {e}")
+        return False
+
+    for name in candidates:
+        file_path = repo_path / name
+        try:
+            if file_path.stat().st_size > limit:
+                # Dynamic size formatting (Bytes -> MB)
+                limit_mb = int(limit / (1024 * 1024))
+
+                logger.warning(
+                    f"WARNING {repo_path.name}: Large file detected ({name}). "
+                    "Backup aborted."
+                )
+                system.get_system().notify(
+                    "Backup Aborted", f"File >{limit_mb}MB detected: {name}"
+                )
+                return True
+        except OSError as e:
+            logger.warning(f"Failed to check size of file {name}: {e}")
+            continue
+
+    return False
diff --git a/tests/README.md b/tests/README.md
@@ -34,6 +34,7 @@ Verifies the "State Reconciliation" engine and primitive operations.
 - **Octopus Merges:** Simulates complex multi-head merge scenarios (e.g., merging 3 different machine streams into `main`) to ensure the DAG (Directed Acyclic Graph) is constructed correctly without conflicts.
 - **State Management:** Verifies atomic file I/O operations (`set_drift_state`) to ensure cross-process thread safety between the background daemon and foreground CLI.
 - **Drift Detection:** Tests the core logic for identifying when remote sessions leapfrog local ones, simulating various network failures and detached HEAD states.
+- **Pipeline Blockers:** Validates decoupled checks for oversized files (`has_large_files`), ensuring they safely abort operations and trigger system notifications without polluting the daemon's event loop.
 
 ### 5. Configuration Hierarchy (`test_config.py`)
 
@@ -46,6 +47,7 @@ Ensures the **Cascading Configuration** system behaves deterministically.
 
 Validates the state-aware diagnostic engine and user-facing CLI commands.
 
+- **Dashboard Observability:** Validates the `status` command's rendering of power telemetry (Eco-Mode vs. Critical), dynamic health thresholds, and zero-latency caching for drift/blocker warnings.
 - **State vs. Event Correlation:** Tests the `doctor` command by decoupling repository health (state) from daemon logs (events). We mock dynamic lookback windows to verify that naturally resolved transient anomalies are suppressed, while active correlated failures trigger alerts.
 - **Environment Simulation:** Uses `tmp_path` and `mocker` to synthesize restrictive `.git/hooks`, offline networks, and Linux `systemd` configurations (`loginctl`) without executing side effects on the host.
 - **UI Determinism:** Ensures commands like `status` and `config` parse timestamps and route to standard system editors (`$EDITOR`, `nano`) correctly.
diff --git a/tests/test_cli.py b/tests/test_cli.py
diff --git a/tests/test_daemon.py b/tests/test_daemon.py
diff --git a/tests/test_ops.py b/tests/test_ops.py
