Merge main into storage and retain release notes

2026-10-24 17:01:40 +02:00 · 2026-10-24 03:08:15 +00:00
commit bb9236b2b7
@@ -7,3 +7,16 @@
  and permission/missing-drive states. Includes instructions for Steam's own
  Move UI; Frame Control does not move or delete game files. The read-only parser was
  checked on a real Frame; the connected UI and game moves were not.
+
+- Add `scripts/frame-doctor.sh` for read-only setup and pairing diagnostics,
+  with verified SSH identity, private summaries and actionable next steps
+  (issue #34). Connection steps links to the diagnostic guide. Repairs remain
+  manual; restart-loop evidence stops deeper diagnostics. The real Frame
+  verified the SSH connection and safety stop; deeper checks were skipped.
+- Fixed headset smoke cleanup reporting success while a smoke-title process
+  could remain running after its files were removed. Cleanup now stops and
+  rechecks processes tied to exact reserved test-title paths, uses PID handles
+  for safe TERM/KILL escalation, and records stopped PIDs. Unrelated titles and
+  shared Wine services are left alone. Verified with local Linux process
+  regressions and a 13/13 real Frame smoke run that stopped five test-owned
+  Proton process PIDs before removing the Windows test title.
@@ -14,6 +14,13 @@ reported Game Mode, so **Return to Game Mode** changed nothing. Not tested on a
 headset: a restore after a real factory reset, a restore that replaces files,
 Android data restore, and the switch out of a real Desktop Mode session. Unit
 tests and the fake Frame cover those (see [Verification](#verification)).
+On 2026-10-24 a read-only session check on the same build again reported Game
+Mode (`gamescope=true`, `plasma=false`, `nested_desktop=false`) and the
+`steamos-session-select` command was present. Opening the nested desktop for a
+clipboard test did not enter full Desktop Mode. A full session switch was not
+attempted because it restarts the headset session and a reliable return path
+was not established; the **Return to Game Mode** branch for a real full
+Desktop Mode session remains unverified.

 ## Back up

@@ -0,0 +1,59 @@
+# Battery and health monitoring
+
+Open **Control Center → Battery & thermal health**, or expand **System
+information**, to read the Frame's charge, charging state, signed battery
+power, battery temperature and driver-reported health. Optional readings show
+charge cycles, full charge capacity, design capacity and full / design capacity.
+The existing battery chip also shows charging state and temperature.
+
+These are read-only readings from the Linux host's `/sys/class/power_supply`,
+not Android's container battery view. The probe prefers the documented Frame
+fuel gauge, `max1720x_bat_7-36`, over other battery nodes, excludes peripheral
+(`scope=Device`) and absent batteries, and otherwise uses a deterministic
+battery fallback. The UI shows the selected source path.
+
+| Reading | Linux attribute | Interpretation |
+|---|---|---|
+| Charge | `capacity` | Integer 0–100 percent; zero is a real reading |
+| Charging state | `status` | Charging, Full, Discharging or Not charging; missing/unknown states stay unavailable |
+| Battery power | `voltage_now × current_now` | Microvolts and microamps converted to signed watts; positive means charging on the Frame |
+| Temperature | `temp` | Tenths of a degree Celsius, including valid negative readings |
+| Battery health | `health` | Driver status such as Good or Overheat; not a wear percentage |
+| Charge cycles | `cycle_count` | Driver-reported count, including zero |
+| Full/design capacity | `charge_full`, `charge_full_design` | Microamp-hours converted to mAh |
+| Full / design capacity | Ratio of those two capacities | Fuel-gauge estimate; not a diagnosis or a guaranteed runtime |
+| Time estimate | `time_to_full_now`, `time_to_empty_now` | Seconds; displayed only for the corresponding charging/discharging state |
+
+Unavailable means the field is absent, unreadable or invalid. One missing
+sensor does not hide the others. Zero design capacity cannot produce a ratio. Time estimates outside 1 second
+to 7 days and battery temperatures outside −273.15 to 200 °C are rejected
+as invalid readings; these bounds are not thermal warning thresholds.
+The ratio may exceed 100% because full capacity is a gauge estimate, so the app
+does not clamp it or invent a wear warning. The app does not estimate health
+from charge percentage or assign temperature thresholds. Existing thermal
+alerts use the kernel's own hot/critical trip points.
+
+A connected charger does not necessarily mean charging: the Frame can still
+drain under load or sit idle near full charge. A 100% capacity reading alone
+does not prove the driver reports Full. Missing status is explicitly unknown;
+near-zero measured battery power with a charger is shown as not charging.
+Failed, stale or disconnected status samples clear Control Center readings.
+
+**No charge controls are provided.** Frame's SteamOS charge-limit backend is
+unsupported; see [charge-limit research](charge-limit.md). Monitoring never
+writes to power supplies, pauses charging, changes current or sets a limit.
+
+## Verification
+
+`tests/test_battery.py` uses temporary sysfs-like files for conversion,
+malformed/missing values, permission failures, source selection and partial
+sensor support. `tests/control_center.cjs` exercises charging states, optional
+metrics and failed/stale/disconnected sample handling. These tests do not
+connect to a headset. On 2026-10-24, the PR's uninstalled parser was also
+piped over SSH to a real Frame running SteamOS 0.5.6 (build
+`20261015.6141207`). Its read-only sysfs result selected
+`max1720x_bat_7-36` and reported 99% charge, Not charging, 24.9 °C,
+Good driver health, 14 cycles, 2,920 mAh full and 2,700 mAh design capacity
+(108.1% fuel-gauge estimate). The Control Center UI was not run against this
+headset; Windows and macOS were not tested. Optional fields are not claimed to
+be available on every firmware build.
@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- Battery monitoring now selects the Frame fuel gauge predictably, handles
+  missing or invalid readings, and shows optional cycle count, full/design
+  capacity and estimated capacity health in Control Center. Unknown charging
+  status stays explicit. Monitoring is read-only; charge limits remain
+  unsupported on Frame. The read-only parser was checked on a real Frame; the UI was not.
@@ -18,6 +18,9 @@ read-only checks below on a Frame running SteamOS 0.5.6 (build 20261015.6141207)
  `charging_enable` and `charging_pause`, both `root`-only (`-rw-r--r--`).
 - `deckard-charger.service` (Deckard Battery Charger service) is enabled and running.

+For safe read-only readings in Control Center, see [battery and health
+monitoring](battery-health.md). It does not provide charging controls.
+
 ## How Steam does it on other devices

 - Steam's **Settings → Power → Battery Charge Limit** shipped to the Deck in
@@ -62,6 +62,12 @@ refused with a message, so send big things as a file. An empty clipboard, or
 one holding an image, says so. Neither the server nor its log ever records what
 was on the clipboard.

-**Not tested on a headset yet.** Reading uses the same Klipper interface as
-sending, which was verified on 2026-09-25, but `getClipboardContents` itself
-hasn't been tried on a Frame. The fake Frame (`tests/fakeframe`) answers it.
+**Verified on a Frame, 2026-10-24:** SteamOS 0.5.6, build
+`20261015.6141207`. With a temporary nested desktop open, Frame Control sent
+a 47-character test marker to Klipper, then **Copy the headset's clipboard**
+read it through `getClipboardContents` and set a Linux PC's X11 clipboard.
+Reading that PC clipboard returned the exact marker. The prior headset
+clipboard was restored and the test desktop was closed. The PC side used a
+temporary X display on lxso2; macOS and Windows clipboard backends, a user's
+copy action in a headset app, and image/size error cases remain untested on a
+real headset. The fake Frame (`tests/fakeframe`) covers the protocol cases.
@@ -0,0 +1,121 @@
+# Frame doctor
+
+Run `scripts/frame-doctor.sh` from a checkout on macOS or Linux to diagnose
+first-time setup, pairing and common Frame failures without applying repairs.
+It needs Bash, Python 3 and OpenSSH on the computer, and Python 3 on the Frame.
+Windows users can run `python scripts/frame_doctor.py` with Python and OpenSSH
+installed; the desktop app does not bundle this command.
+
+```sh
+scripts/frame-doctor.sh
+scripts/frame-doctor.sh --alias bedroom --lan frame.local
+scripts/frame-doctor.sh --alias frame --lan 192.168.1.40
+```
+
+Use only addresses belonging to your intended headset. The command tries the
+existing `frame` SSH alias first (Tailscale if setup configured it that way),
+then `frame.local`, then USB-C at `10.86.200.233`. `--alias`, `--lan` and `--usb`
+override those defaults. It reports the successful path without printing its
+address. It neither discovers other devices nor enables Tailscale.
+
+The existing alias supplies the user, port, keys and known-hosts file. LAN and
+USB overrides preserve its `HostKeyAlias`, or its configured hostname if no
+alias was set. A first connection therefore needs trusted setup first. The
+doctor never accepts a new host key, deletes a saved key, generates keys or
+sends a pairing request. It uses your trusted OpenSSH configuration; OpenSSH
+can evaluate `Match exec` conditions in that configuration. Proxy commands,
+jumps, local commands, forwarding and connection sharing are disabled for
+these direct diagnostic connections.
+
+## Reading the result
+
+Each of the eleven runbook sections has one line: `OK`, `WARN`, `BROKEN` or
+`UNKNOWN`. `OK` means only that the stated check passed, not that the whole
+feature works. Optional features that are off may produce a warning.
+
+| Section | Read-only evidence and limits |
+|---|---|
+| 1. Boot and crash history | Previous-boot kernel-oops signatures; one day of coredump history. An oops alone does not prove an unclean reset. |
+| 2. Wi-Fi | NetworkManager's wlan0 state, without SSIDs or connection profiles. |
+| 3. Displays and SteamVR | DSI timeout signatures in the recent kernel journal; no display, compositor or game is launched. |
+| 4. Steam and storage | Free space in home and `devkit-game`, including separate mounts; missing Steam install marker. No CRC scan or restart. |
+| 5. Idle sleep and keep-awake | Existing keep-awake unit state; never takes ownership or changes idle timers. |
+| 6. Remote wake | WoWLAN state, without arming it or testing suspend. Wake with the power button. |
+| 7. Lepton | Recent port-clash, binder and data-clearing signatures; no Android/container commands. |
+| 8. Chromium XR | Crash history; no browser profile or environment inspection. |
+| 9. KDE Connect | Process presence; absence is normal when sharing is off. |
+| 10. Streaming and capture | ffmpeg crash history; no capture or encoder is started. |
+| 11. Panels | Always `UNKNOWN`: placement requires the user's visual confirmation. |
+
+Journal samples are capped at 2,000 entries; current-boot samples cover the
+last ten minutes. This can miss older or high-volume failures. Empty,
+inaccessible or permission-limited journals are `UNKNOWN`, never zero errors.
+Commands time out individually, and each SSH probe is bounded to 90 seconds.
+
+Exit codes: **0** if all reported checks are OK; **1** for warnings, broken or
+unknown checks after connecting; **2** if no authenticated SSH path exists or
+local SSH setup is unavailable. Panel verification currently means a connected
+run normally exits 1. Automation should read the labelled checks rather than
+treating a warning as proof the headset is unusable.
+
+## First-time setup and pairing
+
+- **No SSH response:** wake the headset with its power button. Check the cable
+  or Steam Settings → Internet, then enable Developer Mode. Sleep and network
+  failure can look alike; a timeout cannot distinguish them.
+- **Key rejected:** open **Set Up Connection** in Frame Control. In the headset,
+  open Steam Settings → Developer → **Pair new host**, then approve setup's
+  request. The doctor only checks whether devkit port 32000 responds; that
+  does not prove pairing mode is open or the service is healthy.
+- **Unknown or changed identity:** verify the intended headset through setup
+  or Devices → **Check its key**. Do not delete `known_hosts` to bypass this.
+- **No devkit response:** check Developer Mode and the address. See
+  [SSH setup](ssh.md) for the manual fallback. The doctor cannot turn SSH on.
+
+No password is requested. Enter any password required by the separate setup
+flow only in its local terminal; never paste it into an issue or report.
+
+## Restart safety and recovery
+
+Before deeper checks, and again afterwards, the doctor samples Steam and
+SteamVR `NRestarts` and health-check tracker sizes two seconds apart. Rising
+counters stop diagnostics immediately. Nonempty health-check trackers also stop
+deeper checks even when stable, since a short sample could miss a slower loop.
+Missing counters or counters that reset stop deeper checks as `UNKNOWN`. Stable
+counters with empty trackers still cannot rule out a slower restart loop.
+
+The [historical runbook from PR #33](https://github.com/saphid/frame-control/blob/cce3d940302054ab5246c92d740afaefc4e58d38/docs/frame-doctor.md)
+is the source for these section numbers and observed signatures (September
+2026 builds). Its section 4 describes freezing and verifying health-check
+trackers before prolonged recovery during a live loop. That changes headset
+state, so this read-only implementation stops and directs you there instead.
+It does not implement issue #34's automatic fixes, before/after repair runs,
+or full recovery automation. Review build-specific recovery instructions with
+the person using the headset; a repair can remove data.
+
+Never reload `ath12k`, suspend remotely, kill gamescope to diagnose a loop,
+reset or force power off during extraction/repair, or write passwords to disk.
+The doctor never restarts services, signals processes, repairs Steam, changes
+WoWLAN/standby settings, takes keep-awake ownership, installs anything or writes
+a report. Nothing needs restoring after its checks. Manual/device tests must
+follow the [shared-device lock and battery procedure](testing.md#headset-smoke-test).
+
+## Privacy and verification
+
+Only fixed diagnostic summaries leave the remote probe. Raw journals, process
+arguments, environment variables, SSH errors, account IDs, network addresses,
+SSIDs, keys and tokens are not printed. No telemetry or HTTP request is sent;
+the only pairing-service probe is a TCP connection. SSH produces normal access
+logs. Review summaries before sharing them; feature availability can still be
+personal information. Redirecting stdout saves a report only if you choose it.
+
+Unit tests use mocked boundaries. `scripts/e2e.sh test_doctor` covers asleep,
+disk-full, SSH/devkit-off and missing-key faults against the fake Frame. Its
+stable restart counters are explicitly simulated, not proof about SteamOS.
+On 2026-10-24 the script ran read-only against a real Frame, SteamOS build
+`20261015.6141207`. It verified the configured SSH alias and key login,
+then reported `WARN Restart safety`: nonempty health-check trackers. It
+correctly skipped all eleven deeper sections and exited 1. No raw logs,
+addresses or keys were printed, and no repair or restart was attempted.
+This verifies the safety stop on that device; the deeper checks are not
+claimed as headset-tested.
@@ -149,11 +149,12 @@ recording with Steam's file names and export it with the real `ffmpeg`.

 ## What hasn't been checked

-None of this has run on a Steam Frame yet. In particular:
+The 2026-10-24 read-only clip list on build `20261015.6141207` again returned
+zero clips: its `gamerecordings` directory held only `gamerecording.pb`. No
+Steam recording was created during that check, so a real Steam clip export is
+still unverified. The recording and Stop path were verified earlier on that
+build, as described above. Remaining checks:

- That SteamOS's `ffmpeg` can read `@DEFAULT_MONITOR@`. It has the PulseAudio
-  output device (the media player plays through it), so the input is expected,
-  but if it fails the recording is video only, as above.
 - Audio and video sync. Both inputs are stamped with the wall clock, because
  the camera device and the audio server otherwise count from different clocks.
 - The exact layout of `gamerecordings` on the Frame's SteamOS build, and
@@ -7,6 +7,10 @@ run on Linux. On Windows, use the app.

 ## Minimum typing on the headset

+If setup or pairing fails, run `scripts/frame-doctor.sh` from this checkout.
+It checks existing SSH access without requesting passwords, pairing or applying
+repairs. See the [Frame doctor guide](frame-doctor.md) for results and next steps.
+
 Valve's own developer docs say SSH, ADB, and RDP are all turned on through a
 **UI toggle**. You don't need a terminal, `passwd`, or `systemctl`. The only
 thing you type on the headset is a password you choose.
@@ -44,6 +44,20 @@ them on macOS, Windows and Linux. They don't pick up `tests/e2e`.

 ## The fake Frame

+Frame doctor has focused offline tests in `tests/test_frame_doctor.py` and
+fake-Frame fault tests in `tests/e2e/test_doctor.py`:
+
+```sh
+python3 -m unittest discover -s tests -p test_frame_doctor.py -v
+scripts/e2e.sh test_doctor
+```
+
+They cover privacy filtering, host-key preservation, restart safety and missing
+journal evidence, plus asleep, full-title-storage, SSH/devkit-off and missing-key
+faults. The fake's doctor-only `systemctl show` responses assume stable restart
+counters and inactive keep-awake; unsupported queries fail. These tests do not
+exercise a real SteamOS user manager or touch a headset.
+
 `tests/fakeframe/` builds a container that stands in for the headset, and a
 second one for the computer Frame Control runs on. `scripts/e2e.sh` builds
 both, starts them with `docker compose`, runs `tests/e2e` in the host
@@ -164,6 +178,43 @@ does). A cleanup that fails counts as a failed step. Results go to
 screen; it exits 0 when every step passed, 1 if one failed, 2 if the headset
 isn't reachable.

+Smoke process cleanup runs before and after title removal and during the
+initial/final leftover sweeps. It targets only the reserved `fc_smoke_arm64`,
+`fc_smoke_x86_64`, `fc_smoke_exe` IDs and their legacy `fc-smoke-` equivalents.
+On the target, `tests/smoke/stop_processes.py` requires the SSH user's uid and
+an exact title directory in `/proc` cwd/exe or an individual absolute command
+argument; similarly named folders and shell command substrings do not count.
+Deleted cwd/exe paths still count, so a process left after file removal can be
+found. It sends SIGTERM, waits up to three seconds, then uses SIGKILL with
+another three-second bound, rescanning for survivors. PID handles prevent PID
+reuse from signalling another process. Linux Python 3.9+ with pidfd support
+is required; missing support, signal errors and survivors fail the
+cleanup step. Stopped PIDs are recorded in the results JSON.
+If the initial leftover cleanup fails, the run skips installs and pairing and
+records the failure instead of overwriting an active test title.
+
+This deliberately does not stop shared Wine/Proton services by name or prefix,
+Steam, SteamVR, process groups or arbitrary descendants. A process that drops
+all title-path evidence cannot safely be attributed and is outside this
+check. Unreadable `/proc` fields provide no ownership evidence; other readable
+fields are still checked, and a wholly unattributable process is left alone.
+Real Frame verification, 2026-10-24, SteamOS build `20261015.6141207`: the
+fixed Python smoke entry point passed all 13 steps under the shared device lock.
+The `fc_smoke_exe` launch ran under Proton Experimental (ARM64), and its
+remove step stopped five test-owned wrapper/Proton PIDs before removing the
+title; the following process sweep found none. The final cleanup found no
+test titles or processes, the test desktop was closed, and the battery
+remained at 99%. The `scripts/frame-smoke.sh` zsh wrapper could not run
+on lxso2 because zsh is absent; `python3 tests/smoke/frame_smoke.py` ran
+the same entry point instead.
+The local regression suite runs real Linux processes in temporary fake title
+directories (including deleted folders and a TERM-resistant wrapper); it checks
+exit, escalation and survival of unrelated processes without SSH or a headset:
+
+```sh
+python3 -m unittest discover -s tests -p test_smoke_cleanup.py -v
+```
+
 `--pair` asks the devkit service to pair a new RSA key, which needs someone
 in the headset to open **Settings → Developer → Pair new host** and approve
 it; the key is checked and then taken out of `authorized_keys` again.
@@ -365,3 +416,11 @@ read-only metadata probe, guarded HTTP endpoint and Node renderer/navigation
 regressions. All headset reads are temporary fixtures or mocked SSH. See
 [game storage](game-storage.md#verification-and-limits) for coverage and device
 verification limits. This suite does not move games or contact a headset.
+
+## Battery monitoring
+
+`tests/test_battery.py` covers real file parsing with temporary sysfs-like
+files, source preference, missing/invalid sensors and permission errors.
+`tests/control_center.cjs` covers charging states and optional health fields,
+alongside existing stale/offline handling. No headset is used. See
+[battery monitoring](battery-health.md) for sources, units and limitations.
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Read-only setup and health diagnostics; see docs/frame-doctor.md.
+set -euo pipefail
+root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)
+exec python3 "$root/scripts/frame_doctor.py" "$@"
@@ -0,0 +1,279 @@
+"""Read-only doctor. Also sent over SSH on stdin; never installed on the Frame.
+
+Only fixed summaries leave the probe: no raw journals, addresses, account IDs,
+process arguments, environment, key material or HTTP response bodies.
+"""
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import time
+
+SECTIONS = ('Boot and crash history', 'Wi-Fi', 'Displays and SteamVR',
+            'Steam and storage', 'Idle sleep and keep-awake', 'Remote wake',
+            'Lepton (Android)', 'Chromium XR', 'KDE Connect',
+            'Streaming and capture', 'Panels')
+
+
+def run(args, timeout=4, **kwargs):
+    try:
+        return subprocess.run(args, capture_output=True, text=True, timeout=timeout, **kwargs)
+    except (OSError, UnicodeError, subprocess.TimeoutExpired):
+        return None
+
+
+def command(*args):
+    r = run(list(args))
+    return r.stdout if r is not None and r.returncode == 0 else None
+
+
+def journal(*args):
+    # Even exit 0 can mean the account cannot see the system journal.
+    r = run(['journalctl', '--no-pager', '-q', '-n', '2000', *args])
+    if r is None or r.returncode or r.stderr.strip() or not r.stdout.strip():
+        return None
+    return r.stdout
+
+
+def snapshot():
+    values = []
+    for unit in ('steam', 'steamvr'):
+        s = command('systemctl', '--user', 'show', unit + '.service',
+                    '-p', 'NRestarts', '--value')
+        if s is None or not s.strip().isdigit():
+            return None
+        values.append(int(s.strip()))
+        p = Path('/run/user') / str(os.getuid()) / (unit + '-short-session-tracker')
+        try:
+            values.append(p.stat().st_size)
+        except FileNotFoundError:
+            values.append(0)
+        except OSError:
+            return None
+    return values
+
+
+def guard():
+    first = snapshot()
+    time.sleep(2)
+    second = snapshot()
+    if first is None or second is None:
+        return 'unknown'
+    if any(b > a for a, b in zip(first, second)):
+        return 'loop'
+    if first != second:
+        return 'unknown'  # counters reset or tracker replaced during the sample
+    if second[1] or second[3]:
+        return 'risk'  # avoid a long run even if a short sample missed the loop
+    return 'stable'
+
+
+def signal_check(text, pattern, problem, healthy):
+    if text is None:
+        return ['UNKNOWN', 'Evidence unavailable; consult the runbook locally.']
+    return ['WARN', problem] if re.search(pattern, text, re.I) else ['OK', healthy]
+
+
+def storage():
+    # devkit-game may be a separate mount (including in the fake Frame).
+    try:
+        paths = [Path.home()]
+        games = Path.home() / 'devkit-game'
+        if games.exists():
+            paths.append(games)
+        free = min(shutil.disk_usage(p).free for p in paths)
+        if free < 16 * 1024**2:
+            return ['BROKEN', 'Less than 16 MiB free; review storage in Frame Control before installing.']
+        if free < 256 * 1024**2:
+            return ['WARN', 'Less than 256 MiB free; review storage before large installs.']
+        return ['OK', 'Home and title storage have at least 256 MiB free.']
+    except OSError:
+        return ['UNKNOWN', 'Storage could not be read.']
+
+
+def probe():
+    state = guard()
+    if state != 'stable':
+        return {'guard': state, 'checks': []}
+    kernel = journal('-b', '-k', '--since=-10min')
+    recent = journal('-b', '--since=-10min')
+    previous = journal('-b', '-1', '-k')
+    crashes = command('coredumpctl', 'list', '--no-pager', '--since=-1d')
+    checks = []
+    boot = signal_check(previous, r'Unable to handle kernel|Internal error|Kernel panic',
+                        'Previous boot has a kernel oops; this alone does not prove an unclean reset.',
+                        'No kernel-oops signature in the sampled previous boot.')
+    if crashes is None and boot[0] != 'WARN':
+        boot = ['UNKNOWN', 'Crash history unavailable; inspect boot history locally.']
+    elif crashes is not None and boot[0] != 'WARN' and re.search(r'SIG(SEGV|ABRT)|\b(SEGV|ABRT)\b', crashes):
+        boot = ['WARN', 'Crash records exist in the last day; inspect locally using the runbook.']
+    checks.append(boot)
+    wifi = command('nmcli', '-t', '-f', 'DEVICE,TYPE,STATE', 'device')
+    checks.append(signal_check(wifi if wifi and 'wlan0:wifi:' in wifi else None, r'wlan0:wifi:(unavailable|disconnected|failed)',
+                               'Wi-Fi is unavailable or disconnected; check Steam Settings > Internet. Never reload ath12k.',
+                               'No unavailable/disconnected wlan0 reported; other interfaces may differ.'))
+    checks.append(signal_check(kernel, r'wait for video done',
+                               'Display timeouts observed; follow display recovery before touching Steam.',
+                               'No display-timeout signature in recent kernel sample.'))
+    if checks[-1][0] != 'WARN' and recent is not None and re.search(r'left-over process|steamvr.service: Failed|!modifiers.empty', recent):
+        checks[-1] = ['WARN', 'SteamVR/session failure signature observed; inspect locally before restarting anything.']
+    disk = storage()
+    if disk[0] == 'OK' and not (Path.home() / '.local/share/Steam/.install-complete').exists():
+        disk = ['WARN', 'Steam install marker is missing; do not restart Steam for diagnosis. Consult the runbook.']
+    checks.append(disk)
+    awake = command('systemctl', '--user', 'show', 'fc-keep-awake.service', '-p', 'ActiveState', '--value')
+    checks.append(['UNKNOWN', 'Keep-awake state unavailable.'] if awake is None or not awake.strip() else
+                  ['WARN', 'Keep-awake is active; leave it with its owner.'] if awake.strip() == 'active' else
+                  ['OK', 'Keep-awake is inactive; diagnostics do not inhibit sleep.'])
+    wow = command('iw', 'phy', 'phy0', 'wowlan', 'show')
+    checks.append(['UNKNOWN', 'WoWLAN state unavailable; remote wake is not verified.'] if wow is None else
+                  ['OK', 'WoWLAN is disabled; wake the headset with its power button.'] if 'WoWLAN is disabled' in wow else
+                  ['WARN', 'WoWLAN may be armed; review the runbook. Remote wake is not reliable.'])
+    checks.append(signal_check(recent, r'Listen failed for HOST TCP|binder_user_error|Clearing baked app data',
+                               'Android failure signature observed; inspect Lepton locally before retrying.',
+                               'No known Android failure signature in recent journal sample.'))
+    checks.append(signal_check(crashes, r'chromium|/chrome\b',
+                               'Chromium crash history found; update/relaunch the panel through its normal UI.',
+                               'No Chromium crash signature in available crash history.'))
+    kde = run(['pgrep', '-f', 'frame-control/kdeconnect/root/usr/lib/kdeconnectd'])
+    checks.append(['UNKNOWN', 'KDE Connect process check unavailable.'] if kde is None or kde.returncode not in (0, 1) else
+                  ['OK', 'KDE Connect process found.'] if kde.returncode == 0 else
+                  ['WARN', 'KDE Connect is not running; normal if keyboard/trackpad sharing is off.'])
+    checks.append(signal_check(crashes, r'ffmpeg',
+                               'Capture crash history found; consult software-encoder guidance in the runbook.',
+                               'No ffmpeg crash signature in available crash history.'))
+    checks.append(['UNKNOWN', 'Panel placement needs visual confirmation; open one panel at a time.'])
+    # A short sample is not proof that Steam is healthy. Recheck after collecting.
+    after = guard()
+    return {'guard': after, 'checks': checks if after == 'stable' else []}
+
+
+SSH_OPTIONS = ['BatchMode=yes', 'NumberOfPasswordPrompts=0', 'StrictHostKeyChecking=yes',
+               'UpdateHostKeys=no', 'CheckHostIP=no', 'ConnectTimeout=3', 'ConnectionAttempts=1',
+               'ControlMaster=no', 'ControlPath=none', 'ClearAllForwardings=yes',
+               'PermitLocalCommand=no', 'RemoteCommand=none', 'RequestTTY=no',
+               'ProxyCommand=none', 'ProxyJump=none', 'ForwardAgent=no', 'ForwardX11=no']
+
+
+def ssh_args(alias, host=None, identity=None):
+    args = ['ssh']
+    for opt in SSH_OPTIONS:
+        args += ['-o', opt]
+    if host:
+        args += ['-o', 'HostName=' + host, '-o', 'HostKeyAlias=' + identity]
+    return args + [alias]
+
+
+def failure(text):
+    # Never echo SSH stderr: it can contain addresses, paths or remote text.
+    if 'REMOTE HOST IDENTIFICATION HAS CHANGED' in text:
+        return 'SSH identity changed; use Devices > Check its key after verifying the headset. Do not delete known_hosts.'
+    if 'Host key verification failed' in text:
+        return 'SSH identity is untrusted; verify it through Set Up Connection or Devices > Check its key.'
+    if 'Permission denied' in text:
+        return "SSH key rejected; use Set Up Connection, then Developer > Pair new host in the headset."
+    return 'No SSH response; wake the headset, check the network/cable and enable Developer Mode.'
+
+
+def port_open(host, port):
+    try:
+        with socket.create_connection((host, port), timeout=2):
+            return True
+    except OSError:
+        return False
+
+
+def report(data):
+    state = data.get('guard')
+    if state != 'stable':
+        status = 'BROKEN' if state == 'loop' else 'WARN' if state == 'risk' else 'UNKNOWN'
+        message = {'loop': 'Counters are rising. Stop diagnostics; use the runbook health-check recovery procedure.',
+                   'risk': 'Health-check trackers contain failures. Deeper checks skipped; review the runbook before recovery.'}
+        print(status + ' Restart safety: ' + message.get(state, 'Cannot verify restart counters; deeper checks skipped for safety.'))
+        for i, label in enumerate(SECTIONS, 1):
+            print(f'UNKNOWN {i}. {label}: Skipped until restart safety is verified.')
+        return 1
+    checks = data.get('checks')
+    # Treat the remote endpoint as untrusted. Only accept pairs from our own
+    # fixed vocabulary by matching against the production probe's messages.
+    if not isinstance(checks, list) or len(checks) != len(SECTIONS):
+        print('UNKNOWN Probe: Incomplete diagnostic response; no raw output displayed.')
+        return 1
+    for check in checks:
+        if (not isinstance(check, list) or len(check) != 2 or check[0] not in ('OK', 'WARN', 'BROKEN', 'UNKNOWN')
+                or not isinstance(check[1], str) or check[1] not in MESSAGES):
+            print('UNKNOWN Probe: Unexpected diagnostic response; no raw output displayed.')
+            return 1
+    print('OK Restart safety: No rising counters during short samples; this is not a health guarantee.')
+    for i, (label, (status, message)) in enumerate(zip(SECTIONS, checks), 1):
+        print(f'{status} {i}. {label}: {message}')
+    return int(any(c[0] != 'OK' for c in checks))
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Read-only Frame setup diagnostics. Never pairs, repairs or asks for a password.')
+    parser.add_argument('--alias', default='frame', help='Existing trusted SSH alias (default: frame)')
+    parser.add_argument('--lan', default='frame.local', help='LAN fallback host/IP')
+    parser.add_argument('--usb', default='10.86.200.233', help='USB fallback IP; use only with the intended headset connected')
+    args = parser.parse_args(argv)
+    for value in (args.alias, args.lan, args.usb):
+        if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,252}', value):
+            parser.error('Use a plain alias, hostname or IP address.')
+    print('Frame doctor: read-only; no passwords, pairing, repairs or raw logs. No report is saved.')
+    if not shutil.which('ssh'):
+        print('BROKEN Setup: Install an OpenSSH client, then run Set Up Connection.')
+        return 2
+    config = run(ssh_args(args.alias)[:-1] + ['-G', args.alias])
+    if config is None or config.returncode:
+        print('UNKNOWN Setup: SSH configuration could not be read; check it locally.')
+        return 2
+    settings = dict(line.split(' ', 1) for line in config.stdout.splitlines() if ' ' in line)
+    identity = settings.get('hostkeyalias') or settings.get('hostname', args.alias)
+    source = Path(__file__).read_text()
+    for label, host in (('configured alias (Tailscale if configured)', None), ('LAN', args.lan), ('USB-C', args.usb)):
+        result = run(ssh_args(args.alias, host, identity) + ['python3 -B - --probe'], timeout=90, input=source)
+        if result is not None and result.returncode == 0:
+            try:
+                data = json.loads(result.stdout)
+                if not isinstance(data, dict):
+                    raise ValueError()
+            except ValueError:
+                print('UNKNOWN Probe: Invalid response; check Python 3 availability on the headset. No raw output displayed.')
+                return 1
+            print('OK Connection: ' + label + '; verified SSH identity and key login.')
+            return report(data)
+        if result is not None and result.returncode != 255:
+            print('UNKNOWN Probe: SSH connected but diagnostics failed; check Python 3 on the headset.')
+            return 1
+        reason = failure(result.stderr if result is not None else '')
+        print('WARN Connection (' + label + '): ' + reason)
+    # No /register call: an open devkit port cannot prove pairing mode is enabled.
+    hosts = (settings.get('hostname', args.alias), args.lan, args.usb)
+    if any(port_open(host, 32000) for host in hosts):
+        print('WARN Pairing: Devkit port responds. Use Set Up Connection and Developer > Pair new host; no pairing request was sent.')
+    else:
+        print('UNKNOWN Pairing: Devkit port did not respond. Needs your hands: wake headset, enable Developer Mode and check its address.')
+    for i, label in enumerate(SECTIONS, 1):
+        print(f'UNKNOWN {i}. {label}: No authenticated SSH path.')
+    return 2
+
+
+# Derive the output allowlist from literal strings, not remote data. This module
+# has no dynamic diagnostic messages. AST stays stdlib and runs only locally.
+def messages():
+    import ast
+    tree = ast.parse(Path(__file__).read_text())
+    return {node.value for node in ast.walk(tree) if isinstance(node, ast.Constant) and isinstance(node.value, str)}
+
+
+if __name__ == '__main__':
+    if sys.argv[1:] == ['--probe']:
+        print(json.dumps(probe()))
+    else:
+        MESSAGES = messages()
+        sys.exit(main())
@@ -165,6 +165,50 @@ test('metrics use real fields, preserve zero, and distinguish unavailable values
  assert.equal(cc.metrics({battery:{percent:0,status:'Discharging'}}).battery,'0%');
  assert.match(cc.metrics({thermalAlerts:[{zone:'battery',tempC:45,limitC:44}]}).thermal,/battery 45 °C ≥ 44 °C/);
 });
+test('battery health distinguishes charging states and optional sensors', () => {
+  for (const status of [null, 'Unknown', 'Unexpected']) {
+    const m = cc.metrics({battery:{percent:100,status,timeToEmpty:3600}});
+    assert.equal(m.batteryDetail,'Charging state unavailable');
+    assert.equal(m.estimate,'Unavailable');
+  }
+  assert.equal(cc.metrics({battery:{status:'Not charging'}}).batteryDetail,'Not charging');
+  assert.equal(cc.metrics({battery:{status:'Full'}}).batteryDetail,'Fully charged');
+  assert.equal(cc.metrics({battery:{status:'Charging',timeToFull:3600}}).estimate,'1 h 0 min to full');
+  assert.equal(cc.metrics({battery:{status:'Discharging',timeToEmpty:600}}).estimate,'10 min remaining');
+  const m = cc.metrics({battery:{cycleCount:0,fullMah:4500,designMah:5000,capacityHealthPercent:90,
+    source:'/sys/class/power_supply/max1720x_bat_7-36',health:'Unknown',tempC:0}});
+  assert.equal(m.cycles,'0'); assert.equal(m.capacityHealth,'90%');
+  assert.equal(m.fullCapacity,'4,500 mAh'); assert.equal(m.batteryTemp,'0 °C');
+  assert.equal(m.batteryHealth,'Unavailable'); assert.match(m.batterySource,/max1720x/);
+  for (const key of ['cycles','fullCapacity','designCapacity','capacityHealth','batterySource','batteryHealth','batteryTemp'])
+    assert.equal(cc.metrics(null)[key],'Unavailable');
+});
+test('battery chip preserves unknown status and does not infer Full at 100%', () => {
+  const f=fixture();
+  const start=pageSource.indexOf('function battery(b, power)');
+  const end=pageSource.indexOf('// hidePopover', start);
+  const context={$:f.element,dur:String}; vm.createContext(context);
+  vm.runInContext(pageSource.slice(start,end),context);
+  context.battery({percent:100,status:'Unknown'},{watts:20});
+  assert.equal(f.element('battState').textContent,'Charging state unavailable');
+  context.battery({percent:50,status:'Not charging'},null);
+  assert.equal(f.element('battState').textContent,'Not charging');
+  context.battery({percent:50,status:'Charging',watts:2,tempC:0},null);
+  assert.match(f.element('battState').textContent,/Charging/);
+  assert.match(f.element('battDetail').textContent,/battery 0°C/);
+  context.battery(null,null);
+  assert.equal(f.element('battState').textContent,'Battery unknown');
+});
+test('new health readings clear after a failed status read', () => {
+  const f=mounted();
+  f.ui.status({...sample(),battery:{...sample().battery,cycleCount:42,capacityHealthPercent:92,
+    fullMah:4600,designMah:5000,source:'/sys/class/power_supply/max1720x_bat_7-36'}});
+  assert.equal(f.element('metric-capacityHealth').textContent,'92%');
+  f.ui.unavailable(Error('Read failed'));
+  for (const key of ['cycles','fullCapacity','designCapacity','capacityHealth','batterySource'])
+    assert.equal(f.element('metric-'+key).textContent,'Unavailable');
+  f.ui.destroy();
+});
 test('audio controller validates before any API call and rejects offline or expired readings', async () => {
  let context={online:true,fresh:true,sample:sample(),device:'frame-a',generation:1},calls=[];
  const controller=cc.createController({api:async(...args)=>{calls.push(args);return {};},getContext:()=>context});
@@ -0,0 +1,43 @@
+"""Real doctor/SSH against fake-Frame faults; never a real headset."""
+import subprocess
+import sys
+
+import harness
+from harness import ROOT, ctl
+
+harness.require()
+
+
+class Doctor(harness.FrameTestCase):
+    def doctor(self):
+        return subprocess.run([sys.executable, str(ROOT / 'scripts/frame_doctor.py'),
+                               '--lan', harness.FAKE_HOST, '--usb', harness.FAKE_HOST],
+                              capture_output=True, text=True, timeout=120)
+
+    def test_disk_full(self):
+        before = self.doctor()
+        self.assertNotIn('BROKEN 4. Steam and storage', before.stdout)
+        ctl('disk-full', 'on')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 1, r.stdout + r.stderr)
+        self.assertIn('BROKEN 4. Steam and storage: Less than 16 MiB free', r.stdout)
+
+    def test_unreachable_asleep(self):
+        ctl('sleep', 'on')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 2, r.stdout + r.stderr)
+        self.assertIn('No authenticated SSH path', r.stdout)
+
+    def test_no_ssh_and_no_devkit(self):
+        ctl('sshd', 'off')
+        ctl('devkit-service', 'off')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 2, r.stdout + r.stderr)
+        self.assertIn('Devkit port did not respond', r.stdout)
+
+    def test_no_keys_but_devkit_available(self):
+        ctl('keys', 'none')
+        r = self.doctor()
+        self.assertEqual(r.returncode, 2, r.stdout + r.stderr)
+        self.assertIn('SSH key rejected', r.stdout)
+        self.assertIn('no pairing request was sent', r.stdout)
@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Doctor's read-only systemd queries in a container without a user manager.
+
+Stable NRestarts=0 and inactive keep-awake are harness assumptions, not observed
+device behavior. Real Frame query forms come from the historical doctor runbook
+(2026-09-28, BUILD_ID 20260925.6191901). No service control is emulated here.
+"""
+import sys
+
+args = sys.argv[1:]
+if args in (['--user', 'show', 'steam.service', '-p', 'NRestarts', '--value'],
+            ['--user', 'show', 'steamvr.service', '-p', 'NRestarts', '--value']):
+    print('0')
+elif args == ['--user', 'show', 'fc-keep-awake.service', '-p', 'ActiveState', '--value']:
+    print('inactive')
+else:
+    sys.exit(1)
@@ -13,11 +13,12 @@ BUILD_ID in tests/smoke/results/<time>-<BUILD_ID>.json (git-ignored):
  (someone has to open Settings > Developer > Pair new host and approve it in
  the headset), checked, and taken out of authorized_keys again.

-Everything it installs is removed again, also when a step fails: the titles
-(named fc_smoke_*, and leftovers of an interrupted run first), their Steam
+Everything it installs is removed again, also when a step fails: the reserved
+fc_smoke_{arm64,x86_64,exe} titles (and legacy leftovers first), their Steam
 shortcuts, the paired key, and ~/devkit-utils if it wasn't there before (if it
 was, it stays, synced to this checkout as Frame Control always does). A
-cleanup that fails is a failed step.
+cleanup that fails is a failed step. Test-owned processes are stopped and
+rechecked around deletion; shared Proton services are never stopped by name.

 Usage: python3 tests/smoke/frame_smoke.py [--pair]     (or scripts/frame-smoke.sh)
 Env:   FRAME_ALIAS (default frame), FRAME_SMOKE_RESULTS (default tests/smoke/results)
@@ -45,11 +46,17 @@ import frame_android  # noqa: E402
 import frame_connect  # noqa: E402
 import frame_titles  # noqa: E402
 import tiny_programs  # noqa: E402
+import stop_processes  # noqa: E402

 RESULTS = Path(os.environ.get('FRAME_SMOKE_RESULTS') or HERE / 'results')
 PREFIX = 'fc_smoke_'
-# Earlier runs named titles fc-smoke*, which Steam refused to register but left on disk.
-OLD_PREFIX = 'fc-smoke'
+
+
+def stop_titles(ids):
+    """Run the same bounded, PID-safe helper used by the local process tests."""
+    return json.loads(frame_android.ssh(
+        'python3 - ' + ' '.join(shlex.quote(gid) for gid in sorted(ids)),
+        input=(HERE / 'stop_processes.py').read_text(), timeout=20))


 class Smoke:
@@ -172,14 +179,17 @@ def title_cycle(smoke, kind, folder):
        return detail

    def remove():
+        stopped = stop_titles({gid})
        frame_titles.remove(gid)
+        # A wrapper could have launched a child just as deletion completed.
+        after = stop_titles({gid})
        left = ssh(f'ls -d ~/devkit-game/{gid} ~/devkit-game/{gid}-*.json 2>/dev/null || true').strip()
        if left:
            raise AssertionError(f'left behind: {left}')
        if gid in {t['id'] for t in frame_titles.list_titles()}:
            raise AssertionError(f'{gid} is still listed')
        smoke.installed.discard(gid)
-        return {'removed': gid}
+        return {'removed': gid, 'process_cleanup': [stopped, after]}

    if smoke.step(f'{kind}: install', install)['ok']:
        smoke.step(f'{kind}: launch', launch)
@@ -187,15 +197,21 @@ def title_cycle(smoke, kind, folder):


 def cleanup(smoke):
-    """Remove this run's titles and any fc_smoke_* an interrupted run left: the folder,
-    its json files, and (through steamos-delete) Steam's shortcut. Raises if anything stays."""
+    """Stop reserved smoke processes and remove their titles and shortcuts.
+
+    Legacy fc-smoke-* IDs are included; arbitrary similarly named titles are
+    never removed. Raises if any owned process, file or shortcut stays.
+    """
    problems = []
    try:
-        ids = {t['id'] for t in frame_titles.list_titles() if t['id'].startswith((PREFIX, OLD_PREFIX))}
+        ids = {t['id'] for t in frame_titles.list_titles() if t['id'] in stop_processes.IDS}
    except frame_android.FrameError as e:
        ids = set()
        problems.append(f'could not list titles: {e}')
    ids |= smoke.installed
+    # Scan every reserved ID, even when a prior run removed its folder and
+    # shortcut but left Proton running. Stop before removing any more files.
+    stopped = stop_titles(stop_processes.IDS)
    gone = set()
    for gid in sorted(ids):
        try:
@@ -226,9 +242,10 @@ def cleanup(smoke):
                    smoke.installed.discard(gid)
        except (frame_android.FrameError, AssertionError) as e:
            problems.append(f"syncing Steam's shortcuts: {e}")
+    after = stop_titles(stop_processes.IDS)
    if problems:
        raise AssertionError('; '.join(problems))
-    return {'removed': sorted(ids)}
+    return {'removed': sorted(ids), 'process_cleanup': [stopped, after]}


 # Runs on the Frame: drop the lines holding one key from authorized_keys, writing a
@@ -307,15 +324,17 @@ def main():
    # Frame Control copies Valve's devkit tools to ~/devkit-utils on the first install
    # (as Valve's client does). If they weren't there before, they go again at the end.
    had_utils = ssh('test -d ~/devkit-utils && echo yes || true').strip() == 'yes'
-    smoke.step('cleanup: leftovers from earlier runs', cleanup, smoke)
+    ready = smoke.step('cleanup: leftovers from earlier runs', cleanup, smoke)['ok']
    folder = tempfile.mkdtemp(prefix='frame-smoke-')
    try:
-        smoke.step('devkit service: properties.json', properties)
-        smoke.step('status', status, build)
-        for kind in ('arm64', 'x86_64', 'exe'):
-            title_cycle(smoke, kind, folder)
-        if args.pair:
-            smoke.step('devkit pairing (throwaway key)', pair, folder)
+        # Do not overwrite a leftover title when safe process cleanup failed.
+        if ready:
+            smoke.step('devkit service: properties.json', properties)
+            smoke.step('status', status, build)
+            for kind in ('arm64', 'x86_64', 'exe'):
+                title_cycle(smoke, kind, folder)
+            if args.pair:
+                smoke.step('devkit pairing (throwaway key)', pair, folder)
    finally:
        smoke.step('cleanup: everything this run installed', cleanup, smoke)
        if not had_utils:
@@ -0,0 +1,91 @@
+"""Linux-only smoke cleanup helper, sent over SSH before deleting test files.
+
+Only exact, reserved smoke title directories establish ownership. Never signal
+by process name, process group, Steam app id, or a shared Wine/Proton prefix.
+"""
+import json
+import os
+from pathlib import Path
+import signal
+import sys
+import time
+
+IDS = frozenset(prefix + kind for prefix in ('fc_smoke_', 'fc-smoke-')
+                for kind in ('arm64', 'x86_64', 'exe'))
+
+
+def owned(pid, roots):
+    """Require our uid and an exact cwd/exe or individual absolute argv path.
+
+    /proc retains a deleted cwd/exe with ' (deleted)' appended. This also lets
+    the final sweep catch an older run whose title was already removed.
+    """
+    proc = Path('/proc') / str(pid)
+    try:
+        if pid == os.getpid() or proc.stat().st_uid != os.getuid():
+            return False
+        state = (proc / 'stat').read_text().rsplit(')', 1)[1].split()[0]
+        if state == 'Z':
+            return False
+        paths = []
+        for key in ('cwd', 'exe'):
+            try:
+                paths.append(os.readlink(proc / key).removesuffix(' (deleted)'))
+            except (FileNotFoundError, PermissionError):
+                pass
+        try:
+            paths += os.fsdecode((proc / 'cmdline').read_bytes()).split('\0')
+        except PermissionError:
+            pass
+        return any(path == root or path.startswith(root + '/')
+                   for path in paths for root in roots)
+    except (FileNotFoundError, ProcessLookupError, PermissionError):
+        return False
+
+
+def candidates(roots):
+    return sorted(int(p.name) for p in Path('/proc').iterdir()
+                  if p.name.isdigit() and owned(int(p.name), roots))
+
+
+def stop(ids, grace=3):
+    if not ids or not set(ids) <= IDS:
+        raise ValueError('only reserved smoke title IDs may be stopped')
+    if not hasattr(os, 'pidfd_open') or not hasattr(signal, 'pidfd_send_signal'):
+        raise RuntimeError('safe smoke cleanup requires Linux Python with pidfd support')
+    roots = [str(Path.home() / 'devkit-game' / gid) for gid in ids]
+    stopped = set()
+    for sig in (signal.SIGTERM, signal.SIGKILL):
+        # Re-scan while waiting: wrappers can spawn a child during shutdown.
+        deadline = time.monotonic() + grace
+        while True:
+            pids = candidates(roots)
+            if not pids:
+                return {'stopped_pids': sorted(stopped)}
+            for pid in pids:
+                try:
+                    fd = os.pidfd_open(pid)
+                except ProcessLookupError:
+                    continue
+                try:
+                    # Open first, then revalidate ownership. The handle cannot
+                    # signal an unrelated process if this numeric PID is reused.
+                    if owned(pid, roots):
+                        try:
+                            signal.pidfd_send_signal(fd, sig)
+                            stopped.add(pid)
+                        except ProcessLookupError:
+                            pass
+                finally:
+                    os.close(fd)
+            if time.monotonic() >= deadline:
+                break
+            time.sleep(0.1)
+    left = candidates(roots)
+    if left:
+        raise RuntimeError(f'smoke processes survived cleanup: {left}')
+    return {'stopped_pids': sorted(stopped)}
+
+
+if __name__ == '__main__':
+    print(json.dumps(stop(sys.argv[1:])))
@@ -0,0 +1,86 @@
+"""Read-only sysfs battery parsing; fixture values, no real headset access."""
+import sandbox  # noqa: F401
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'ui'))
+import frame_status as status
+
+
+class Battery(unittest.TestCase):
+    def probe(self, fields):
+        # Real files exercise missing files, whitespace and integer conversion.
+        with tempfile.TemporaryDirectory() as tmp:
+            node = Path(tmp) / 'max1720x_bat_7-36'
+            node.mkdir()
+            for name, value in dict(type='Battery', **fields).items():
+                (node / name).write_text(str(value) + '\n')
+            with mock.patch.object(status.glob, 'glob', return_value=[str(node)]):
+                result = status.battery()
+            if result:
+                result.pop('source')
+            return result
+
+    def test_frame_units_and_optional_health(self):
+        b = self.probe(dict(capacity=73, status='Charging', voltage_now=3800000,
+                            current_now=1000000, temp=325, health='Good',
+                            charge_full=4600000, charge_full_design=5000000,
+                            cycle_count=42, time_to_full_now=3600))
+        self.assertEqual(b, dict(percent=73, status='Charging', watts=3.8,
+                                tempC=32.5, health='Good', timeToFull=3600,
+                                timeToEmpty=None, cycleCount=42, fullMah=4600,
+                                designMah=5000, capacityHealthPercent=92))
+
+    def test_zero_negative_current_and_temperature(self):
+        b = self.probe(dict(capacity=0, cycle_count=0, temp=-50,
+                            voltage_now=3800000, current_now=-1000000))
+        self.assertEqual((b['percent'], b['cycleCount'], b['tempC'], b['watts']),
+                         (0, 0, -5, -3.8))
+
+    def test_missing_optional_sensors_stay_null(self):
+        b = self.probe(dict(capacity=50, status='Discharging'))
+        self.assertEqual(b['percent'], 50)
+        self.assertTrue(all(value is None for key, value in b.items()
+                            if key not in ('percent', 'status')))
+
+    def test_invalid_values_do_not_break_other_readings(self):
+        for invalid in ('abc', '', '-1', '101', '12.5'):
+            b = self.probe(dict(capacity=invalid, status='Charging', temp='bad',
+                                charge_full=4500000, charge_full_design=0,
+                                time_to_full_now=-1, time_to_empty_now=4294967295,
+                                cycle_count=-1, voltage_now='bad', current_now=100))
+            self.assertIsNone(b['percent'])
+            for key in ('watts', 'tempC', 'capacityHealthPercent', 'timeToFull', 'timeToEmpty', 'cycleCount'):
+                self.assertIsNone(b[key], key)
+            self.assertEqual(b['status'], 'Charging')
+
+    def test_no_battery_and_unreadable_type(self):
+        with mock.patch.object(status.glob, 'glob', return_value=[]):
+            self.assertIsNone(status.battery())
+        with mock.patch.object(status.glob, 'glob', return_value=['/missing']), \
+                mock.patch('builtins.open', side_effect=PermissionError):
+            self.assertIsNone(status.battery())
+
+    def test_prefers_frame_and_excludes_peripheral_or_absent_batteries(self):
+        paths = ['/sys/class/power_supply/aaa', '/sys/class/power_supply/max1720x_bat_7-36']
+        def read(path):
+            return {'type': 'Battery', 'capacity': '80'}.get(path.rsplit('/', 1)[-1])
+        with mock.patch.object(status.glob, 'glob', return_value=paths), \
+                mock.patch.object(status, 'read', side_effect=read):
+            self.assertEqual(status.battery()['source'], paths[1])
+        self.assertIsNone(self.probe(dict(scope='Device', capacity=99)))
+        self.assertIsNone(self.probe(dict(present=0, capacity=99)))
+
+    def test_permission_failure_affects_only_one_sensor(self):
+        actual_open = open
+        def guarded(path, *args, **kwargs):
+            if str(path).endswith('/temp'):
+                raise PermissionError('unreadable')
+            return actual_open(path, *args, **kwargs)
+        with mock.patch('builtins.open', side_effect=guarded):
+            b = self.probe(dict(capacity=45, temp=300))
+        self.assertEqual(b['percent'], 45)
+        self.assertIsNone(b['tempC'])
@@ -0,0 +1,122 @@
+"""Doctor tests never contact a headset or the user's SSH configuration."""
+import importlib.util
+import io
+import json
+from pathlib import Path
+import subprocess
+import unittest
+from unittest.mock import patch, Mock
+
+ROOT = Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location('frame_doctor', ROOT / 'scripts/frame_doctor.py')
+doctor = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(doctor)
+doctor.MESSAGES = doctor.messages()
+
+
+def result(out='', code=0, err=''):
+    return subprocess.CompletedProcess([], code, out, err)
+
+
+class FrameDoctor(unittest.TestCase):
+    def main(self, responses, **kwargs):
+        config = result('hostname private-tailnet.ts.net\nhostkeyalias pinned-frame\n')
+        with patch.object(doctor.shutil, 'which', return_value='/usr/bin/ssh'), \
+                patch.object(doctor, 'run', side_effect=[config, *responses]) as run, \
+                patch.object(doctor, 'port_open', return_value=kwargs.get('devkit', False)), \
+                patch('sys.stdout', new_callable=io.StringIO) as output:
+            code = doctor.main([])
+        return code, output.getvalue(), run
+
+    def test_unreachable_is_actionable_without_exposing_stderr(self):
+        code, text, _ = self.main([result(code=255, err='secret-token 192.0.2.5')] * 3)
+        self.assertEqual(code, 2)
+        self.assertIn('wake headset', text)
+        self.assertEqual(text.count('No authenticated SSH path.'), 11)
+        self.assertNotIn('secret-token', text)
+        self.assertNotIn('192.0.2.5', text)
+        self.assertNotIn('private-tailnet', text)
+
+    def test_no_keys_and_devkit_available_never_registers(self):
+        code, text, run = self.main([result(code=255, err='Permission denied')] * 3, devkit=True)
+        self.assertEqual(code, 2)
+        self.assertIn('no pairing request was sent', text)
+        self.assertIn('Pair new host', text)
+        self.assertFalse(any('/register' in str(c.args[0]) for c in run.call_args_list))
+
+    def test_fallback_preserves_identity_and_disables_mutating_ssh_options(self):
+        _, text, run = self.main([result(code=255), result(json.dumps({'guard': 'loop', 'checks': []}))])
+        args = run.call_args_list[2].args[0]
+        for flag in ('HostKeyAlias=pinned-frame', 'HostName=frame.local', 'BatchMode=yes',
+                     'StrictHostKeyChecking=yes', 'UpdateHostKeys=no', 'PermitLocalCommand=no',
+                     'ClearAllForwardings=yes', 'ControlPath=none'):
+            self.assertIn(flag, args)
+        self.assertIn('OK Connection: LAN', text)
+        self.assertIn('Counters are rising', text)
+
+    def test_hostkey_failure_does_not_suggest_deleting_identity(self):
+        _, text, _ = self.main([result(code=255, err='REMOTE HOST IDENTIFICATION HAS CHANGED')] * 3)
+        self.assertIn('Do not delete known_hosts', text)
+
+    def test_invalid_probe_response_never_prints_remote_data(self):
+        for payload in ('a secret token', json.dumps({'guard': 'stable', 'checks': [['OK', 'secret']] * 11})):
+            code, text, _ = self.main([result(payload)])
+            self.assertEqual(code, 1)
+            self.assertNotIn('secret', text)
+
+    def test_guard_stops_before_any_deeper_checks(self):
+        for state in ('loop', 'unknown', 'risk'):
+            with patch.object(doctor, 'guard', return_value=state), patch.object(doctor, 'journal') as journal:
+                self.assertEqual(doctor.probe(), {'guard': state, 'checks': []})
+                journal.assert_not_called()
+
+    def test_rising_and_reset_counters_and_missing_data(self):
+        for snapshots, expected in (([[0, 0, 0, 0], [1, 0, 0, 0]], 'loop'),
+                                    ([[1, 0, 0, 0], [0, 0, 0, 0]], 'unknown'),
+                                    ([None, None], 'unknown'),
+                                    ([[0, 4, 0, 0]] * 2, 'risk'),
+                                    ([[0, 0, 0, 0]] * 2, 'stable')):
+            with patch.object(doctor, 'snapshot', side_effect=snapshots), patch.object(doctor.time, 'sleep'):
+                self.assertEqual(doctor.guard(), expected)
+
+    def test_journal_permission_denied_and_empty_are_unknown(self):
+        for response in (result('partial', err='not seeing messages from other users'), result(), result(code=1)):
+            with patch.object(doctor, 'run', return_value=response):
+                self.assertIsNone(doctor.journal('-b'))
+        self.assertEqual(doctor.signal_check(None, 'bad', 'problem', 'healthy')[0], 'UNKNOWN')
+
+    def test_disk_full_reports_broken_and_never_fixes(self):
+        with patch.object(doctor.shutil, 'disk_usage', return_value=Mock(free=0)):
+            check = doctor.storage()
+        with patch('sys.stdout', new_callable=io.StringIO) as output:
+            code = doctor.report({'guard': 'stable', 'checks': [check] * 11})
+        self.assertEqual(code, 1)
+        self.assertIn('BROKEN 4. Steam and storage', output.getvalue())
+
+    def test_probe_only_emits_approved_messages_and_rechecks_guard(self):
+        with patch.object(doctor, 'guard', side_effect=['stable', 'stable']) as guard, \
+                patch.object(doctor, 'journal', return_value=None), \
+                patch.object(doctor, 'command', return_value=None), \
+                patch.object(doctor, 'run', return_value=None), \
+                patch.object(doctor, 'storage', return_value=['UNKNOWN', 'Storage could not be read.']):
+            data = doctor.probe()
+        self.assertEqual(guard.call_count, 2)
+        self.assertEqual(len(data['checks']), 11)
+        with patch('sys.stdout', new_callable=io.StringIO):
+            self.assertEqual(doctor.report(data), 1)
+
+    def test_help_shell_entry_point_is_offline(self):
+        # This Bash wrapper is for macOS/Linux; Windows uses the Python CLI.
+        import os, shutil
+        if os.name == 'nt':
+            self.skipTest('POSIX shell wrapper')
+        if not shutil.which('bash'):
+            self.skipTest('bash unavailable')
+        r = subprocess.run(['bash', str(ROOT / 'scripts/frame-doctor.sh'), '--help'],
+                           capture_output=True, text=True, timeout=5)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertIn('Never pairs', r.stdout)
+
+
+if __name__ == '__main__':
+    unittest.main()
@@ -0,0 +1,153 @@
+"""Smoke cleanup against real local Linux processes, never a headset or SSH."""
+import sandbox  # noqa: F401
+import os
+from pathlib import Path
+import shutil
+import shlex
+import signal
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+SMOKE = Path(__file__).resolve().parent / 'smoke'
+sys.path.insert(0, str(SMOKE))
+import stop_processes  # noqa: E402
+import frame_smoke  # noqa: E402
+
+
+@unittest.skipUnless(sys.platform == 'linux' and hasattr(os, 'pidfd_open'), 'Linux pidfds required')
+class RealProcesses(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.home = Path(self.tmp.name)
+        self.title = self.home / 'devkit-game' / 'fc_smoke_exe'
+        self.title.mkdir(parents=True)
+        self.children = []
+        self.patcher = mock.patch.object(stop_processes.Path, 'home', return_value=self.home)
+        self.patcher.start()
+        self.addCleanup(self.patcher.stop)
+        self.addCleanup(self.reap)
+
+    def reap(self):
+        for child in self.children:
+            if child.poll() is None:
+                child.kill()
+            child.wait(timeout=5)
+
+    def start(self, cwd, *args, ignore=False):
+        code = ('import signal,time; '
+                + ('signal.signal(signal.SIGTERM, signal.SIG_IGN); ' if ignore else '')
+                + 'print("ready", flush=True); time.sleep(60)')
+        child = subprocess.Popen([sys.executable, '-c', code, *args], cwd=cwd,
+                                 stdout=subprocess.PIPE, text=True)
+        self.children.append(child)
+        self.addCleanup(child.stdout.close)
+        self.assertEqual(child.stdout.readline().strip(), 'ready')
+        return child
+
+    def test_deleted_title_process_is_stopped_but_similar_names_survive(self):
+        owned = self.start(self.title)
+        neighbour = self.title.with_name('fc_smoke_exe_other')
+        neighbour.mkdir()
+        other = self.start(neighbour, 'fc_smoke_exe', 'wine', 'proton')
+        shutil.rmtree(self.title)
+        # Reproduces the old success condition: no title remains, yet it runs.
+        self.assertFalse(self.title.exists())
+        self.assertIsNone(owned.poll())
+        def local_target(command, *, input, timeout):
+            return subprocess.run(shlex.split(command), input=input, text=True,
+                                  capture_output=True, check=True, timeout=timeout,
+                                  env={**os.environ, 'HOME': str(self.home)}).stdout
+
+        # Exercise the production SSH command and stdin payload against a local
+        # fake target, including the helper's CLI and JSON result contract.
+        with mock.patch.object(frame_smoke.frame_android, 'ssh', side_effect=local_target):
+            result = frame_smoke.stop_titles({'fc_smoke_exe'})
+        self.assertIn(owned.pid, result['stopped_pids'])
+        self.assertEqual(owned.wait(timeout=5), -signal.SIGTERM)
+        self.assertIsNone(other.poll())
+
+    def test_proton_style_absolute_argument_escalates_without_stopping_shared_wine(self):
+        owned = self.start(self.home, str(self.title / 'fc-smoke-exe.exe'), ignore=True)
+        shared = self.start(self.home, 'wineserver', '-p')
+        quoted = self.start(self.home, 'echo ' + str(self.title / 'fc-smoke-exe.exe'))
+        result = stop_processes.stop(['fc_smoke_exe'], grace=0.2)
+        self.assertIn(owned.pid, result['stopped_pids'])
+        self.assertEqual(owned.wait(timeout=5), -signal.SIGKILL)
+        self.assertIsNone(shared.poll())
+        self.assertIsNone(quoted.poll())
+        self.assertEqual(stop_processes.stop(['fc_smoke_exe']), {'stopped_pids': []})
+
+    def test_unreadable_cwd_does_not_abort_scan_or_hide_readable_argv(self):
+        owned = self.start(self.home, str(self.title / 'fc-smoke-exe.exe'))
+        other = self.start(self.home, 'wineserver')
+        with mock.patch.object(stop_processes.os, 'readlink', side_effect=PermissionError):
+            self.assertTrue(stop_processes.owned(owned.pid, [str(self.title)]))
+            self.assertFalse(stop_processes.owned(other.pid, [str(self.title)]))
+            result = stop_processes.stop(['fc_smoke_exe'], grace=0.2)
+        self.assertIn(owned.pid, result['stopped_pids'])
+        self.assertEqual(owned.wait(timeout=5), -signal.SIGTERM)
+        self.assertIsNone(other.poll())
+
+
+class Safety(unittest.TestCase):
+    def test_non_test_ids_rejected_before_scanning(self):
+        for ids in ([], ['portal2'], ['fc_smoke_exe/../portal2'], ['fc_smoke_custom']):
+            with self.subTest(ids=ids), self.assertRaises(ValueError):
+                stop_processes.stop(ids)
+
+    @unittest.skipUnless(sys.platform == 'linux', 'Linux signalling helper')
+    def test_lost_ownership_after_open_never_signalled(self):
+        with mock.patch.object(stop_processes, 'candidates', side_effect=[[123], [], []]), \
+                mock.patch.object(stop_processes.os, 'pidfd_open', return_value=9, create=True), \
+                mock.patch.object(stop_processes.os, 'close'), \
+                mock.patch.object(stop_processes, 'owned', return_value=False), \
+                mock.patch.object(stop_processes.signal, 'pidfd_send_signal', create=True) as send:
+            self.assertEqual(stop_processes.stop(['fc_smoke_exe'], grace=0), {'stopped_pids': []})
+            send.assert_not_called()
+
+    @unittest.skipUnless(sys.platform == 'linux', 'Linux signalling helper')
+    def test_survivor_is_a_failure(self):
+        with mock.patch.object(stop_processes, 'candidates', return_value=[123]), \
+                mock.patch.object(stop_processes.os, 'pidfd_open', return_value=9, create=True), \
+                mock.patch.object(stop_processes.os, 'close'), \
+                mock.patch.object(stop_processes, 'owned', return_value=True), \
+                mock.patch.object(stop_processes.signal, 'pidfd_send_signal', create=True):
+            with self.assertRaisesRegex(RuntimeError, 'survived cleanup'):
+                stop_processes.stop(['fc_smoke_exe'], grace=0)
+
+    def test_cleanup_scans_even_when_title_already_removed(self):
+        with mock.patch.object(frame_smoke.frame_titles, 'list_titles', return_value=[]), \
+                mock.patch.object(frame_smoke, 'ssh') as ssh, \
+                mock.patch.object(frame_smoke, 'stop_titles', return_value={'stopped_pids': [42]}) as stop:
+            result = frame_smoke.cleanup(frame_smoke.Smoke())
+            self.assertEqual(stop.call_args_list, [mock.call(stop_processes.IDS)] * 2)
+            self.assertEqual(result['process_cleanup'][0]['stopped_pids'], [42])
+            ssh.assert_not_called()
+
+    def test_stop_failure_prevents_file_removal(self):
+        with mock.patch.object(frame_smoke.frame_titles, 'list_titles', return_value=[{'id': 'fc_smoke_exe'}]), \
+                mock.patch.object(frame_smoke, 'ssh') as ssh, \
+                mock.patch.object(frame_smoke, 'stop_titles', side_effect=RuntimeError('still running')):
+            with self.assertRaisesRegex(RuntimeError, 'still running'):
+                frame_smoke.cleanup(frame_smoke.Smoke())
+            ssh.assert_not_called()
+
+    def test_failed_initial_cleanup_prevents_install_and_records_failure(self):
+        with tempfile.TemporaryDirectory() as folder, \
+                mock.patch.object(frame_smoke, 'RESULTS', Path(folder)), \
+                mock.patch.object(frame_smoke.sys, 'argv', ['frame_smoke.py']), \
+                mock.patch.object(frame_smoke.subprocess, 'run', return_value=mock.Mock(returncode=0)), \
+                mock.patch.object(frame_smoke.tempfile, 'mkdtemp', return_value=folder), \
+                mock.patch.object(frame_smoke, 'os_release', return_value={
+                    'BUILD_ID': 'fake', 'VERSION_ID': 'fake', 'VARIANT_ID': 'fake'}), \
+                mock.patch.object(frame_smoke, 'ssh', return_value='yes'), \
+                mock.patch.object(frame_smoke, 'cleanup', side_effect=RuntimeError('cannot stop')), \
+                mock.patch.object(frame_smoke, 'title_cycle') as cycle, \
+                mock.patch('builtins.print'):
+            self.assertEqual(frame_smoke.main(), 1)
+            cycle.assert_not_called()
+            self.assertEqual(len(list(Path(folder).glob('*-fake.json'))), 1)
@@ -16,8 +16,8 @@
      description:'Set the default headset output volume or mute it. Changes apply only when you choose Apply or Mute.',
      keywords:'sound speakers headphones loud quiet', special:'audio'},
    {id:'health', category:'device', icon:'pulse', title:'Battery & thermal health', kind:'read', label:'Read-only metrics',
-      description:'Inspect charge, signed battery power, charger capability, battery temperature and health. Heat warnings use the kernel’s own hot and critical trip points.',
-      keywords:'battery charging charger charge time estimate remaining power watts usb health heat temperature thermal sensor', special:'health', links:[['#comfort','Configure battery & heat alerts']]},
+      description:'Inspect charge, signed battery power, charger readings, battery temperature, health and optional capacity / cycle readings. Heat warnings use the kernel’s own hot and critical trip points.',
+      keywords:'battery charging charger charge time estimate remaining power watts usb health cycles capacity wear heat temperature thermal sensor', special:'health', links:[['#comfort','Configure battery & heat alerts']]},
    {id:'storage', category:'device', icon:'files', title:'Storage & memory', kind:'read', label:'Read-only metrics',
      description:'Check free user and system storage plus available RAM. Manage installed apps in their existing libraries, or use SFTP for files.',
      keywords:'disk space root home free total ram memory capacity cleanup usage storage', special:'storage', links:[['#library','Installed games'],['#linuxApps','Linux apps'],['#power','SFTP & remote tools']]},
@@ -144,9 +144,9 @@
    const capacity = b.percent;
    const idle = !!s.power && Number.isFinite(b.watts) && Math.abs(b.watts) < .5;
    const charging = b.status === 'Charging';
-    const full = b.status === 'Full' || (!!s.power && capacity >= 100);
+    const full = b.status === 'Full';
    const batteryState = !sample ? 'Connect to read charge and power' : !s.battery ? 'Battery sensor unavailable' :
-      full ? 'Fully charged' : charging ? 'Charging' : idle ? 'Plugged in · not charging' : s.power ? 'Plugged in · on battery' : 'On battery';
+      full ? 'Fully charged' : charging ? 'Charging' : b.status === 'Not charging' || idle ? (s.power ? 'Plugged in · not charging' : 'Not charging') : b.status === 'Discharging' ? (s.power ? 'Plugged in · on battery' : 'On battery') : 'Charging state unavailable';
    return {
      battery:number(capacity, '%'), batteryDetail:batteryState,
      storage:h ? gib(h.free) : 'Unavailable', storageDetail:h ? `${gib(h.total)} total · user storage` : 'User storage unavailable',
@@ -155,8 +155,11 @@
      rootFree:gib(s.disk?.root?.free), rootTotal:gib(s.disk?.root?.total), memoryAvailable:gib(m?.available),
      fps:number(p.compositorFps, '', 1), fpsDetail:'Compositor FPS · not game FPS',
      power:number(b.watts, ' W', 1), charger:s.power ? `${s.power.type || 'Connected'} · ${number(s.power.watts, ' W', 1)}` : sample ? 'No charger reported' : 'Unavailable',
-      batteryTemp:number(b.tempC, ' °C', 1), batteryHealth:b.health || 'Unavailable',
-      estimate:charging ? (b.timeToFull > 0 ? `${duration(b.timeToFull)} to full` : 'Unavailable') : !full && !idle && b.timeToEmpty > 0 && b.timeToEmpty < 86400 ? `${duration(b.timeToEmpty)} remaining` : 'Unavailable',
+      batteryTemp:number(b.tempC, ' °C', 1), batteryHealth:b.health && b.health !== 'Unknown' ? b.health : 'Unavailable',
+      batterySource:b.source || 'Unavailable', cycles:number(b.cycleCount),
+      fullCapacity:number(b.fullMah, ' mAh', 1), designCapacity:number(b.designMah, ' mAh', 1),
+      capacityHealth:number(b.capacityHealthPercent, '%', 1),
+      estimate:charging ? (b.timeToFull > 0 ? `${duration(b.timeToFull)} to full` : 'Unavailable') : b.status === 'Discharging' && !idle && b.timeToEmpty > 0 && b.timeToEmpty < 86400 ? `${duration(b.timeToEmpty)} remaining` : 'Unavailable',
      wifi:s.wifi?.ssid || 'Unavailable', signal:number(s.wifi?.signal, '%'), ip:s.ip || 'Unavailable',
      uptime:duration(s.uptime), os:s.os?.version || 'Unavailable', build:s.os?.build || 'Unavailable',
      temperature:number(s.temp, ' °C', 1), cpu:number(p.cpuPercent, '%', 1), gpu:number(p.gpuMHz, ' MHz', 1),
@@ -214,7 +217,8 @@
    const metric = (id, label) => `<div><dt>${label}</dt><dd data-cc-metric="${id}">Unavailable</dd></div>`;
    const perf = `<dl class="cc-readings">${[['appFps','Application FPS'],['frame','Compositor period'],['render','Render GPU time'],['compositorCpu','Compositor CPU'],['cpu','System CPU'],['gpu','GPU clock'],['temperature','Hottest sensor']].map(([id,label])=>metric(id,label)).join('')}</dl><p class="cc-note">GPU time is render time, not utilisation. The hottest sensor is not necessarily CPU temperature.</p><p class="cc-note" data-cc-metric="thermal">Trip data unavailable</p>`;
    const audio = `<div class="cc-audio"><label for="ccVolume">Output volume <output id="ccVolumeValue" for="ccVolume">—</output></label><input id="ccVolume" type="range" min="0" max="100" step="1" value="0" disabled><div class="cc-audio-actions"><button class="action small" id="ccApplyVolume" disabled>Apply volume</button><button class="small" id="ccMute" disabled>Mute</button><span id="ccAudioReadback" class="cc-note">Waiting for an audio reading</span></div><p class="cc-note" id="ccAudioResult" role="status"></p></div>`;
-    const health = `<dl class="cc-readings">${[['battery','Charge'],['power','Battery power · signed'],['charger','Charger'],['estimate','Battery estimate'],['batteryTemp','Battery temperature'],['batteryHealth','Battery health']].map(([id,label])=>metric(id,label)).join('')}</dl>`;
+    const batteryNote = 'Read-only. Unavailable means not reported, unreadable or invalid. Health is the driver’s status; full / design capacity is a fuel-gauge estimate, not a diagnosis. Charge limits are unsupported on Frame.';
+    const health = `<dl class="cc-readings">${[['battery','Charge'],['batteryDetail','Charging state'],['power','Battery power · signed'],['charger','Charger'],['estimate','Battery estimate'],['batteryTemp','Battery temperature'],['batteryHealth','Battery health'],['cycles','Charge cycles'],['fullCapacity','Full charge capacity'],['designCapacity','Design capacity'],['capacityHealth','Full / design capacity'],['batterySource','Battery source']].map(([id,label])=>metric(id,label)).join('')}</dl><p class="cc-note">${batteryNote}</p>`;
    const forcequit = `<div class="cc-quit"><div class="cc-audio-actions"><button class="small" type="button" id="ccRunningCheck">Check what’s running</button></div><ul class="cc-running" id="ccRunningList"></ul><p class="cc-note" id="ccRunningResult" role="status"></p></div>`;
    const storage = `<dl class="cc-readings">${[['storage','User storage free'],['rootFree','System storage free'],['rootTotal','System storage total'],['memoryAvailable','Memory available']].map(([id,label])=>metric(id,label)).join('')}</dl>`;
    get('ccCategories').innerHTML = categories.map(([id,label,symbol])=>`<button type="button" data-cc-category="${id}" aria-pressed="${id === 'all'}">${icon(symbol)}<span>${label}</span><span class="cc-category-count"></span></button>`).join('');
@@ -45,19 +45,40 @@ def num(path, scale=1.0):


 def battery():
-    for d in glob.glob("/sys/class/power_supply/*"):
+    # Prefer the documented Frame fuel gauge over controller/peripheral batteries.
+    supplies = sorted(glob.glob("/sys/class/power_supply/*"),
+                      key=lambda d: (os.path.basename(d) != "max1720x_bat_7-36", d))
+    for d in supplies:
        if read(d + "/type") != "Battery":
            continue
-        cap = read(d + "/capacity")
+        if read(d + "/scope") == "Device" or read(d + "/present") == "0":
+            continue
+
+        def value(name, scale=1, minimum=None, maximum=None):
+            n = num(d + "/" + name, scale)
+            if n is None or not math.isfinite(n):
+                return None
+            if (minimum is not None and n < minimum) or (maximum is not None and n > maximum):
+                return None
+            return n
+
        # max1720x reports microvolts/microamps; current is positive while charging.
-        volts, amps = num(d + "/voltage_now", 1e-6), num(d + "/current_now", 1e-6)
-        return {"percent": int(cap) if cap and cap.isdigit() else None,
+        volts, amps = value("voltage_now", 1e-6, 0), value("current_now", 1e-6)
+        full = value("charge_full", 1e-3, 0)
+        design = value("charge_full_design", 1e-3, 0)
+        return {"source": d,
+                "percent": value("capacity", minimum=0, maximum=100),
                "status": read(d + "/status"),
                "watts": round(volts * amps, 2) if volts is not None and amps is not None else None,
-                "timeToFull": num(d + "/time_to_full_now"),
-                "timeToEmpty": num(d + "/time_to_empty_now"),
-                "tempC": num(d + "/temp", 0.1),
-                "health": read(d + "/health")}
+                # Reject negative/unsigned sentinel estimates and implausible temperatures.
+                "timeToFull": value("time_to_full_now", minimum=1, maximum=604800),
+                "timeToEmpty": value("time_to_empty_now", minimum=1, maximum=604800),
+                "tempC": value("temp", 0.1, -273.15, 200),
+                "health": read(d + "/health"),
+                "cycleCount": value("cycle_count", minimum=0),
+                "fullMah": full if full else None,
+                "designMah": design if design else None,
+                "capacityHealthPercent": round(full / design * 100, 1) if full and design else None}
    return None


@@ -1127,7 +1127,10 @@
          <div><dt>Battery power · signed</dt><dd data-cc-metric="power">Unavailable</dd></div><div><dt>Charger</dt><dd data-cc-metric="charger">Unavailable</dd></div>
          <div><dt>Battery temperature</dt><dd data-cc-metric="batteryTemp">Unavailable</dd></div><div><dt>Battery health</dt><dd data-cc-metric="batteryHealth">Unavailable</dd></div>
          <div><dt>Battery estimate</dt><dd data-cc-metric="estimate">Unavailable</dd></div>
-        </dl><p class="cc-note">Positive battery watts mean charging; negative means discharge. Estimates are reported by the battery and may be unavailable.</p>
+          <div><dt>Charge cycles</dt><dd data-cc-metric="cycles">Unavailable</dd></div><div><dt>Full charge capacity</dt><dd data-cc-metric="fullCapacity">Unavailable</dd></div>
+          <div><dt>Design capacity</dt><dd data-cc-metric="designCapacity">Unavailable</dd></div><div><dt>Full / design capacity</dt><dd data-cc-metric="capacityHealth">Unavailable</dd></div>
+          <div><dt>Battery source</dt><dd data-cc-metric="batterySource">Unavailable</dd></div>
+        </dl><p class="cc-note">Positive battery watts mean charging; negative means discharge. Unavailable sensors are not reported, unreadable or invalid. Health is the driver’s status; full / design capacity is a fuel-gauge estimate, not a diagnosis. Charge limits are unsupported on Frame.</p>
        <div class="cc-services" id="ccServices"></div>
      </details>
    </section>
@@ -1995,6 +1998,8 @@
    <input type="text" id="caLabel" maxlength="60" placeholder="Label, e.g. Home" aria-label="Label for the new address">
    <button class="small" type="submit">Add</button></form>
  <details class="conn-more" id="connMore"><summary>Connection steps</summary>
+    <p class="sub">Trouble setting up or pairing? <a href="https://github.com/saphid/frame-control/blob/main/docs/frame-doctor.md" target="_blank" rel="noopener noreferrer">Read-only diagnostic guide</a>
+      explains how to check a connection without sharing passwords or keys.</p>
    <ol class="stages" id="connStages"></ol>
    <h3>This computer</h3>
    <dl class="facts" id="connNet"></dl>
@@ -2436,12 +2441,11 @@ $("castBtn").onclick = () => {
 // ---- battery ----
 function battery(b, power) {
  const pct = b?.percent;
-  const full = b?.status === "Full" || (!!power && pct >= 100);
+  const full = b?.status === "Full";
  const charging = !full && b?.status === "Charging";
  // A weak charger can lose to the load: plugged in but still draining.
  // Topped up on a charger it reports Discharging at ~0 W: that's idle, not draining.
  const idle = !!power && b?.watts != null && Math.abs(b.watts) < 0.5;
-  const draining = !full && !charging && !idle && (!power || b?.status === "Discharging" || b?.watts < 0);
  const low = !charging && !full && pct != null && pct <= 15;
  const color = full || charging ? "#59bf40" : low ? "#d94126" : pct != null && pct <= 30 ? "#d9a23a" : "#dcdedf";

@@ -2451,7 +2455,8 @@ function battery(b, power) {
  else if (charging) {
    label = b.watts > 0 ? `Charging · ${b.watts.toFixed(1)} W` : "Charging"; cls = "charging";
    if (b.timeToFull > 0) detail.push(`Full in ${dur(b.timeToFull)}`);
-  } else if (!draining) { label = "Plugged in, not charging"; cls = "draining"; }
+  } else if (b.status === "Not charging" || idle) { label = "Not charging"; cls = "draining"; }
+  else if (b.status !== "Discharging") { label = "Charging state unavailable"; cls = "draining"; }
  else {
    label = low ? "Battery low" : power ? "Plugged in, still draining" : "On battery";
    cls = low ? "low" : "draining";