Skip to content

feat(ui): read host metrics from released CLIs through the machine shell (OH-59) - #33

Merged
andorcassian merged 2 commits into
devfrom
feature/OH-59-shell-metrics-fallback
Nov 8, 2026
Merged

andorcassian merged 2 commits into
devfrom
feature/OH-59-shell-metrics-fallback

Conversation

@andorcassian

@andorcassian andorcassian commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

What changes

Every machine in the sidebar showed "This machine CLI does not support host metrics". The daily daemons run released CLIs (0.2.12–0.2.17), which have no tool.machineMetrics capability. Every released CLI from 0.2.12 through 0.2.20 does register the machine bash RPC, so the app can now read those hosts without a new daemon.

  • Released-CLI fallback (sync/ops/machineMetricsShell.ts): when the capability is unsupported, loadMachineMetrics runs one fixed, read-only, argv-only command for the host's platform through machineBash, using the shared 30 s capability budget. The commands are top/vm_stat/sysctl/df/ioreg on macOS, /proc/df/nvidia-smi/AMD gpu_busy_percent on Linux, and PowerShell CIM queries on Windows. Nothing is interpolated into the commands. The capability is still preferred when present.
  • One definition of each measurement: capacityUsage and the NVIDIA, Windows and Mac GPU parsers move from the CLI collector into @happier-dev/protocol, and both paths use them. Memory follows os.freemem(): free pages on macOS, MemAvailable (or MemFree on kernels without it) on Linux, available memory on Windows.
  • Cached readings: the last good reading per Home/account/machine persists for a week through the existing persistent cache, with every saved reading validated against the snapshot schema. After a restart, or while a host is offline or unreadable, the row shows it as "Previous reading · stale".
  • Compact line: when a reading exists, its values come first, so a narrow sidebar truncates the state rather than the numbers. Expanded details say when a reading came from system tools (copy in all 12 locales).
  • Read race fixed: a host's platform can load after its first read starts. The store used to fold the platform-bearing refresh into the read that started without it, which left released hosts "unsupported" until the next 3-minute tick. It now re-reads once the platform arrives, and only if that read came back unsupported, so a metrics-capable host is still read once.
  • Failure handling: only a daemon without the shell handler is "unsupported". A timeout, dropped connection, failed spawn or unreadable output is a read error that retries on the next refresh, instead of telling the user to install another CLI.
  • Same measurements as the CLI: storage on macOS uses df's Available column, because on APFS the Used column counts only the Data volume. That matches the CLI's statfs reading (95.8% measured on this Mac, against 93.6% from Used). Windows measures the drive holding the user profile. The CPU-sample, load-average and percentage calculations are shared from protocol along with the parsers.
  • Docs: the app Machine monitoring section, docs/fork-development.md and docs/fork-production.md.

Validation

  • RED → GREEN: fallback parsing and failure handling on real captures (machineMetrics.test.ts, 10 tests), the store's platform, source, persistence and race handling (machineMetricsStore.test.ts, 7), and the values-first compact line (MachineMonitoringSection.test.tsx, 4). The race was reproduced in the browser before its RED test.
  • Fixtures are real output of the exact scripts from an Apple M4 Pro Mac, a Windows 11 host, and WSL Ubuntu on that host, which lacks MemAvailable. One constructed Linux fixture covers the AMD/NVIDIA formats and is labelled as constructed.
  • Windows: the daemon's exact child_process.spawn(powershell.exe … -Command <script>, { shell: false }) ran on the Windows host: exit 0 in 2.9 s with every field present.
  • Chrome, machines.monitoring.oh59.spec.ts (whole file): 4/4 pass. The new test serves a released-CLI host's bash from this Mac's real commands, checks the live reading and the system-tools note, then disconnects the host and reloads to check that the saved reading shows first. With the fallback forced off, it fails with the original "does not support host metrics" text.
  • Owner tests after the review fixes: metrics op/store/section/hook, machineBash callers and locale tests (71 passed); CLI collector (1, after the CPU tests moved); protocol interpreters plus import-cycle and export guards (37). Typechecks pass for UI, CLI, protocol and tests. Docs: content checks and 47 guards pass.
  • Not run: full suites (CI owns them) and native macOS/iOS app QA.

Independent review

A separate reviewer reported one major and four minor findings, and all five were confirmed against source and measurements:

  • the macOS storage definition;
  • transient shell failures shown as unsupported;
  • the unsupported message flashing during the platform re-read;
  • the Windows drive in domain setups;
  • calculations duplicated between the CLI and the UI.

Each behavior fix has a RED test, except the Windows drive change. That one is script-only and was checked through the daemon's exact spawn on the Windows host (drive C:, exit 0). The duplication fix is a refactor, covered by the moved tests. No security finding held up: the argv is a fixed constant chosen by a three-way platform switch.

Scope and deferrals

  • Native QA stays deferred. The fallback has not yet been seen against the hosted relay and the real daily daemons. That needs this build installed, which reaches production through the nightly promotion after merge.
  • The 0.3 port disposition is blocked because the destination checkout is absent.
  • Remove the fallback once every supported host runs a metrics-capable CLI.

Tracks OH-59.

…ell (OH-59)

Released CLIs (0.2.12 to 0.2.20) have no host-metrics capability, so every
installed daemon showed "This machine CLI does not support host metrics". They
all register the machine bash RPC, so when the capability is unsupported the UI
now runs one fixed, read-only, argv-only command per platform (macOS, Linux,
Windows) and interprets it with the same helpers as the CLI collector, now in
@happier-dev/protocol. The capability stays preferred where present.

The last good reading per Home/account/machine persists for a week, so rows show
it marked stale after a restart or while a host is offline or unreadable, with
the values first on the compact line.

A host's platform can arrive after its first read starts; the store now re-reads
once it arrives instead of sharing the read that started without it, and only
when that read came back unsupported.
… retryable (OH-59)

Review fixes for the released-CLI host metrics fallback:

- macOS storage free space is df's Available column. On APFS, df's Used counts only
  the Data volume, so total minus Used understated use by about 2 points here
  (93.6% vs the CLI's statfs 95.8%). Linux keeps total minus Used, which GNU df
  defines as total minus free blocks.
- Only a daemon without the shell handler (method not found or not available,
  thrown or as a result payload) is unsupported. Timeouts, dropped connections,
  failed spawns and unreadable output are read errors the next refresh retries,
  so the row no longer tells the user to install another CLI for a hiccup.
- A read that missed the host's platform and came back unsupported re-reads
  with it instead of publishing that answer, so the row never flashes the
  unsupported message during the re-read.
- Windows measures the drive holding the user profile, like the CLI collector,
  rather than HOMEDRIVE, which can name a network home folder in a domain.
- The CPU sample, load average and utilization percentage definitions move into
  @happier-dev/protocol with the other shared interpreters; the CLI collector and
  the fallback both use them.
@andorcassian
andorcassian marked this pull request as ready for review November 8, 2026 23:33
@andorcassian
andorcassian merged commit be5fd38 into dev Nov 8, 2026
45 checks passed
@andorcassian
andorcassian deleted the feature/OH-59-shell-metrics-fallback branch November 8, 2026 23:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant