doctor_platform.py 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659
  1. """Host-platform checks for hermes doctor: interpreter, SQLite, certificates, macOS TCC, gateway supervision, command install.
  2. Split out of ``hermes_cli/doctor.py``, which re-exports every name so ``hermes_cli.doctor.<name>`` keeps resolving (and monkeypatching)."""
  3. from __future__ import annotations
  4. import os
  5. import shutil
  6. import ssl
  7. import subprocess
  8. import sys
  9. from pathlib import Path
  10. from hermes_cli.colors import Colors, color
  11. from hermes_cli.config import is_nix_install_method, recommended_update_command_for_method
  12. from hermes_cli.doctor_report import (
  13. Finding, _fail_and_issue, _section, check_bool, check_fail, check_info, check_ok, check_warn, doctor_check,
  14. warn_on_error,
  15. )
  16. from hermes_constants import is_termux as _is_termux
  17. def _python_repair_hint() -> str:
  18. from hermes_cli.config import detect_install_method
  19. from hermes_cli.doctor import PROJECT_ROOT
  20. method = detect_install_method(PROJECT_ROOT)
  21. if is_nix_install_method(method):
  22. return recommended_update_command_for_method(method)
  23. if method in ("docker", "apt"):
  24. command = recommended_update_command_for_method(method)
  25. return f"Run `{command}`" + (", then recreate the Hermes container" if method == "docker" else "")
  26. return "Run `hermes pm repair`, then restart Hermes"
  27. def _system_package_install_cmd(pkg: str) -> str:
  28. return f"{'pkg' if _is_termux() else 'brew' if sys.platform == 'darwin' else 'sudo apt'} install {pkg}"
  29. def _sqlite_upgrade_hint(install_method: str | None = None) -> str:
  30. """Return an actionable SQLite upgrade hint for this install layout."""
  31. from hermes_cli.doctor import PROJECT_ROOT
  32. from hermes_cli.config import detect_install_method
  33. method = install_method or detect_install_method(PROJECT_ROOT)
  34. cmd = recommended_update_command_for_method(method)
  35. action = cmd if is_nix_install_method(method) else { # nix: prose guidance, not a shell command
  36. "docker": f"run `{cmd}`, then recreate all Hermes containers", "apt": f"run `{cmd}`"}.get(method, "run `hermes update`")
  37. return f"({action}; fixed versions: 3.51.3+ / 3.50.7 / 3.44.6 — see https://sqlite.org/wal.html#walresetbug)"
  38. def _hermes_database_paths(hermes_home: Path) -> list[tuple[str, Path]]:
  39. """(display name, path) pairs for Hermes-managed SQLite databases: backup.py's per-profile store list + per-board kanban.db."""
  40. from hermes_cli.backup import _QUICK_STATE_FILES
  41. entries = [(name, hermes_home / name) for name in _QUICK_STATE_FILES if name.endswith(".db")]
  42. for board_db in sorted((hermes_home / "kanban" / "boards").glob("*/kanban.db")):
  43. entries.append((str(board_db.relative_to(hermes_home)), board_db))
  44. return entries
  45. _SQLITE_HEADER_MAGIC = b"SQLite format 3\x00"
  46. def _unreadable_reason(db_path: Path) -> str:
  47. """Explain why a database file could not be read, without opening it.
  48. ``read_header_bytes_preopen`` collapses every ``OSError`` into ``None``, but doctor must say *which*
  49. problem it hit. ``stat()``/``access()`` answer from directory metadata alone — no descriptor, no lock loss.
  50. """
  51. try:
  52. db_path.stat()
  53. except OSError as exc:
  54. return str(exc)
  55. return "file could not be read" if os.access(db_path, os.R_OK) else f"permission denied: {db_path}"
  56. def _read_journal_mode(db_path: Path) -> tuple[str | None, str | None]:
  57. """Return (journal mode, error) from header byte 18 (2=WAL, 1=rollback) without opening the database.
  58. Opening through SQLite — even read-only — creates -wal/-shm sidecars, which a diagnostic must not do.
  59. ``read_header_bytes_preopen`` rather than a bare ``open()``: closing *any* descriptor cancels this
  60. process's POSIX advisory locks (see ``hermes_cli.sqlite_safe_read``), and the dashboard console runs
  61. ``run_doctor`` in-process with live ``SessionDB`` connections — the helper refuses then (unreadable).
  62. """
  63. from hermes_cli.sqlite_safe_read import has_live_connection, read_header_bytes_preopen
  64. header = read_header_bytes_preopen(db_path, length=20)
  65. if header is None:
  66. return None, "database is open in this process" if has_live_connection(db_path) else _unreadable_reason(db_path)
  67. if len(header) == 0:
  68. return None, "file is empty"
  69. if len(header) < 20 or not header.startswith(_SQLITE_HEADER_MAGIC):
  70. return None, "file is not a database"
  71. mode = {2: "wal", 1: "rollback"}.get(header[18])
  72. return (mode, None) if mode else (None, f"unrecognized file-format version {header[18]}")
  73. def _format_db_size(db_path: Path) -> str:
  74. from hermes_cli.sizefmt import format_bytes as _format_size
  75. try:
  76. return _format_size(db_path.stat().st_size)
  77. except OSError:
  78. return "size unknown"
  79. def _report_database_holders(name: str, db_path: Path) -> None:
  80. """Name the processes holding ``db_path`` (or a WAL sidecar) so the operator knows what to stop before the
  81. offline journal-mode conversion; a partial or unavailable scan is reported as "cannot prove quiet", never as
  82. an all-clear (the scan is the same fail-closed authority repair/VACUUM/checkpoint admission uses)."""
  83. from hermes_state_holders import describe_holder_pid, foreign_state_db_holders
  84. unknown: list[str] = []
  85. by_pid: dict[int, set[str]] = {}
  86. for pid, target in foreign_state_db_holders(db_path):
  87. if pid <= 0 or target.startswith("uninspectable"):
  88. unknown.append(target)
  89. else:
  90. by_pid.setdefault(pid, set()).add(Path(target.removesuffix(" (deleted)")).name)
  91. for pid in sorted(by_pid):
  92. check_info(f"{name} is held by {describe_holder_pid(pid)}: {', '.join(sorted(by_pid[pid]))}")
  93. if unknown:
  94. check_warn(f"{name}: cannot prove the database is quiet",
  95. f"(holder scan incomplete: {unknown[0][:120]}" + (f"; +{len(unknown) - 1} more" if len(unknown) > 1 else "") + ")")
  96. elif not by_pid:
  97. check_info(f"{name}: no other process holds it right now — the offline conversion can run")
  98. def _report_database_journal_modes(hermes_home: Path | None = None, version_info: tuple[int, ...] | None = None) -> None:
  99. """List each database's journal mode; warn on WAL under a vulnerable SQLite, and on a configured
  100. ``database.journal_mode: delete`` that never took effect."""
  101. from hermes_cli.doctor import HERMES_HOME
  102. from hermes_state_wal import (
  103. _path_on_cross_vm_fs, _wal_reset_repair_hint, is_sqlite_wal_reset_vulnerable, resolve_journal_mode,
  104. )
  105. vulnerable = is_sqlite_wal_reset_vulnerable(version_info)
  106. configured = resolve_journal_mode()
  107. try:
  108. databases = _hermes_database_paths(hermes_home if hermes_home is not None else HERMES_HOME)
  109. except Exception as exc:
  110. check_warn(f"Could not list Hermes databases: {exc}")
  111. return
  112. exposed = []
  113. for name, path in databases:
  114. if not path.is_file():
  115. continue
  116. mode, error = _read_journal_mode(path)
  117. size = _format_db_size(path)
  118. if error is None and mode == "wal" and configured == "delete":
  119. # The operator configured `delete` because WAL is unsafe on their filesystem, but the runtime never
  120. # live-downgrades an existing WAL database (#68545: a downgrade under open connections corrupts it)
  121. # and says so only once per process in the gateway log (#85608). Doctor is the surface they check;
  122. # a plain "WAL journal mode" line here reads as protected. Outranks the sibling WAL messages: the
  123. # cross-VM hint's remedy ("set journal_mode: delete") is already applied.
  124. if vulnerable:
  125. exposed.append(name)
  126. check_warn(f"{name} is in WAL mode ({size}) despite database.journal_mode=delete",
  127. "(the setting never applied: an existing WAL database is never live-downgraded"
  128. + ("; also exposed to the WAL-reset bug" if vulnerable else "")
  129. + ". Stop every Hermes process for this profile, then run "
  130. f"`hermes sessions set-journal-mode delete{'' if name == 'state.db' else f' --db {path}'}`)")
  131. _report_database_holders(name, path)
  132. elif error is not None:
  133. if vulnerable:
  134. check_warn(f"{name}: journal mode could not be read", f"({error}; cannot rule out WAL exposure)")
  135. else:
  136. check_info(f"{name}: journal mode could not be read ({error})")
  137. elif mode == "wal" and _path_on_cross_vm_fs(str(path)):
  138. # #110848: WAL shared-memory is not coherent across a virtiofs/9p bind mount; startup only refuses WAL
  139. # for FRESH databases, so an existing WAL file here keeps corrupting until the operator converts it.
  140. # Checked before the WAL-reset exposure: active cross-VM corruption outranks a latent bug class.
  141. if vulnerable:
  142. exposed.append(name)
  143. check_warn(f"{name} is in WAL mode on a cross-VM filesystem (virtiofs/9p, {size})",
  144. "(WAL can silently corrupt across the VM boundary; stop every Hermes process and run "
  145. f"`hermes sessions set-journal-mode delete{'' if name == 'state.db' else f' --db {path}'}`, then "
  146. "set `database.journal_mode: delete` — or move the database onto a native/named volume)")
  147. elif mode == "wal" and vulnerable:
  148. exposed.append(name)
  149. check_warn(f"{name} is in WAL mode ({size})", "(exposed to the WAL-reset bug until SQLite is upgraded)")
  150. elif mode == "wal":
  151. check_info(f"{name}: WAL journal mode ({size})")
  152. else:
  153. check_info(f"{name}: rollback journal mode ({size}{', not exposed' if vulnerable else ''})")
  154. if exposed:
  155. check_info(f"To clear the exposure: {_wal_reset_repair_hint()}")
  156. def _check_s6_supervision(issues: list[str]) -> None:
  157. """Under our s6 /init, report static services and the ONE host gateway slot; no-op elsewhere.
  158. Counterpart to :func:`_check_gateway_service_linger` (systemd-on-host)."""
  159. try:
  160. from hermes_cli.service_manager import (
  161. S6_STATIC_SCANDIR, S6ServiceManager, detect_service_manager, s6_service_up)
  162. except Exception:
  163. return
  164. if detect_service_manager() != "s6":
  165. return
  166. _section("s6 Supervision")
  167. mgr = S6ServiceManager()
  168. for static in ("main-hermes", "dashboard"): # s6-rc symlinks in the root scandir, not the gateway one
  169. up = s6_service_up(S6_STATIC_SCANDIR / static)
  170. (check_ok if up else check_info)(f"{static}: up" if up else f"{static}: down (expected if not enabled via env)")
  171. _report_host_gateway_slot(mgr, issues)
  172. def _report_host_gateway_slot(mgr, issues: list[str]) -> None:
  173. """Multiplex-only: ONE gateway process serves N profiles, so report THAT process and its
  174. roster. The old ``Per-profile gateways: up/total`` line described a topology we no longer
  175. run — it counted supervision slots and never said which profiles were actually served."""
  176. from gateway.host_topology import host_gateway_topology
  177. slots = sorted(mgr.list_profile_gateways())
  178. topology = host_gateway_topology()
  179. if topology is None:
  180. if not slots:
  181. return check_info("No gateway registered yet — run `hermes gateway install`")
  182. up = [p for p in slots if mgr.is_running(f"gateway-{p}")]
  183. issues.append("No host gateway owns the gateway role — start the ONE host multiplexer: "
  184. "hermes --profile default gateway start")
  185. return check_warn(f"No host gateway owns the gateway role ({len(up)}/{len(slots)} supervision "
  186. f"slots up: {', '.join(slots)})", "(nothing is serving these profiles)")
  187. check_ok(f"Host gateway: {topology.describe()}")
  188. legacy_up = sorted(p for p in slots if p != "default" and mgr.is_running(f"gateway-{p}"))
  189. if legacy_up:
  190. check_warn(f"LEGACY per-profile gateway slots still supervised: {', '.join(legacy_up)}",
  191. "(multiplex-only: the host gateway already serves every profile from one process)")
  192. issues.append("Fold the legacy per-profile gateways into the host gateway: "
  193. "hermes --profile default gateway migrate --multiplex")
  194. def check_certificates(should_fix: bool = False, issues: list | None = None) -> None:
  195. """Verify the actual TLS policy is usable before the first HTTPS call tracebacks.
  196. The policy is ``agent.ssl_verify``: the platform verifier (truststore) is
  197. installed process-wide and every stack builds SSL contexts through it. There
  198. is no certifi bundle to validate anymore; the check is that the platform
  199. store is in force and a default context constructs.
  200. """
  201. try:
  202. from agent.ssl_verify import install_truststore
  203. except Exception as e:
  204. return check_warn("TLS trust check skipped", str(e))
  205. if issues is None:
  206. issues = []
  207. platform_store = install_truststore()
  208. if not platform_store:
  209. check_warn("TLS platform trust store unavailable",
  210. "OpenSSL default trust paths are in use; certificates trusted only by the OS store (a corporate root) will not verify")
  211. try:
  212. ssl.create_default_context()
  213. except Exception as e:
  214. _fail_and_issue("TLS default SSL context cannot be constructed", str(e),
  215. _python_repair_hint() + "; if TLS still fails, repair Python through the installation owner.", issues)
  216. return
  217. if platform_store:
  218. check_ok("TLS platform trust store configured; default SSL context available")
  219. else:
  220. check_ok("TLS default SSL context available (OpenSSL trust paths)")
  221. def _check_gateway_service_linger(issues: list[str]) -> None:
  222. """Warn when a systemd user gateway service will stop after logout (skipped under s6: no linger concept).
  223. Multiplex-only: the HOST gateway runs under the default profile's unit, so a doctor run from a
  224. SERVED profile must still check it — gating on the active profile's own unit silently skipped
  225. the check for every profile that does not own a service of its own.
  226. """
  227. try:
  228. from hermes_cli.gateway import (
  229. _SERVICE_BASE, get_systemd_linger_status, get_systemd_unit_path, is_linux,
  230. user_systemd_unit_dir)
  231. from hermes_cli.service_manager import detect_service_manager
  232. except Exception as e:
  233. return check_warn("Gateway service linger", f"(could not import gateway helpers: {e})")
  234. if not is_linux() or detect_service_manager() == "s6":
  235. return
  236. host_unit = user_systemd_unit_dir() / f"{_SERVICE_BASE}.service"
  237. if not (get_systemd_unit_path().exists() or host_unit.exists()):
  238. return
  239. _section("Gateway Service")
  240. linger_enabled, linger_detail = get_systemd_linger_status()
  241. if linger_enabled is None:
  242. return check_warn("Could not verify systemd linger", f"({linger_detail})")
  243. if not check_bool(linger_enabled, ("Systemd linger enabled", "(gateway service survives logout)"),
  244. ("Systemd linger disabled", "(gateway may stop after logout)")):
  245. check_info("Run: sudo loginctl enable-linger $USER")
  246. issues.append("Enable linger for the gateway user service: sudo loginctl enable-linger $USER")
  247. _TCC_CDHASH_DETAIL = (
  248. "the desktop bundle's designated requirement is cdhash-pinned (pre-#73681 build) — rebuilds invalidate "
  249. "all permission grants. Run `hermes update` to get the stable identifier-pinned signing identity, "
  250. "then re-grant permissions once.")
  251. _TCC_STABLE_DETAIL = {
  252. True: "(certificate-anchored DR; grants survive rebuilds)",
  253. False: "(identifier-pinned DR; grants survive rebuilds — for the strongest anchor, see `hermes desktop --setup-tcc-identity`)",
  254. }
  255. def check_macos_tcc_grants() -> None:
  256. """Check macOS TCC grant persistence for a locally-built desktop bundle; silent on non-macOS / no bundle.
  257. TCC keys grants to the app's designated requirement (DR). A cdhash-pinned ad-hoc DR changes on every
  258. rebuild, so grants silently stop matching while the Settings toggle stays ON; identifier-pinned builds
  259. survive rebuilds, but grants made to older binaries stay stale until re-granted once. TCC.db needs Full
  260. Disk Access, so the DR string is the only readable signal (a proxy for the signing class, not DR wording).
  261. See #86385.
  262. """
  263. app = _desktop_app_bundle() if sys.platform == "darwin" else None
  264. if app is None:
  265. return
  266. dr = _macos_desktop_dr(app)
  267. if not dr:
  268. return check_warn("macOS TCC grant check", "(could not read code-signing requirement of the desktop bundle)")
  269. if "cdhash" in dr.lower():
  270. return check_warn("macOS TCC grants will reset after every update", _TCC_CDHASH_DETAIL)
  271. # --setup-tcc-identity or notarized build (certificate-anchored) is the strongest anchor.
  272. check_ok("macOS TCC signing identity is stable", _TCC_STABLE_DETAIL["certificate" in dr.lower()])
  273. check_info("If macOS still re-prompts for permissions (toggle shows ON): the stored grant is stale — run "
  274. "`tccutil reset ScreenCapture com.nousresearch.hermes` (repeat per affected service), toggle it ON in "
  275. "System Settings, then fully quit & relaunch Hermes once.")
  276. def _desktop_app_bundle() -> Path | None:
  277. """Locate the locally-built desktop bundle (``apps/desktop/release/mac-<arch>/Hermes.app``), newest first.
  278. The only layout whose ad-hoc re-signed bundle can invalidate TCC grants. ``/Applications/Hermes.app`` is
  279. deliberately not probed: it is the separately-signed, certificate-anchored Hermes-Setup launcher.
  280. """
  281. release_dir = Path(__file__).resolve().parents[1] / "apps" / "desktop" / "release"
  282. candidates = [p for p in release_dir.glob("mac*/Hermes.app") if p.is_dir()]
  283. return max(candidates, key=lambda p: p.stat().st_mtime) if candidates else None
  284. def _macos_desktop_dr(app: Path) -> str | None:
  285. """Return the bundle's designated requirement string, or None on failure (a hanging codesign must never abort doctor)."""
  286. codesign = shutil.which("codesign")
  287. try:
  288. proc = subprocess.run([codesign, "-d", "--requirements", "-", str(app)], capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=15, check=False) if codesign else None
  289. except (FileNotFoundError, subprocess.TimeoutExpired):
  290. return None
  291. return None if proc is None or proc.returncode != 0 else (proc.stdout or "") + (proc.stderr or "")
  292. def check_macos_tcc_anchor(should_fix: bool = False) -> None:
  293. """Report (and with --fix install) the dylib-complete TCC anchor; silent on non-macOS / non-uv interpreters.
  294. Never raises. Install is gated by the module's pre-install boot probe, so ``--fix`` cannot brick the CLI.
  295. See #95596.
  296. """
  297. with warn_on_error("macOS TCC anchor check failed"):
  298. from hermes_cli import macos_tcc_anchor as tcc
  299. status, detail = tcc.tcc_anchor_state()
  300. if status == "skip":
  301. return
  302. if status == "active":
  303. return check_ok("macOS TCC anchor active", f"({detail})")
  304. anchored = tcc.ensure_tcc_anchor() if should_fix else None
  305. if anchored is not None:
  306. return check_ok("macOS TCC anchor installed", f"({anchored})")
  307. check_warn("macOS TCC anchor missing" if status == "missing" else "macOS TCC anchor stale", f"({detail})")
  308. def check_macos_full_disk_access() -> None:
  309. """One-grant guidance: Full Disk Access silences every per-folder TCC prompt. Silent on non-macOS.
  310. Probe: listdir of ``~/Library/Application Support/com.apple.TCC`` — FDA-gated, and probing it does NOT
  311. trigger a prompt (the TCC dir just returns EPERM). A missing dir / other error is indeterminate: stay silent.
  312. macOS TCC prompts per-category (Desktop, then Downloads, then Documents, ...), so first-run agents
  313. drip-feed permission dialogs as they touch each folder. ONE Full Disk Access grant covers all of them,
  314. permanently — and with the stable signing identities now in place (#73681/#95091/#95131), it survives
  315. updates too. This check probes whether the terminal context already has FDA and, when it doesn't, prints
  316. the exact one-switch setup with the System Settings deep link.
  317. """
  318. if sys.platform != "darwin":
  319. return
  320. try:
  321. os.listdir(Path.home() / "Library" / "Application Support" / "com.apple.TCC")
  322. except PermissionError:
  323. check_info("One switch silences all macOS folder prompts: grant your terminal app Full Disk Access and Hermes "
  324. "will never trip per-folder dialogs (Desktop/Downloads/Documents/...) again. Open: System Settings → "
  325. "Privacy & Security → Full Disk Access — or run:\n"
  326. " open \"x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles\"\n"
  327. " then enable your terminal (and Hermes.app if you use Desktop), and restart them once. "
  328. "With Hermes' stable signing identities the grant survives every update.")
  329. except OSError:
  330. pass # missing dir / other error: indeterminate, stay silent
  331. else:
  332. check_ok("macOS Full Disk Access granted", "(no per-folder permission prompts will occur)")
  333. @doctor_check("Security advisory check failed: {e}")
  334. def _check_security_advisories(should_fix: bool, f: Finding) -> None:
  335. """Compromised-package advisories, funnelled into manual issues; a bug here must never block the rest of doctor."""
  336. from hermes_cli.security_advisories import detect_compromised, filter_unacked, full_remediation_text, get_acked_ids
  337. all_hits = detect_compromised()
  338. fresh_hits = filter_unacked(all_hits)
  339. if not fresh_hits:
  340. return check_ok("No active security advisories")
  341. for hit in fresh_hits:
  342. # Fail row + remediation text indented under it as one section; also into the summary action list.
  343. _fail_and_issue(f"{hit.advisory.title}", f"({hit.package}=={hit.installed_version})",
  344. f"Resolve security advisory {hit.advisory.id}: uninstall {hit.package}=={hit.installed_version} "
  345. f"and rotate credentials, then run `hermes doctor --ack {hit.advisory.id}`.", f.manual_issues)
  346. for line in full_remediation_text(hit):
  347. print(f" {color(line, Colors.YELLOW)}" if line else "")
  348. acked_ids = get_acked_ids() # acked-but-still-installed stays visible
  349. for h in all_hits:
  350. if h.advisory.id in acked_ids:
  351. check_warn(f"{h.package}=={h.installed_version} still installed (advisory {h.advisory.id} acknowledged)")
  352. def _staged_venv_dir() -> Path | None:
  353. """pm's provisioned runtime venv, or None when nothing is staged.
  354. ``pm.packages.Venv().venv_dir()`` is pm's public authority for where
  355. the runtime venv lives, including an external selected generation or
  356. the original source/payload environment before first sync. A resolved
  357. path without a venv marker is not a provisioned venv — pm also returns
  358. the intended location before first sync, and
  359. doctor must not read an empty directory as staged dependencies.
  360. """
  361. try:
  362. import pm
  363. from pm.packages import Venv
  364. venv_dir = Venv().venv_dir()
  365. except Exception:
  366. return None
  367. if venv_dir is not None and (Path(venv_dir) / "pyvenv.cfg").is_file():
  368. return Path(venv_dir)
  369. return None
  370. @doctor_check()
  371. def _check_python_environment(should_fix: bool, f: Finding) -> None:
  372. """Interpreter, linked SQLite, venv, macOS TCC anchors/FDA/grants, version-file drift."""
  373. v, label = sys.version_info, f"Python {'.'.join(map(str, sys.version_info[:3]))}"
  374. if v < (3, 8):
  375. _fail_and_issue(label, "(3.10+ required)", "Upgrade Python to 3.10+", f.issues)
  376. elif check_bool(v >= (3, 10), label, (label, "(3.10+ recommended)")) and v < (3, 11):
  377. check_warn("Python 3.11+ recommended for RL Training tools (tinker requires >= 3.11)")
  378. # Linked SQLite: version + source id matter independently of the Python minor (uv's
  379. # python-build-standalone can keep a vulnerable SQLite across upgrades).
  380. with warn_on_error("SQLite version probe failed: {e}", ""):
  381. import sqlite3
  382. from hermes_state_wal import is_sqlite_wal_reset_vulnerable, sqlite_source_id
  383. src = sqlite_source_id()
  384. # Warn-only: Hermes already refuses WAL on fresh DBs and runtime repair is best-effort.
  385. check_bool(not is_sqlite_wal_reset_vulnerable(), f"SQLite {sqlite3.sqlite_version}",
  386. (f"SQLite {sqlite3.sqlite_version} (WAL-reset bug)", _sqlite_upgrade_hint()))
  387. if src:
  388. check_info(f"SQLite source id: {(src[:48] + '…') if len(src) > 48 else src}")
  389. _report_database_journal_modes()
  390. # PM launchers run base Python with the selected dependency tree on
  391. # sys.path. Neither sys.prefix nor a stale PYTHONPATH proves activation.
  392. staged = _staged_venv_dir()
  393. if staged is not None:
  394. from pm.environments import site_packages
  395. selected_site = site_packages(staged).resolve()
  396. running_here = selected_site.is_dir() and any(Path(entry).resolve() == selected_site for entry in sys.path)
  397. check_ok(f"Runtime venv staged ({staged})",
  398. "(active in this process)" if running_here else "(this process runs outside it)")
  399. else:
  400. check_bool(sys.prefix != sys.base_prefix, "Virtual environment active",
  401. ("Not in virtual environment", "(recommended)"))
  402. # macOS TCC interpreter anchor (#95596): dylib-complete re-land of the mechanism reverted in #95563.
  403. # Silent on non-macOS.
  404. check_macos_tcc_anchor(should_fix=should_fix)
  405. # macOS Full Disk Access (issue #52010 follow-up): one grant silences every per-folder prompt
  406. # permanently. Silent on non-macOS.
  407. check_macos_full_disk_access()
  408. # macOS TCC grant persistence (issue #86385): a locally-built desktop bundle whose DR is cdhash-pinned
  409. # loses every permission grant on each rebuild; a post-#73681 identifier-pinned DR survives, but grants
  410. # made to older binaries stay stale (toggle shows ON while macOS re-prompts).
  411. check_macos_tcc_grants()
  412. @doctor_check()
  413. def _check_certificates(should_fix: bool, f: Finding) -> None:
  414. check_certificates(should_fix=should_fix, issues=f.manual_issues)
  415. # (import name, display name, optional)
  416. _PACKAGES = (
  417. ("openai", "OpenAI SDK", False), ("rich", "Rich (terminal UI)", False), ("dotenv", "python-dotenv", False),
  418. ("ruamel.yaml", "ruamel.yaml", False), ("httpx", "HTTPX", False),
  419. ("croniter", "Croniter (cron expressions)", True), ("telegram", "python-telegram-bot", True), ("discord", "discord.py", True),
  420. )
  421. @doctor_check()
  422. def _check_required_packages(should_fix: bool, f: Finding) -> None:
  423. for module, name, optional in _PACKAGES:
  424. try:
  425. __import__(module)
  426. check_ok(name, "(optional)" if optional else "")
  427. except ImportError:
  428. if optional:
  429. check_warn(name, "(optional, not installed)")
  430. else:
  431. _fail_and_issue(name, "(missing)", f"Repair {name}: {_python_repair_hint()}", f.issues)
  432. def _check_windows_gateway_autostart(should_fix: bool, f: Finding) -> None:
  433. """Windows: the gateway must start at logon from ONE mechanism — a Scheduled Task and a
  434. Startup-folder entry side by side launch it twice (#80569)."""
  435. if sys.platform != "win32":
  436. return
  437. from hermes_cli import gateway_windows
  438. redundant = gateway_windows.redundant_autostart_entries()
  439. if not redundant:
  440. return
  441. _section("Windows Gateway Autostart")
  442. if not should_fix:
  443. for path in redundant:
  444. check_warn("Redundant gateway login item", f"({path})")
  445. f.issues.append("Remove duplicate Windows gateway autostart entries: hermes doctor --fix")
  446. return
  447. done, warnings = gateway_windows.reconcile_autostart_launchers()
  448. for message in done:
  449. check_ok(message)
  450. for message in warnings:
  451. check_warn(message)
  452. if done and not warnings:
  453. f.fixed += 1
  454. if warnings:
  455. f.manual_issues.extend(warnings)
  456. @doctor_check()
  457. def _check_web_dashboard_import(should_fix: bool, f: Finding) -> None:
  458. """Import the dashboard web surface in a subprocess so an import-time crash lands in the report.
  459. When starlette is updated past the fastapi pinned beside it (the CVE starlette pin ships in
  460. several extras on its own), ``hermes dashboard`` dies constructing ``FastAPI(...)`` with a
  461. TypeError — not an ImportError — so the module's own lazy-install fallback never fires and the
  462. process exits before a single log line. Importing in a subprocess keeps a dead web surface
  463. from taking the doctor down with it; lazy installs stay off so the probe never mutates the
  464. environment it is diagnosing.
  465. """
  466. from hermes_cli.doctor import PROJECT_ROOT
  467. env = dict(os.environ, HERMES_DISABLE_LAZY_INSTALLS="1")
  468. try:
  469. proc = subprocess.run(
  470. [sys.executable, "-c", "import hermes_cli.web_server"],
  471. capture_output=True,
  472. text=True,
  473. encoding="utf-8",
  474. errors="replace",
  475. timeout=120,
  476. cwd=str(PROJECT_ROOT),
  477. env=env,
  478. check=False,
  479. )
  480. except subprocess.TimeoutExpired:
  481. _fail_and_issue(
  482. "Dashboard web surface",
  483. "(import probe timed out)",
  484. "Repair the dashboard dependencies: `hermes pm repair`, then restart Hermes",
  485. f.issues,
  486. )
  487. return
  488. stderr = (proc.stderr or "").strip()
  489. if proc.returncode == 0:
  490. return check_ok("Dashboard web surface", "(imports cleanly)")
  491. if "Web UI requires fastapi and uvicorn" in stderr:
  492. # The optional web extra is simply absent; anyone who never opens the dashboard
  493. # should not be told their install is broken.
  494. return check_warn("Dashboard web surface", "(optional web extra not installed)")
  495. detail = (
  496. stderr.splitlines()[-1] if stderr else f"(exited with code {proc.returncode})"
  497. )
  498. _fail_and_issue(
  499. "Dashboard web surface",
  500. detail,
  501. "Repair the dashboard dependencies: `hermes pm repair`, then restart Hermes",
  502. f.issues,
  503. )
  504. @doctor_check()
  505. def _check_gateway_supervision(should_fix: bool, f: Finding) -> None:
  506. _check_gateway_service_linger(f.issues)
  507. _check_s6_supervision(f.issues)
  508. _check_windows_gateway_autostart(should_fix, f)
  509. @doctor_check()
  510. def _check_command_installation(should_fix: bool, f: Finding) -> None:
  511. """Check the install-owned launch contract without replacing custom commands."""
  512. from hermes_cli.doctor import PROJECT_ROOT
  513. if sys.platform == "win32":
  514. return
  515. _section("Command Installation")
  516. from hermes_cli.config import detect_install_method
  517. method = detect_install_method(PROJECT_ROOT)
  518. if is_nix_install_method(method) or method in ("docker", "apt"):
  519. command = shutil.which("hermes")
  520. if command:
  521. check_ok(f"Hermes command managed by {method} ({command})")
  522. else:
  523. check_warn(f"Hermes command not on PATH ({method}-managed)")
  524. f.manual_issues.append(_python_repair_hint())
  525. return
  526. from hermes_cli._launchers import resolve_store_python
  527. from pm.environments import base_venv, selected_venv
  528. try:
  529. selected = selected_venv(PROJECT_ROOT)
  530. except (OSError, ValueError, RuntimeError) as exc:
  531. check_fail("Cannot resolve selected dependencies", str(exc))
  532. return f.manual_issues.append(_python_repair_hint())
  533. pm_launcher = selected != base_venv(PROJECT_ROOT) or resolve_store_python(PROJECT_ROOT) is not None
  534. venv_bin = PROJECT_ROOT / "hermes" if pm_launcher else selected / "bin" / "hermes"
  535. if not venv_bin.is_file():
  536. check_warn("Hermes entry point not found", f"({venv_bin})")
  537. return f.manual_issues.append("Repair or reinstall the Hermes launcher through the installation owner")
  538. check_ok(f"Hermes entry point exists ({venv_bin})")
  539. # Expected command link directory (mirrors install.sh logic).
  540. prefix = os.environ.get("PREFIX", "")
  541. termux = prefix and (os.environ.get("TERMUX_VERSION") or "com.termux/files/usr" in prefix)
  542. link_dir, display = (Path(prefix) / "bin", "$PREFIX/bin") if termux else (Path.home() / ".local" / "bin", "~/.local/bin")
  543. link = link_dir / "hermes"
  544. if link.is_symlink():
  545. target, expected = link.resolve(), venv_bin.resolve()
  546. if target == expected:
  547. return check_ok(f"{display}/hermes → correct target")
  548. check_warn(f"{display}/hermes points to wrong target", f"(→ {target}, expected → {expected})")
  549. owned_targets = {(PROJECT_ROOT / name / "bin" / "hermes").resolve() for name in ("venv", ".venv")}
  550. if target not in owned_targets:
  551. return f.manual_issues.append(f"Review {display}/hermes manually; its target is user-managed and was not changed")
  552. if not should_fix:
  553. return f.issues.append(f"Broken symlink at {display}/hermes — run 'hermes doctor --fix'")
  554. verb = "Fixed"
  555. elif link.exists(): # regular file (wrapper script), not a symlink
  556. return check_ok(f"{display}/hermes exists (non-symlink)")
  557. else:
  558. check_fail(f"{display}/hermes not found", "(hermes command may not work outside the venv)")
  559. if not should_fix:
  560. return f.issues.append(f"Missing {display}/hermes symlink — run 'hermes doctor --fix'")
  561. link_dir.mkdir(parents=True, exist_ok=True)
  562. verb = "Created"
  563. if pm_launcher:
  564. from hermes_cli._launchers import stage_launcher
  565. if stage_launcher("hermes", PROJECT_ROOT, link_dir) is None:
  566. check_fail("Could not publish Hermes launcher")
  567. return f.manual_issues.append("Repair the PM store interpreter through the installation owner, then rerun 'hermes doctor --fix'")
  568. check_ok(f"{verb} PM launcher: {display}/hermes")
  569. else:
  570. if link.is_symlink():
  571. link.unlink()
  572. link.symlink_to(venv_bin)
  573. check_ok(f"{verb} symlink: {display}/hermes → {venv_bin}")
  574. f.fixed += 1
  575. if verb == "Created" and str(link_dir) not in os.environ.get("PATH", "").split(os.pathsep):
  576. check_warn(f"{display} is not on your PATH", "(add it to your shell config: export PATH=\"$HOME/.local/bin:$PATH\")")
  577. f.manual_issues.append(f"Add {display} to your PATH")