Merge pull request 'feat(gui): Run Diagnostic flow on the Games page — 0.12.0' (#7) from feat/m6-steam-detection into main

Reviewed-on: #7

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to RigDoctor are recorded here. Format follows
 (`MAJOR.MINOR.PATCH`, pre-1.0). `__version__` and `pyproject.toml` must match the git
 release tag (so the auto-updater, D18, can compare versions).
 
+## [0.12.0] - 2026-05-22
+### Added
+- **Guided diagnostic in the GUI.** Each game on the **Games** page now has a **Run Diagnostic**
+  button → a focused, game-tagged capture starts and a recording banner appears (live sample
+  count, GPU-lost indicator) with **Finish & analyze** / **Discard**. Finishing opens a results
+  dialog: the window-scoped capture summary (peak temps/power, events, last samples) plus the
+  health findings as cards. The banner persists/restores if you navigate away and back while a
+  capture is running. Shares `core/diagnostic.py` with the CLI (one flow, three front-ends).
+
+## [0.11.0] - 2026-05-22
+### Added
+- **Guided diagnostic session (CLI) — the seed use case, end to end.** `rigdoctor diagnose
+  start --game "<name>"` runs a **focused crash-capture tagged with that game** (its own
+  diagnostic log, so the report is scoped to just that session), `diagnose status` shows
+  progress, and `diagnose finish` stops it and prints a combined report: the **capture
+  summary** (peak temps/power, GPU-lost events, last samples — M3) plus the **health findings**
+  (Xid/SMART/driver/etc. — M4). The game can be given by `--game` or `--appid` (resolved from
+  the Steam scan), and is recorded as a log event so it survives a crash + reboot.
+- Shared orchestration lives in `core/diagnostic.py` (one callable for CLI/GUI/tray, per
+  ARCHITECTURE §7.1); the recorder/`record run` gained an optional `--game` tag.
+
 ## [0.10.2] - 2026-05-22
 ### Changed
 - When an Environment **Apply**/**Install** fails, the status now shows the **real reason**

docs/ROADMAP.md

@@ -40,8 +40,13 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).
 - [ ] M10 desktop GUI (PySide6: dashboard, log browser, report viewer, logger controls)
 - [ ] M11 tray / menu-bar applet (QSystemTrayIcon: live M1 readouts + Run Diagnostic +
       supporting actions — D13)
-- [ ] Guided diagnostic session (pick game → focused M3 capture → M4 scan → findings),
-      shared by tray/GUI/CLI
+- [~] Guided diagnostic session (pick game → focused M3 capture → M4 scan → findings),
+      shared by tray/GUI/CLI — *core + CLI + GUI done* (`core/diagnostic.py`, `rigdoctor
+      diagnose start/status/finish`, and a **Run Diagnostic** button per game on the GUI Games
+      page → recording banner → results dialog with the capture summary + findings). Tags a
+      focused capture with the chosen game (own diagnostic log, window-scoped report) and
+      combines the capture summary with the M4 findings. *Pending:* the tray (M11) entry point,
+      and auto start/stop via the D12 wrapper/watcher.
 - [ ] Logger trigger modes: always-on + game-launch (D12 — wrapper first:
       `rigdoctor wrap %command%` + global Steam compat-tool; zero-config watcher
       (Steam RunningAppID + /proc) and GameMode hook follow)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rigdoctor"
-version = "0.10.2"
+version = "0.12.0"
 description = "Modular hardware monitoring & crash diagnostics for Linux gamers."
 readme = "README.md"
 requires-python = ">=3.11"

src/rigdoctor/__init__.py

@@ -1,3 +1,3 @@
 """RigDoctor — modular hardware monitoring & crash diagnostics for Linux gamers."""
 
-__version__ = "0.10.2"
+__version__ = "0.12.0"

src/rigdoctor/cli.py

@@ -86,6 +86,7 @@ def cmd_record_run(args) -> int:
         max_bytes=cfg["log_max_bytes"],
         backups=cfg["log_backups"],
         status_path=config.STATUS_FILE,
+        game=getattr(args, "game", None),
     )
 
     def _handle(_sig, _frame):
@@ -345,6 +346,77 @@ def cmd_report(args) -> int:
     return 0
 
 
+def _resolve_game(args) -> str | None:
+    """Game name from --game, or looked up from --appid via the Steam scan."""
+    if getattr(args, "game", None):
+        return args.game
+    if getattr(args, "appid", None):
+        from .core import steam
+
+        for g in steam.scan_games(steam.selected_library_paths()):
+            if g.appid == str(args.appid):
+                return g.name
+        return None
+    return None
+
+
+def cmd_diagnose(args) -> int:
+    from .core import diagnostic, reccontrol, steam
+
+    sub = args.diagnose_cmd or "status"
+
+    if sub == "start":
+        if reccontrol.running_pid():
+            print("A capture is already running — finish it with: rigdoctor diagnose finish")
+            return 1
+        game = _resolve_game(args)
+        if game is None and (args.game or args.appid):
+            print("Couldn't match that game in your selected Steam libraries.")
+            return 1
+        if game is None:
+            games = steam.cached_games() or steam.scan_games(steam.selected_library_paths())
+            if games:
+                print("Pick a game to focus on, then re-run with --game:")
+                for g in games:
+                    print(f"  --game {g.name!r}")
+            else:
+                print("No games detected. Select a library: rigdoctor games libraries --all")
+            return 1
+        pid = diagnostic.start(game=game, interval=args.interval)
+        time.sleep(1.0)
+        if pid and reccontrol.pid_alive(pid):
+            print(f"Diagnostic capture started for {game!r} (pid {pid}).")
+            print("  Play your game. When you're done (or after a crash + reboot):")
+            print("    rigdoctor diagnose finish")
+            return 0
+        print(f"Capture failed to start; see {config.SPAWN_LOG}")
+        return 1
+
+    if sub == "status":
+        status = diagnostic.active()
+        if not status:
+            print("No diagnostic capture is running.")
+            return 0
+        game = status.get("game") or "—"
+        print(f"Capturing for {game!r}: {status.get('samples', 0)} samples"
+              + (" · GPU-lost seen" if status.get("gpu_lost") else ""))
+        return 0
+
+    # finish
+    if not reccontrol.running_pid() and not config.DIAG_LOG.exists():
+        print("No diagnostic to analyze. Start one with: rigdoctor diagnose start --game <name>")
+        return 1
+    print("Stopping capture and analyzing…\n")
+    result = diagnostic.finish(last_n=args.last)
+    from .render import render_health, render_summary
+
+    if result.game:
+        print(f"Diagnostic — {result.game}\n")
+    print(render_summary(result.summary, log_path=config.DIAG_LOG))
+    print("\n" + render_health(result.findings, title="Findings"))
+    return 0
+
+
 def cmd_gameenv(args) -> int:
     from dataclasses import asdict
 
@@ -470,6 +542,7 @@ def build_parser() -> argparse.ArgumentParser:
     run_p = rec_sub.add_parser("run", help="run the capture loop in the foreground (systemd-friendly)")
     run_p.add_argument("-n", "--interval", type=float, default=None, help="sampling interval (s)")
     run_p.add_argument("-o", "--out", default=None, help="log file path")
+    run_p.add_argument("--game", default=None, help="tag the capture with a game name (M6/diagnose)")
     run_p.set_defaults(func=cmd_record_run)
 
     start_p = rec_sub.add_parser("start", help="start recording in the background")
@@ -519,6 +592,19 @@ def build_parser() -> argparse.ArgumentParser:
     env_p = sub.add_parser("gameenv", help="gaming environment checks (M6): flag stability/perf settings")
     env_p.add_argument("--json", action="store_true", help="output JSON instead of text")
     env_p.set_defaults(func=cmd_gameenv)
+
+    diag_p = sub.add_parser("diagnose", help="guided diagnostic: capture while gaming, then analyze")
+    diag_sub = diag_p.add_subparsers(dest="diagnose_cmd")
+    diag_start = diag_sub.add_parser("start", help="start a focused capture for a game")
+    diag_start.add_argument("--game", default=None, help="game name to focus on")
+    diag_start.add_argument("--appid", default=None, help="Steam appid to focus on (resolved to a name)")
+    diag_start.add_argument("-n", "--interval", type=float, default=None, help="sampling interval (s)")
+    diag_start.set_defaults(func=cmd_diagnose)
+    diag_sub.add_parser("status", help="show the in-progress diagnostic").set_defaults(func=cmd_diagnose)
+    diag_finish = diag_sub.add_parser("finish", help="stop the capture and analyze it")
+    diag_finish.add_argument("--last", type=int, default=10, help="recent samples to show")
+    diag_finish.set_defaults(func=cmd_diagnose)
+    diag_p.set_defaults(func=cmd_diagnose, diagnose_cmd=None, last=10)
     return p
 
 

src/rigdoctor/config.py

@@ -23,6 +23,9 @@ CONFIG_FILE = CONFIG_DIR / "config.toml"
 
 # Crash-capture logger (M3)
 LOG_FILE = LOG_DIR / "capture.jsonl"
+# Guided diagnostic (M6/D12): a focused capture writes here, separate from the always-on
+# crash log, so its report covers only that session's window.
+DIAG_LOG = LOG_DIR / "diagnostic.jsonl"
 STATUS_FILE = STATE_DIR / "recorder.json"
 PID_FILE = STATE_DIR / "recorder.pid"
 SPAWN_LOG = STATE_DIR / "recorder.out"

src/rigdoctor/core/diagnostic.py

@@ -0,0 +1,84 @@
+"""Guided diagnostic session (SPEC §4 / ARCHITECTURE §7.1): orchestrate M3 + M4.
+
+The seed use case, one flow: **pick a game** → **focused crash-capture** scoped to that
+session (M3, tagged with the game) → on **finish**, **scan & analyze** (M4 health report)
+over the captured window + system logs → return a prioritized result. This is not a new
+module — it's a single shared callable so the CLI, GUI, and tray run the identical flow.
+
+The capture is **manually bracketed** (start/finish) for now; auto start/stop on game launch
+(the D12 wrapper/watcher) plugs in here later without changing the result shape.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from .. import config
+from . import reccontrol
+from .crashlog import Summary, summarize
+from .health import Finding
+
+
+@dataclass
+class DiagnosticResult:
+    game: str | None
+    summary: Summary           # capture window: peak temps/power, events, last samples (M3)
+    findings: list[Finding]    # health findings: Xid/SMART/driver/etc. (M4)
+
+
+def _clear_diag_log() -> None:
+    """Each diagnostic is a fresh focused capture — drop any previous session + segments."""
+    base = config.DIAG_LOG
+    for p in [base, *base.parent.glob(base.name + ".*")]:
+        try:
+            p.unlink()
+        except OSError:
+            pass
+
+
+def start(game: str | None = None, interval: float | None = None) -> int | None:
+    """Begin a focused capture, tagged with the game, into the dedicated diagnostic log.
+    Returns the pid, or None if a capture is already running."""
+    if reccontrol.running_pid():
+        return None
+    _clear_diag_log()
+    return reccontrol.start_background(interval=interval, out=str(config.DIAG_LOG), game=game)
+
+
+def is_running() -> bool:
+    return reccontrol.running_pid() is not None
+
+
+def active() -> dict | None:
+    """Status of the in-progress session (running flag, game, samples), or None if idle."""
+    if not is_running():
+        return None
+    return reccontrol.read_status()
+
+
+def _await_stopped(timeout: float = 6.0) -> None:
+    deadline = time.monotonic() + timeout
+    while reccontrol.running_pid() and time.monotonic() < deadline:
+        time.sleep(0.1)
+
+
+def _game_from_summary(summary: Summary) -> str | None:
+    """Recover the focused game from the log's 'game' event (survives a crash + reboot)."""
+    for _ts, kind, detail in reversed(summary.events):
+        if kind == "game" and detail:
+            return detail
+    return None
+
+
+def finish(last_n: int = 10, log_path=None) -> DiagnosticResult:
+    """Stop the capture (if running), summarize the window, and run the health report."""
+    from .health import run_health_checks
+
+    reccontrol.stop_background()
+    _await_stopped()
+    path = log_path or config.DIAG_LOG
+    summary = summarize(path, last_n=last_n)
+    game = _game_from_summary(summary) or (reccontrol.read_status() or {}).get("game")
+    findings = run_health_checks()
+    return DiagnosticResult(game=game, summary=summary, findings=findings)

src/rigdoctor/core/reccontrol.py

@@ -38,7 +38,9 @@ def read_status() -> dict | None:
         return None
 
 
-def start_background(interval: float | None = None, out: str | None = None) -> int | None:
+def start_background(
+    interval: float | None = None, out: str | None = None, game: str | None = None
+) -> int | None:
     """Spawn a detached `record run`. Returns the child pid, or None if already running."""
     if running_pid():
         return None
@@ -48,6 +50,8 @@ def start_background(interval: float | None = None, out: str | None = None) -> i
         cmd += ["--interval", str(interval)]
     if out:
         cmd += ["--out", out]
+    if game:
+        cmd += ["--game", game]
     out_fh = open(config.SPAWN_LOG, "a")
     proc = subprocess.Popen(
         cmd,

src/rigdoctor/core/recorder.py

@@ -27,12 +27,14 @@ class Recorder:
         backups: int = 10,
         status_path=None,
         sampler: Sampler | None = None,
+        game: str | None = None,
     ) -> None:
         self.interval = interval
         self.sampler = sampler or Sampler(available_sources())
         self.writer = CrashLogWriter(log_path, max_bytes, backups)
         self.log_path = Path(log_path)
         self.status_path = Path(status_path) if status_path else None
+        self.game = game or None
         self.samples = 0
         self._stop = threading.Event()
         self._gpu_lost = False
@@ -43,6 +45,8 @@ class Recorder:
 
     def run(self) -> None:
         self.writer.write_event("session-start", f"interval={self.interval:g}s")
+        if self.game:
+            self.writer.write_event("game", self.game)  # tag the focused-diagnostic target
         self._write_status(running=True)
         try:
             while not self._stop.is_set():
@@ -81,6 +85,7 @@ class Recorder:
             "samples": self.samples,
             "updated": time.time(),
             "gpu_lost": self._gpu_lost,
+            "game": self.game,
         }
         if sample is not None:
             data["latest"] = headline(sample)

src/rigdoctor/gui/diagnostic_dialog.py

@@ -0,0 +1,81 @@
+"""Results view for a guided diagnostic session (M6/D12): capture summary + findings."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QFont
+from PySide6.QtWidgets import (
+    QDialog,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QScrollArea,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..render import render_summary
+from .widgets import finding_card
+
+
+class DiagnosticDialog(QDialog):
+    def __init__(self, result, parent=None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle(f"Diagnostic — {result.game}" if result.game else "Diagnostic")
+        self.resize(660, 680)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 16)
+        root.setSpacing(14)
+
+        title = QLabel(f"Diagnostic — {result.game}" if result.game else "Diagnostic")
+        title.setObjectName("PageTitle")
+        root.addWidget(title)
+
+        scroll = QScrollArea()
+        scroll.setWidgetResizable(True)
+        scroll.setFrameShape(QFrame.Shape.NoFrame)
+        scroll.setStyleSheet("background: transparent;")
+        body = QWidget()
+        col = QVBoxLayout(body)
+        col.setContentsMargins(0, 0, 0, 0)
+        col.setSpacing(10)
+        col.setAlignment(Qt.AlignmentFlag.AlignTop)
+
+        # Capture window summary (peaks / events / last samples) — monospace for the columns.
+        cap_head = QLabel("Capture")
+        cap_head.setStyleSheet("font-weight: 700; background: transparent;")
+        col.addWidget(cap_head)
+        summary = QLabel(render_summary(result.summary))
+        summary.setObjectName("Report")
+        summary.setFont(QFont("monospace"))
+        summary.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        summary.setWordWrap(False)
+        summary.setStyleSheet(
+            "background: #0d0f13; color: #cfd3da; border: 1px solid #2a2f39; "
+            "border-radius: 8px; padding: 10px;"
+        )
+        col.addWidget(summary)
+
+        find_head = QLabel(f"Findings ({len(result.findings)})")
+        find_head.setStyleSheet("font-weight: 700; background: transparent;")
+        col.addWidget(find_head)
+        if result.findings:
+            for finding in result.findings:
+                col.addWidget(finding_card(finding))
+        else:
+            none = QLabel("No findings.")
+            none.setObjectName("Muted")
+            col.addWidget(none)
+
+        scroll.setWidget(body)
+        root.addWidget(scroll, 1)
+
+        buttons = QHBoxLayout()
+        buttons.addStretch(1)
+        close = QPushButton("Close")
+        close.setObjectName("PrimaryButton")
+        close.clicked.connect(self.accept)
+        buttons.addWidget(close)
+        root.addLayout(buttons)

src/rigdoctor/gui/games_page.py

@@ -17,6 +17,7 @@ from PySide6.QtWidgets import (
     QFrame,
     QHBoxLayout,
     QLabel,
+    QMessageBox,
     QPushButton,
     QScrollArea,
     QVBoxLayout,
@@ -24,10 +25,11 @@ from PySide6.QtWidgets import (
 )
 
 from ..config import load_config, update_config
+from .diagnostic_dialog import DiagnosticDialog
 from .theme import ACCENT, GOOD, MUTED
 
 
-def _game_row(name: str, sublabel: str, size: str, is_new: bool) -> QFrame:
+def _game_row(name: str, sublabel: str, size: str, is_new: bool, on_diagnose=None) -> QFrame:
     card = QFrame()
     card.setObjectName("Card")
     h = QHBoxLayout(card)
@@ -59,6 +61,13 @@ def _game_row(name: str, sublabel: str, size: str, is_new: bool) -> QFrame:
     size_label.setMinimumWidth(80)
     size_label.setAlignment(Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter)
     h.addWidget(size_label, 0)
+
+    if on_diagnose is not None:
+        diag_btn = QPushButton("Run Diagnostic")
+        diag_btn.setObjectName("ActionButton")
+        diag_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        diag_btn.clicked.connect(lambda: on_diagnose(name))
+        h.addWidget(diag_btn, 0)
     return card
 
 
@@ -66,14 +75,17 @@ class GamesPage(QWidget):
     _libraries_ready = Signal(object)  # list[dict(path, label, count, selected)]
     _scanned = Signal(object)          # steam.ScanResult
     new_count_changed = Signal(int)    # newly-installed game count (for the nav badge)
+    _diag_done = Signal(object)        # DiagnosticResult — focused capture analyzed
 
     def __init__(self) -> None:
         super().__init__()
         self.setObjectName("Page")
         self._libraries_ready.connect(self._render_libraries)
         self._scanned.connect(self._render_games)
+        self._diag_done.connect(self._on_diag_done)
         self._busy = False
         self._new_appids: set[str] = set()
+        self._diag_game: str | None = None
 
         root = QVBoxLayout(self)
         root.setContentsMargins(20, 18, 20, 18)
@@ -93,6 +105,30 @@ class GamesPage(QWidget):
         header.addWidget(self._rescan_btn)
         root.addLayout(header)
 
+        # In-progress diagnostic banner (hidden until a focused capture is running).
+        self._banner = QFrame()
+        self._banner.setObjectName("Card")
+        self._banner.setStyleSheet(f"#Card {{ border: 1px solid {ACCENT}; }}")
+        banner_h = QHBoxLayout(self._banner)
+        banner_h.setContentsMargins(16, 10, 16, 10)
+        banner_h.setSpacing(10)
+        self._banner_label = QLabel("")
+        self._banner_label.setStyleSheet(f"color: {ACCENT}; font-weight: 700; background: transparent;")
+        banner_h.addWidget(self._banner_label, 1)
+        self._finish_btn = QPushButton("Finish & analyze")
+        self._finish_btn.setObjectName("ActionButton")
+        self._finish_btn.clicked.connect(self._finish_diagnostic)
+        banner_h.addWidget(self._finish_btn)
+        self._discard_btn = QPushButton("Discard")
+        self._discard_btn.clicked.connect(self._discard_diagnostic)
+        banner_h.addWidget(self._discard_btn)
+        self._banner.hide()
+        root.addWidget(self._banner)
+
+        self._diag_timer = QTimer(self)
+        self._diag_timer.setInterval(1000)
+        self._diag_timer.timeout.connect(self._poll_diag)
+
         # Libraries (opt-in checkboxes)
         lib_card = QFrame()
         lib_card.setObjectName("Card")
@@ -233,9 +269,74 @@ class GamesPage(QWidget):
                 os.path.basename(g.library.rstrip("/")) or g.library,
                 steam.human_size(g.size_bytes),
                 g.appid in new_appids,
+                on_diagnose=self._start_diagnostic,
             ))
         self._list.addStretch(1)
 
+    # --- guided diagnostic (M6/D12) ---------------------------------------------------
+
+    def _start_diagnostic(self, name: str) -> None:
+        from ..core import diagnostic
+
+        if diagnostic.is_running():
+            QMessageBox.information(
+                self, "RigDoctor",
+                "A capture is already running — finish or discard it first.")
+            return
+        if diagnostic.start(game=name) is None:
+            QMessageBox.warning(self, "RigDoctor", "Couldn't start the capture.")
+            return
+        self._diag_game = name
+        self._banner_label.setText(f"● Recording — {name} · starting…")
+        self._finish_btn.setEnabled(True)
+        self._discard_btn.setEnabled(True)
+        self._banner.show()
+        self._diag_timer.start()
+
+    def _poll_diag(self) -> None:
+        from ..core import diagnostic
+
+        status = diagnostic.active()
+        if not status:
+            self._diag_timer.stop()  # recorder exited on its own
+            return
+        samples = status.get("samples", 0)
+        lost = "  · GPU-lost seen" if status.get("gpu_lost") else ""
+        game = status.get("game") or self._diag_game or ""
+        self._banner_label.setText(f"● Recording — {game} · {samples} samples{lost}")
+
+    def _finish_diagnostic(self) -> None:
+        self._diag_timer.stop()
+        self._finish_btn.setEnabled(False)
+        self._discard_btn.setEnabled(False)
+        self._banner_label.setText("Analyzing… (running the health report)")
+        threading.Thread(target=self._work_finish, daemon=True).start()
+
+    def _work_finish(self) -> None:
+        from ..core import diagnostic
+
+        try:
+            result = diagnostic.finish()
+        except Exception:
+            result = None
+        self._diag_done.emit(result)
+
+    def _on_diag_done(self, result) -> None:
+        self._banner.hide()
+        self._finish_btn.setEnabled(True)
+        self._discard_btn.setEnabled(True)
+        if result is None:
+            QMessageBox.warning(self, "RigDoctor", "The diagnostic couldn't be analyzed.")
+            return
+        DiagnosticDialog(result, self).exec()
+
+    def _discard_diagnostic(self) -> None:
+        from ..core import reccontrol
+
+        self._diag_timer.stop()
+        reccontrol.stop_background()
+        self._banner.hide()
+
     # --- nav badge integration --------------------------------------------------------
 
     def showEvent(self, event) -> None:  # noqa: N802 (Qt override)
@@ -247,3 +348,13 @@ class GamesPage(QWidget):
 
             threading.Thread(target=steam.acknowledge_new, daemon=True).start()
             self.new_count_changed.emit(0)
+
+        # Reflect a capture that's still running (e.g. started earlier, navigated back).
+        from ..core import diagnostic
+
+        if diagnostic.is_running():
+            status = diagnostic.active() or {}
+            self._diag_game = status.get("game") or self._diag_game
+            self._banner.show()
+            if not self._diag_timer.isActive():
+                self._diag_timer.start()

tests/test_diagnostic.py

@@ -0,0 +1,61 @@
+"""Tests for the guided diagnostic orchestration (M3+M4 glue)."""
+
+import tempfile
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from rigdoctor.core import diagnostic
+from rigdoctor.core.crashlog import CrashLogWriter, summarize
+from rigdoctor.core.health import Finding
+from rigdoctor.core.sample import Reading, Sample
+
+
+def _write_log(path: str, game: str) -> None:
+    w = CrashLogWriter(path)
+    w.write_event("session-start", "interval=1s")
+    w.write_event("game", game)
+    for temp in (60.0, 72.0, 81.0):
+        w.write_sample(Sample(ts=time.time(), readings=[Reading("gpu", "temp", temp, "°C", "")]))
+    w.write_event("gpu-lost", "nvidia-smi query timed out")
+    w.close()
+
+
+class GameRecoveryTests(unittest.TestCase):
+    def test_game_recovered_from_log_event(self):
+        with tempfile.TemporaryDirectory() as d:
+            log = str(Path(d) / "capture.jsonl")
+            _write_log(log, "Path of Exile 2")
+            summary = summarize(log)
+            self.assertEqual(diagnostic._game_from_summary(summary), "Path of Exile 2")
+
+    def test_no_game_event_returns_none(self):
+        with tempfile.TemporaryDirectory() as d:
+            log = str(Path(d) / "capture.jsonl")
+            w = CrashLogWriter(log)
+            w.write_event("session-start")
+            w.close()
+            self.assertIsNone(diagnostic._game_from_summary(summarize(log)))
+
+
+class FinishTests(unittest.TestCase):
+    def test_finish_combines_summary_and_findings(self):
+        with tempfile.TemporaryDirectory() as d:
+            log = Path(d) / "capture.jsonl"
+            _write_log(str(log), "Satisfactory")
+            fake = [Finding("warning", "GPU", "NVIDIA Xid 79 ×1", "fell off the bus")]
+            with mock.patch("rigdoctor.core.health.run_health_checks", return_value=fake), \
+                 mock.patch.object(diagnostic.reccontrol, "stop_background", return_value=False), \
+                 mock.patch.object(diagnostic.reccontrol, "running_pid", return_value=None):
+                result = diagnostic.finish(log_path=log)
+            self.assertEqual(result.game, "Satisfactory")
+            self.assertEqual(result.summary.samples, 3)
+            self.assertEqual(result.findings, fake)
+            # peak GPU temp captured in the window, GPU-lost event recorded
+            self.assertEqual(result.summary.maxima["gpu.temp"][0], 81.0)
+            self.assertTrue(any(kind == "gpu-lost" for _ts, kind, _d in result.summary.events))
+
+
+if __name__ == "__main__":
+    unittest.main()