fix(share): terminal scrollback for large output

Render with pyte.HistoryScreen and show scrollback + screen, so large output
(ls -la, cat, etc.) can be scrolled up to read. Auto-scroll to the bottom only
when already at the bottom; preserve position when the user has scrolled up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -5,6 +5,55 @@ 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.7.3] - 2026-05-21
+### Fixed
+- Shared terminal now has **scrollback** — large output (e.g. `ls -la`) can be scrolled up to
+  read; it keeps a history buffer and only auto-scrolls to the bottom when you're already there.
+
+## [0.7.2] - 2026-05-21
+### Changed
+- Removed the GUI **Inventory** tab — use the CLI `rigdoctor inventory` instead. (Inventory is
+  still collected for the relay guest view, so a remote helper still sees the host's hardware.)
+### Fixed
+- Shared terminal caret now sits at the real cursor position (row **and** column) instead of
+  the start of the line.
+
+## [0.7.1] - 2026-05-21
+### Fixed
+- Shared terminal: a guest who joined **after** the host enabled the terminal stayed read-only.
+  The host now re-sends the terminal state when a guest joins, so the terminal is available.
+- Inventory page no longer jumps back to the top when it refreshes (e.g. when elevated data
+  arrives) — scroll position is preserved and unchanged data isn't re-rendered.
+- Shared terminal now follows the cursor to the bottom as output arrives (e.g. `ls -la`),
+  instead of staying scrolled up.
+
+## [0.7.0] - 2026-05-21
+### Added
+- **Shared terminal (M12, Tier 3)**: when the host enables it, the session shares a real **PTY**
+  shell — the guest gets an interactive terminal (vim, top, tab-completion, Ctrl-C) running on
+  the host as the host's user. The host **reads along** live and can type too, e.g. a `sudo`
+  password — which stays local and is never sent to the guest. Off by default, host-consented.
+  The guest also pulls the host's inventory on join.
+### Fixed
+- **Input contrast**: all form controls (text fields, spin boxes, combo boxes, terminals) now
+  use the dark theme with readable text (Fusion defaulted them to light-on-light).
+
+## [0.6.0] - 2026-05-21
+### Added
+- **Session sharing over the relay (M12)**: a **Share** tab — *Start shared session* (host)
+  hands you a short code and streams a read-only live view; *Enter share code* (guest) joins
+  someone else's session and views their sensors/health/inventory. Both connect outbound over
+  WebSocket to the relay (`relay_url`, default `wss://rigdoctor.jesseyvanofferen.com`), gated
+  by your Gitea access token — no port forwarding. Read-only.
+
+## [0.5.0] - 2026-05-21
+### Added
+- **Session sharing (M12, Tier 2)**: `rigdoctor share serve` starts a **read-only** live view
+  (sensors auto-refresh + health report + inventory) over a local HTTP server, gated by a
+  random share token. Bind to localhost for local testing, or to all interfaces behind a
+  user-chosen tunnel (Tailscale/cloudflared/SSH) for remote help. No actions, no terminal.
+  (Tier 1 export and Tier 3 gated terminal still to come — D16.)
+
 ## [0.4.1] - 2026-05-21
 ### Fixed
 - Checkbox contrast: a checked checkbox is now a clear accent-filled box with a checkmark

docs/MODULES.md

@@ -18,7 +18,7 @@ Status: ⬜ not started · 🟦 designing · 🟨 in progress · ✅ done
 | M10 | Desktop GUI | Desktop UI | **python3-pyside6** | all | P2 | 🟨 |
 | M11 | Tray / menu-bar applet | Desktop UI | **python3-pyside6** (+ AppIndicator on GNOME) | all | P2 | ⬜ |
 | M9 | Installer | (meta) | none | all | P1 | 🟨 |
-| M12 | Session sharing / remote assist | Sharing | none (Tier 3: tmate/sshx) | all | P3 | ⬜ |
+| M12 | Session sharing / remote assist | Sharing | none (Tier 3: tmate/sshx) | all | P3 | 🟨 |
 | M13 | Auto-update | (core) | none (stdlib; user-local file swap) | all | P3 | 🟨 |
 | ~~M7~~ | ~~Stress / repro~~ | — | — | — | — | ❌ dropped (D7) |
 

docs/ROADMAP.md

@@ -58,10 +58,10 @@ Ubuntu + NVIDIA first; `.deb` distribution (see `DECISIONS.md`).
 Escalating ladder, built in order:
 - [ ] Tier 1: `share export` — diagnostic bundle (inventory + recent log + report); B opens
       it in RigDoctor. One-way, safest.
-- [ ] Tier 2: live read-only view (local server + user-chosen tunnel: Tailscale/cloudflared/
-      SSH; no hosted relay), token-gated, A approves, revocable.
-- [ ] Tier 3: gated interactive terminal (wrap tmate/sshx; read-only default, read-write on
-      explicit consent), with session audit log.
+- [x] Tier 2: live read-only view — `rigdoctor share serve` (stdlib HTTP, token-gated:
+      sensors + health + inventory). Remote = user-chosen tunnel; GUI controls still to add.
+- [x] Tier 3: host-consented interactive terminal — a real PTY shell shared over the relay
+      (own `pty`, pyte-rendered guest), off by default; host reads along + can type (sudo).
 
 > **Out of scope:** stress/repro module (D7); multi-distro support and packaging beyond
 > Ubuntu/apt + `.deb` (D15) — a thin seam is kept but not built out.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rigdoctor"
-version = "0.4.1"
+version = "0.7.3"
 description = "Modular hardware monitoring & crash diagnostics for Linux gamers."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -13,7 +13,7 @@ requires-python = ">=3.11"
 dependencies = []
 
 [project.optional-dependencies]
-gui = ["PySide6"]
+gui = ["PySide6", "pyte"]
 
 [project.scripts]
 rigdoctor = "rigdoctor.cli:main"

src/rigdoctor/__init__.py

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

src/rigdoctor/cli.py

@@ -295,6 +295,12 @@ def cmd_uninstall(args) -> int:
     return 0
 
 
+def cmd_share_serve(args) -> int:
+    from .core import share
+
+    return share.serve(host=args.host, port=args.port)
+
+
 def cmd_collect_priv(args) -> int:
     """Internal: emit root-only data (SMART + dmidecode) as JSON, run via pkexec at launch."""
     from dataclasses import asdict
@@ -405,6 +411,13 @@ def build_parser() -> argparse.ArgumentParser:
     cp = sub.add_parser("collect-priv", help=argparse.SUPPRESS)  # internal: run via pkexec
     cp.set_defaults(func=cmd_collect_priv)
 
+    share_p = sub.add_parser("share", help="session sharing (M12)")
+    share_sub = share_p.add_subparsers(dest="share_cmd", required=True)
+    serve_p = share_sub.add_parser("serve", help="serve a read-only live view (token-gated)")
+    serve_p.add_argument("--host", default="127.0.0.1", help="bind address (use 0.0.0.0 + a tunnel for remote)")
+    serve_p.add_argument("--port", type=int, default=8765, help="port")
+    serve_p.set_defaults(func=cmd_share_serve)
+
     inv = sub.add_parser("inventory", help="system inventory (M5): export hardware/OS details")
     inv.add_argument("--json", action="store_true", help="output JSON")
     inv.add_argument("--markdown", action="store_true", help="output Markdown (for forum/bug reports)")

src/rigdoctor/config.py

@@ -142,6 +142,7 @@ DEFAULTS: dict = {
     "alerts_enabled": True,       # desktop notifications on overheat / GPU-lost / new version
     "gpu_temp_alert": 90.0,       # °C — alert when GPU reaches this
     "cpu_temp_alert": 95.0,       # °C — alert when CPU reaches this
+    "relay_url": "wss://rigdoctor.jesseyvanofferen.com",  # session-sharing relay (M12)
 }
 
 

src/rigdoctor/core/pty_session.py

@@ -0,0 +1,59 @@
+"""A pseudo-terminal running the host's shell (M12, Tier 3 — host side).
+
+Spawns the user's login shell in a real PTY so interactive programs work over a shared
+session: vim, top, tab-completion, colours, Ctrl-C, and `sudo` (which prompts inside the
+PTY — the host types that password locally, so it's never sent to the guest). Runs as the
+host's own user — never elevated. Linux-only (uses `pty`/`termios`).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import pty
+import signal
+import struct
+import termios
+
+
+class PtySession:
+    def __init__(self, rows: int = 24, cols: int = 80):
+        self.pid, self.master_fd = pty.fork()
+        if self.pid == 0:  # child: become the shell
+            os.environ["TERM"] = "xterm-256color"
+            shell = os.environ.get("SHELL", "/bin/bash")
+            try:
+                os.execvp(shell, [shell])
+            finally:
+                os._exit(1)
+        os.set_blocking(self.master_fd, False)
+        self.set_size(rows, cols)
+
+    def set_size(self, rows: int, cols: int) -> None:
+        try:
+            fcntl.ioctl(self.master_fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+        except OSError:
+            pass
+
+    def write(self, data: bytes) -> None:
+        try:
+            os.write(self.master_fd, data)
+        except OSError:
+            pass
+
+    def read(self, size: int = 65536) -> bytes:
+        try:
+            return os.read(self.master_fd, size)
+        except (BlockingIOError, OSError):
+            return b""
+
+    def close(self) -> None:
+        try:
+            os.close(self.master_fd)
+        except OSError:
+            pass
+        try:
+            os.kill(self.pid, signal.SIGHUP)
+            os.waitpid(self.pid, os.WNOHANG)
+        except (OSError, ChildProcessError, ProcessLookupError):
+            pass

src/rigdoctor/core/share.py

@@ -0,0 +1,194 @@
+"""Session sharing (M12, Tier 2): a read-only live view over a local HTTP server.
+
+Serves the live sensor snapshot + health report + inventory, **read-only**, gated by a
+random share token. Bind to localhost for local testing, or to all interfaces behind a
+user-chosen tunnel (Tailscale / cloudflared / SSH) for remote help. No actions, no terminal.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import asdict
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from .sampler import Sampler
+from .sources import available_sources
+
+_PAGE = """<!doctype html>
+<html><head><meta charset="utf-8"><title>RigDoctor — shared</title>
+<style>
+ body{background:#101216;color:#e6e8eb;font-family:system-ui,sans-serif;margin:0;padding:24px}
+ h1{font-size:20px;margin:0 0 4px} h2{font-size:14px;color:#8b929c;margin:18px 0 6px}
+ .card{background:#1b1f26;border:1px solid #2a2f39;border-radius:12px;padding:16px;margin:14px 0}
+ table{width:100%;border-collapse:collapse} td{padding:3px 0;font-size:14px}
+ td.v{text-align:right;font-weight:600} .muted{color:#8b929c}
+ .critical{color:#f87171} .warning{color:#fb923c} .ok{color:#4ade80} .info{color:#8b929c}
+ .badge{display:inline-block;background:#38bdf8;color:#06222e;border-radius:6px;padding:1px 8px;font-size:12px;font-weight:700}
+</style></head><body>
+ <h1>RigDoctor <span class="badge">read-only share</span></h1>
+ <p class="muted">A live view shared by the machine's owner. You can look, not change anything.</p>
+ <div class="card"><div id="live">loading…</div></div>
+ <div class="card"><h2 style="margin-top:0">Health</h2><div id="health">loading…</div></div>
+ <div class="card"><h2 style="margin-top:0">Inventory</h2><div id="inv">loading…</div></div>
+<script>
+ const T=new URLSearchParams(location.search).get('t');
+ const j=async p=>(await fetch(p+'?t='+encodeURIComponent(T))).json();
+ const fmt=(v,u)=>v==null?'N/A':(u==='\\u00b0C'?(+v).toFixed(1)+' °C':(u?v+' '+u:v));
+ async function live(){try{const d=await j('/api/snapshot');let h='';
+  for(const[g,items]of Object.entries(d.groups)){h+='<h2>'+g.toUpperCase()+'</h2><table>';
+   for(const it of items)h+='<tr><td class="muted">'+it.name+'</td><td class="v">'+fmt(it.value,it.unit)+'</td></tr>';
+   h+='</table>';}document.getElementById('live').innerHTML=h;}catch(e){}}
+ async function once(){try{const r=await j('/api/report');
+   document.getElementById('health').innerHTML=r.map(f=>'<div><span class="'+f.severity+'">['+f.severity.toUpperCase()+']</span> '+f.category+': '+f.title+'</div>').join('')||'no findings';}catch(e){}
+  try{const inv=await j('/api/inventory');let h='';
+   for(const[s,kv]of Object.entries(inv)){h+='<h2>'+s+'</h2><table>';
+    for(const[k,v]of Object.entries(kv))h+='<tr><td class="muted">'+k+'</td><td class="v">'+v+'</td></tr>';
+    h+='</table>';}document.getElementById('inv').innerHTML=h;}catch(e){}}
+ live();once();setInterval(live,2000);
+</script></body></html>"""
+
+
+def _snapshot(sampler: Sampler) -> dict:
+    sample = sampler.sample()
+    groups: dict[str, list] = {}
+    for r in sample.readings:
+        if r.metric == "name":
+            item = {"name": "device", "value": r.label, "unit": ""}
+        else:
+            item = {"name": (r.label + " " + r.metric).strip() if r.label else r.metric,
+                    "value": r.value, "unit": r.unit}
+        groups.setdefault(r.source, []).append(item)
+    return {"ts": sample.ts, "groups": groups}
+
+
+def _report() -> list:
+    from .health import run_health_checks
+    return [asdict(f) for f in run_health_checks()]
+
+
+def _inventory() -> dict:
+    from .inventory import collect, to_dict
+    return to_dict(collect())
+
+
+# --- Relay (M12) frames: a host streams these; a guest renders them. -----------------
+
+def host_full_frame(sampler: Sampler) -> str:
+    """Initial frame: live snapshot + health report + inventory."""
+    return json.dumps({"type": "full", "snapshot": _snapshot(sampler),
+                       "report": _report(), "inventory": _inventory()})
+
+
+def host_snapshot_frame(sampler: Sampler) -> str:
+    """Recurring frame: just the live snapshot."""
+    return json.dumps({"type": "snapshot", "snapshot": _snapshot(sampler)})
+
+
+def _fmt(value, unit: str) -> str:
+    if value is None:
+        return "N/A"
+    if unit == "°C":
+        try:
+            return f"{float(value):.1f} °C"
+        except (TypeError, ValueError):
+            return str(value)
+    return f"{value} {unit}".strip()
+
+
+def guest_html(snapshot: dict | None, report: list | None, inventory: dict | None) -> str:
+    """Render a received frame as read-only dark HTML for the guest's view."""
+    import html as _html
+
+    def esc(x) -> str:
+        return _html.escape(str(x))
+
+    out = ['<div style="font-family:sans-serif;color:#e6e8eb">']
+    if snapshot:
+        for group, items in snapshot.get("groups", {}).items():
+            out.append(f'<h3 style="color:#8b929c">{esc(group).upper()}</h3><table width="100%">')
+            for it in items:
+                out.append(f'<tr><td style="color:#8b929c">{esc(it.get("name"))}</td>'
+                           f'<td align="right"><b>{esc(_fmt(it.get("value"), it.get("unit", "")))}</b></td></tr>')
+            out.append("</table>")
+    if report:
+        out.append('<h3 style="color:#8b929c">HEALTH</h3>')
+        colors = {"critical": "#f87171", "warning": "#fb923c", "ok": "#4ade80"}
+        for f in report:
+            sev = f.get("severity", "info")
+            out.append(f'<div><span style="color:{colors.get(sev, "#8b929c")}">[{esc(sev).upper()}]</span> '
+                       f'{esc(f.get("category"))}: {esc(f.get("title"))}</div>')
+    if inventory:
+        out.append('<h3 style="color:#8b929c">INVENTORY</h3>')
+        for section, kv in inventory.items():
+            out.append(f'<h4 style="margin:6px 0;color:#8b929c">{esc(section)}</h4><table width="100%">')
+            for k, v in kv.items():
+                out.append(f'<tr><td style="color:#8b929c">{esc(k)}</td><td align="right"><b>{esc(v)}</b></td></tr>')
+            out.append("</table>")
+    out.append("</div>")
+    return "".join(out)
+
+
+class _Handler(BaseHTTPRequestHandler):
+    def log_message(self, *args):  # quiet
+        pass
+
+    def _authed(self, query: dict) -> bool:
+        return secrets.compare_digest(query.get("t", [""])[0], self.server.token)
+
+    def _send(self, code: int, ctype: str, body: bytes) -> None:
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if not self._authed(parse_qs(parsed.query)):
+            self._send(403, "text/plain", b"Forbidden: missing or invalid share token")
+            return
+        if parsed.path == "/":
+            self._send(200, "text/html; charset=utf-8", _PAGE.encode())
+        elif parsed.path == "/api/snapshot":
+            self._send(200, "application/json", json.dumps(_snapshot(self.server.sampler)).encode())
+        elif parsed.path == "/api/report":
+            self._send(200, "application/json", json.dumps(_report()).encode())
+        elif parsed.path == "/api/inventory":
+            self._send(200, "application/json", json.dumps(_inventory()).encode())
+        else:
+            self._send(404, "text/plain", b"Not found")
+
+
+class _Server(ThreadingHTTPServer):
+    daemon_threads = True
+
+    def __init__(self, addr, token: str):
+        super().__init__(addr, _Handler)
+        self.token = token
+        self.sampler = Sampler(available_sources())
+
+
+def make_server(host: str = "127.0.0.1", port: int = 0, token: str | None = None) -> tuple[_Server, str]:
+    token = token or secrets.token_urlsafe(16)
+    return _Server((host, port), token), token
+
+
+def serve(host: str = "127.0.0.1", port: int = 8765) -> int:
+    srv, token = make_server(host, port)
+    url = f"http://{host}:{srv.server_address[1]}/?t={token}"
+    print(
+        f"Sharing a read-only live view at:\n  {url}\n\n"
+        "Anyone with this URL (and network access to this host) can VIEW your sensors,\n"
+        "health report, and inventory — read-only. For remote help, expose it via a tunnel\n"
+        "(Tailscale / cloudflared / `ssh -R`). Press Ctrl-C to stop sharing.",
+        flush=True,
+    )
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopped sharing.")
+    finally:
+        srv.shutdown()
+    return 0

src/rigdoctor/gui/inventory_page.py

@@ -1,145 +0,0 @@
-"""Inventory page (M5 in the GUI): system inventory with copy/save + admin re-collect."""
-
-from __future__ import annotations
-
-import os
-import threading
-
-from PySide6.QtCore import Qt, QTimer, Signal
-from PySide6.QtWidgets import (
-    QApplication,
-    QFileDialog,
-    QFrame,
-    QGridLayout,
-    QHBoxLayout,
-    QLabel,
-    QPushButton,
-    QScrollArea,
-    QVBoxLayout,
-    QWidget,
-)
-
-from ..core import inventory
-from .theme import MUTED
-
-
-def _section_card(section) -> QFrame:
-    card = QFrame()
-    card.setObjectName("Card")
-    layout = QVBoxLayout(card)
-    layout.setContentsMargins(16, 12, 16, 12)
-    layout.setSpacing(6)
-    title = QLabel(section.title)
-    title.setStyleSheet("font-weight: 700; background: transparent;")
-    layout.addWidget(title)
-    grid = QGridLayout()
-    grid.setColumnStretch(1, 1)
-    grid.setHorizontalSpacing(14)
-    grid.setVerticalSpacing(4)
-    for row, (key, value) in enumerate(section.items):
-        k = QLabel(key)
-        k.setObjectName("Muted")
-        v = QLabel(value)
-        v.setWordWrap(True)
-        v.setStyleSheet("background: transparent;")
-        grid.addWidget(k, row, 0)
-        grid.addWidget(v, row, 1)
-    layout.addLayout(grid)
-    return card
-
-
-class InventoryPage(QWidget):
-    _result = Signal(object)  # list[Section]
-
-    def __init__(self) -> None:
-        super().__init__()
-        self.setObjectName("Page")
-        self._sections: list = []
-        self._result.connect(self._render)
-
-        root = QVBoxLayout(self)
-        root.setContentsMargins(20, 18, 20, 18)
-        root.setSpacing(16)
-
-        header = QHBoxLayout()
-        title = QLabel("Inventory")
-        title.setObjectName("PageTitle")
-        header.addWidget(title)
-        header.addStretch(1)
-        self._status = QLabel("")
-        self._status.setObjectName("Muted")
-        header.addWidget(self._status)
-        self._copy_btn = QPushButton("Copy Markdown")
-        self._copy_btn.clicked.connect(self._copy)
-        header.addWidget(self._copy_btn)
-        self._save_btn = QPushButton("Save…")
-        self._save_btn.clicked.connect(self._save)
-        header.addWidget(self._save_btn)
-        self._refresh_btn = QPushButton("Refresh")
-        self._refresh_btn.setObjectName("PrimaryButton")
-        self._refresh_btn.clicked.connect(self._run)
-        header.addWidget(self._refresh_btn)
-        root.addLayout(header)
-
-        scroll = QScrollArea()
-        scroll.setWidgetResizable(True)
-        scroll.setFrameShape(QFrame.Shape.NoFrame)
-        scroll.setStyleSheet("background: transparent;")
-        self._container = QWidget()
-        self._list = QVBoxLayout(self._container)
-        self._list.setContentsMargins(0, 0, 0, 0)
-        self._list.setSpacing(12)
-        self._list.setAlignment(Qt.AlignmentFlag.AlignTop)
-        scroll.setWidget(self._container)
-        root.addWidget(scroll, 1)
-
-        QTimer.singleShot(300, self._run)
-
-    def _run(self) -> None:
-        self._busy("Collecting…")
-        threading.Thread(target=self._work, daemon=True).start()
-
-    def _work(self) -> None:
-        try:
-            sections = inventory.collect()
-        except Exception:
-            sections = []
-        self._result.emit(sections)
-
-    def _busy(self, text: str) -> None:
-        self._status.setText(text)
-        for b in (self._refresh_btn, self._copy_btn, self._save_btn):
-            b.setEnabled(False)
-
-    def _render(self, sections) -> None:
-        self._refresh_btn.setEnabled(True)
-        self._copy_btn.setEnabled(True)
-        self._save_btn.setEnabled(True)
-        if sections is None:  # collection failed — keep current
-            self._status.setText("collection failed")
-            return
-
-        self._sections = sections
-        while self._list.count():
-            item = self._list.takeAt(0)
-            w = item.widget()
-            if w is not None:
-                w.deleteLater()
-        for section in sections:
-            self._list.addWidget(_section_card(section))
-        self._list.addStretch(1)
-        self._status.setText("")
-
-    def _copy(self) -> None:
-        if self._sections:
-            QApplication.clipboard().setText(inventory.render_markdown(self._sections))
-            self._status.setText("copied as Markdown")
-
-    def _save(self) -> None:
-        if not self._sections:
-            return
-        path, _ = QFileDialog.getSaveFileName(self, "Save inventory", "rigdoctor-inventory.md", "Markdown (*.md)")
-        if path:
-            with open(path, "w", encoding="utf-8") as f:
-                f.write(inventory.render_markdown(self._sections))
-            self._status.setText(f"saved {os.path.basename(path)}")

src/rigdoctor/gui/main_window.py

@@ -29,14 +29,14 @@ from ..config import load_config
 from ..core import alerts, elevation, updates
 from .dashboard import Dashboard
 from .health_page import HealthPage
-from .inventory_page import InventoryPage
 from .notifications_page import NotificationsPage
 from .recorder_page import RecorderPage
 from .setup_page import SetupPage
+from .share_page import SharePage
 from .theme import ACCENT, GOOD, MUTED
 from .worker import SamplerWorker
 
-_NAV_ITEMS = ["Dashboard", "Logs", "Health", "Setup", "Inventory", "Notifications"]
+_NAV_ITEMS = ["Dashboard", "Logs", "Health", "Setup", "Notifications", "Share"]
 
 
 class MainWindow(QMainWindow):
@@ -67,15 +67,15 @@ class MainWindow(QMainWindow):
         self.recorder_page = RecorderPage()
         self.health_page = HealthPage()
         self.setup_page = SetupPage()
-        self.inventory_page = InventoryPage()
         self.notifications_page = NotificationsPage()
         self.notifications_page.changed.connect(self._apply_alert_settings)
+        self.share_page = SharePage()
         self._stack.addWidget(self.dashboard)            # 0 Dashboard
         self._stack.addWidget(self.recorder_page)        # 1 Logs
         self._stack.addWidget(self.health_page)          # 2 Health
         self._stack.addWidget(self.setup_page)           # 3 Setup
-        self._stack.addWidget(self.inventory_page)       # 4 Inventory
-        self._stack.addWidget(self.notifications_page)   # 5 Notifications
+        self._stack.addWidget(self.notifications_page)   # 4 Notifications
+        self._stack.addWidget(self.share_page)           # 5 Share
         content_layout.addWidget(self._stack)
 
         layout.addWidget(self._build_sidebar())
@@ -225,9 +225,9 @@ class MainWindow(QMainWindow):
             self._elevated.emit()
 
     def _on_elevated(self) -> None:
-        # Re-run Health and Inventory now that root-only data (SMART/dmidecode) is available.
+        # Re-run Health now that root-only SMART data is available. (dmidecode is still
+        # collected and used by the relay guest view + the CLI `rigdoctor inventory`.)
         self.health_page._run()
-        self.inventory_page._run()
 
     def _apply_alert_settings(self) -> None:
         cfg = load_config()
@@ -306,4 +306,5 @@ class MainWindow(QMainWindow):
 
     def closeEvent(self, event) -> None:  # noqa: N802 (Qt override)
         self._worker.stop()
+        self.share_page.shutdown()
         super().closeEvent(event)

src/rigdoctor/gui/setup_page.py

@@ -86,8 +86,13 @@ class SetupPage(QWidget):
         comp_layout.addLayout(controls)
         root.addWidget(comp_card)
 
-        # Update access (M13): token gating updates to Gitea account holders.
-        upd_card, upd_layout = _panel("Update access")
+        # Account access (M13/M12): one Gitea token gates updates and session sharing.
+        upd_card, upd_layout = _panel("Account access")
+        hint = QLabel("A Gitea access token unlocks updates and session sharing. "
+                      "Create it with scopes <b>read:user</b> and <b>read:repository</b>.")
+        hint.setObjectName("Muted")
+        hint.setWordWrap(True)
+        upd_layout.addWidget(hint)
         self._upd_status = QLabel("")
         self._upd_status.setObjectName("Muted")
         self._upd_status.setWordWrap(True)
@@ -95,7 +100,7 @@ class SetupPage(QWidget):
         token_row = QHBoxLayout()
         self._token_input = QLineEdit()
         self._token_input.setEchoMode(QLineEdit.EchoMode.Password)
-        self._token_input.setPlaceholderText("Paste a Gitea token (scope: read:repository)")
+        self._token_input.setPlaceholderText("Paste a Gitea token (read:user + read:repository)")
         save_btn = QPushButton("Save token")
         save_btn.setObjectName("PrimaryButton")
         save_btn.clicked.connect(self._save_token)

src/rigdoctor/gui/share_page.py

@@ -0,0 +1,348 @@
+"""Share page (M12): host or join a shared session over the relay.
+
+Guest sees the host's live sensors + health + inventory (read-only). If the host enables it,
+a full **PTY terminal** is shared: the guest types and the commands run on the host (as the
+host's user), the host reads along, and the host can type too — e.g. a sudo password, which
+stays local and is never sent to the guest.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+
+from PySide6.QtCore import Qt, QSocketNotifier, QTimer, QUrl
+from PySide6.QtWebSockets import QWebSocket
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QTextEdit,
+    QVBoxLayout,
+    QWidget,
+)
+
+from ..config import load_config, load_token
+from ..core import share
+from ..core.pty_session import PtySession
+from ..core.sampler import Sampler
+from ..core.sources import available_sources
+from .terminal_widget import TerminalView
+
+
+def _relay_url() -> str:
+    return load_config().get("relay_url", "wss://rigdoctor.jesseyvanofferen.com").rstrip("/")
+
+
+def _b64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def _card(title: str) -> tuple[QFrame, QVBoxLayout]:
+    card = QFrame()
+    card.setObjectName("Card")
+    v = QVBoxLayout(card)
+    v.setContentsMargins(16, 14, 16, 14)
+    v.setSpacing(10)
+    head = QLabel(title)
+    head.setStyleSheet("font-weight: 700; background: transparent;")
+    v.addWidget(head)
+    return card, v
+
+
+class SharePage(QWidget):
+    def __init__(self) -> None:
+        super().__init__()
+        self.setObjectName("Page")
+        self._sampler = Sampler(available_sources())
+        self._host_ws: QWebSocket | None = None
+        self._guest_ws: QWebSocket | None = None
+        self._pty: PtySession | None = None
+        self._pty_notifier: QSocketNotifier | None = None
+        self._last_report = None
+        self._last_inv = None
+        self._timer = QTimer(self)
+        self._timer.setInterval(2000)
+        self._timer.timeout.connect(self._stream)
+
+        root = QVBoxLayout(self)
+        root.setContentsMargins(20, 18, 20, 18)
+        root.setSpacing(14)
+        title = QLabel("Share")
+        title.setObjectName("PageTitle")
+        root.addWidget(title)
+        root.addWidget(self._build_host())
+        root.addWidget(self._build_guest(), 1)
+
+    # ------------------------------------------------------------------ host
+    def _build_host(self) -> QFrame:
+        card, v = _card("Start a shared session")
+        self._host_status = QLabel("Let someone with an account view your machine, read-only.")
+        self._host_status.setObjectName("Muted")
+        self._host_status.setWordWrap(True)
+        v.addWidget(self._host_status)
+
+        row = QHBoxLayout()
+        self._start_btn = QPushButton("Start shared session")
+        self._start_btn.setObjectName("PrimaryButton")
+        self._start_btn.clicked.connect(self._start_host)
+        self._stop_btn = QPushButton("Stop")
+        self._stop_btn.setEnabled(False)
+        self._stop_btn.clicked.connect(self._stop_host)
+        self._code_label = QLabel("")
+        self._code_label.setStyleSheet("font-weight:700; font-size:18px; color:#38bdf8; background:transparent;")
+        self._code_label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        row.addWidget(self._start_btn)
+        row.addWidget(self._stop_btn)
+        row.addSpacing(12)
+        row.addWidget(self._code_label)
+        row.addStretch(1)
+        v.addLayout(row)
+
+        self._allow_term = QCheckBox("Allow remote terminal — the guest runs commands as your user (you read along; you can type too, e.g. a sudo password)")
+        self._allow_term.setStyleSheet("color:#fb923c; background:transparent;")
+        self._allow_term.toggled.connect(self._toggle_terminal)
+        v.addWidget(self._allow_term)
+
+        self._host_term = TerminalView()
+        self._host_term.keys.connect(lambda b: self._pty.write(b) if self._pty else None)
+        self._host_term.resized.connect(lambda r, c: self._pty.set_size(r, c) if self._pty else None)
+        self._host_term.setVisible(False)
+        v.addWidget(self._host_term)
+        return card
+
+    def _start_host(self) -> None:
+        if not load_token():
+            self._host_status.setText("Set a Gitea access token in Setup → Account access first.")
+            return
+        self._host_status.setText("Connecting to the relay…")
+        self._start_btn.setEnabled(False)
+        self._host_ws = QWebSocket()
+        self._host_ws.connected.connect(lambda: self._host_ws.sendTextMessage(json.dumps({"token": load_token()})))
+        self._host_ws.textMessageReceived.connect(self._host_msg)
+        self._host_ws.disconnected.connect(self._host_closed)
+        self._host_ws.errorOccurred.connect(lambda *_: self._host_status.setText(f"Relay error: {self._host_ws.errorString()}"))
+        self._host_ws.open(QUrl(_relay_url() + "/ws/host"))
+
+    def _host_msg(self, text: str) -> None:
+        try:
+            data = json.loads(text)
+        except ValueError:
+            return
+        if data.get("error"):
+            self._host_status.setText(f"Rejected: {data['error']}")
+            return
+        if "code" in data:  # relay handshake
+            self._code_label.setText(data["code"])
+            self._host_status.setText(f"Sharing as {data.get('user', '?')} — give this code to whoever should view your machine.")
+            self._stop_btn.setEnabled(True)
+            self._host_ws.sendTextMessage(share.host_full_frame(self._sampler))
+            self._send_terminal_state()
+            if self._allow_term.isChecked():
+                self._start_pty()
+            self._timer.start()
+            return
+        kind = data.get("type")  # frames forwarded from a guest
+        if kind == "req_full":
+            # A guest just joined — send a full frame AND the current terminal state, so a
+            # guest that joins *after* the host enabled the terminal still gets access.
+            self._host_ws.sendTextMessage(share.host_full_frame(self._sampler))
+            self._send_terminal_state()
+        elif kind == "pty_in" and self._pty:
+            self._pty.write(base64.b64decode(data["data"]))
+        elif kind == "pty_resize" and self._pty:
+            self._pty.set_size(int(data["rows"]), int(data["cols"]))
+
+    def _toggle_terminal(self, on: bool) -> None:
+        if on and self._host_ws and self._code_label.text():
+            self._start_pty()
+        elif not on:
+            self._stop_pty()
+        self._send_terminal_state()
+
+    def _send_terminal_state(self) -> None:
+        if self._host_ws and self._code_label.text():
+            self._host_ws.sendTextMessage(json.dumps({"type": "terminal", "enabled": self._allow_term.isChecked()}))
+
+    def _start_pty(self) -> None:
+        if self._pty:
+            return
+        rows, cols = self._host_term.grid()
+        self._pty = PtySession(rows=rows, cols=cols)
+        self._pty_notifier = QSocketNotifier(self._pty.master_fd, QSocketNotifier.Type.Read, self)
+        self._pty_notifier.activated.connect(self._on_pty_output)
+        self._host_term.reset()
+        self._host_term.setVisible(True)
+
+    def _on_pty_output(self) -> None:
+        if not self._pty:
+            return
+        data = self._pty.read()
+        if not data:  # shell exited / EOF
+            self._stop_pty()
+            self._send_terminal_state()
+            self._allow_term.setChecked(False)
+            return
+        self._host_term.feed(data)
+        if self._host_ws:
+            self._host_ws.sendTextMessage(json.dumps({"type": "pty", "data": _b64(data)}))
+
+    def _stop_pty(self) -> None:
+        if self._pty_notifier:
+            self._pty_notifier.setEnabled(False)
+            self._pty_notifier = None
+        if self._pty:
+            self._pty.close()
+            self._pty = None
+        self._host_term.setVisible(False)
+
+    def _stream(self) -> None:
+        if self._host_ws:
+            self._host_ws.sendTextMessage(share.host_snapshot_frame(self._sampler))
+
+    def _stop_host(self) -> None:
+        self._timer.stop()
+        self._stop_pty()
+        if self._host_ws:
+            self._host_ws.close()
+            self._host_ws = None
+        self._code_label.setText("")
+        self._stop_btn.setEnabled(False)
+        self._start_btn.setEnabled(True)
+        self._host_status.setText("Stopped sharing.")
+
+    def _host_closed(self) -> None:
+        self._timer.stop()
+        self._stop_pty()
+        self._start_btn.setEnabled(True)
+        self._stop_btn.setEnabled(False)
+        if self._code_label.text():
+            self._code_label.setText("")
+            self._host_status.setText("Disconnected from the relay.")
+
+    # ----------------------------------------------------------------- guest
+    def _build_guest(self) -> QFrame:
+        card, v = _card("Join a shared session")
+        row = QHBoxLayout()
+        self._code_input = QLineEdit()
+        self._code_input.setPlaceholderText("Enter share code")
+        self._code_input.setMaxLength(6)
+        self._code_input.setFixedWidth(160)
+        self._join_btn = QPushButton("Join")
+        self._join_btn.setObjectName("PrimaryButton")
+        self._join_btn.clicked.connect(self._join)
+        self._leave_btn = QPushButton("Leave")
+        self._leave_btn.setEnabled(False)
+        self._leave_btn.clicked.connect(self._leave)
+        row.addWidget(self._code_input)
+        row.addWidget(self._join_btn)
+        row.addWidget(self._leave_btn)
+        row.addStretch(1)
+        v.addLayout(row)
+        self._guest_status = QLabel("")
+        self._guest_status.setObjectName("Muted")
+        v.addWidget(self._guest_status)
+
+        self._view = QTextEdit()
+        self._view.setObjectName("Report")
+        self._view.setReadOnly(True)
+        self._view.setVisible(False)
+        self._view.setMinimumHeight(200)
+        v.addWidget(self._view)
+
+        self._term_label = QLabel("")
+        self._term_label.setObjectName("Muted")
+        self._term_label.setVisible(False)
+        v.addWidget(self._term_label)
+        self._guest_term = TerminalView()
+        self._guest_term.keys.connect(self._guest_key)
+        self._guest_term.resized.connect(self._guest_resize)
+        self._guest_term.setVisible(False)
+        v.addWidget(self._guest_term)
+        return card
+
+    def _join(self) -> None:
+        code = self._code_input.text().strip().upper()
+        if not load_token():
+            self._guest_status.setText("Set a Gitea access token in Setup → Account access first.")
+            return
+        if not code:
+            self._guest_status.setText("Enter a share code.")
+            return
+        self._guest_status.setText("Connecting…")
+        self._join_btn.setEnabled(False)
+        self._guest_ws = QWebSocket()
+        self._guest_ws.connected.connect(lambda: self._guest_ws.sendTextMessage(json.dumps({"token": load_token()})))
+        self._guest_ws.textMessageReceived.connect(self._guest_msg)
+        self._guest_ws.disconnected.connect(self._guest_closed)
+        self._guest_ws.errorOccurred.connect(lambda *_: self._guest_status.setText(f"Relay error: {self._guest_ws.errorString()}"))
+        self._guest_ws.open(QUrl(_relay_url() + "/ws/guest/" + code))
+
+    def _guest_msg(self, text: str) -> None:
+        try:
+            data = json.loads(text)
+        except ValueError:
+            return
+        if data.get("error"):
+            self._guest_status.setText(data["error"])
+            return
+        if "joined" in data:
+            self._guest_status.setText(f"Viewing {data.get('host', '?')}'s machine — read-only.")
+            self._leave_btn.setEnabled(True)
+            self._view.setVisible(True)
+            self._guest_ws.sendTextMessage(json.dumps({"type": "req_full"}))
+            return
+        kind = data.get("type")
+        if kind in ("full", "snapshot"):
+            if kind == "full":
+                self._last_report = data.get("report")
+                self._last_inv = data.get("inventory")
+            self._view.setHtml(share.guest_html(data.get("snapshot"), self._last_report, self._last_inv))
+        elif kind == "terminal":
+            self._set_terminal_visible(bool(data.get("enabled")))
+        elif kind == "pty":
+            self._guest_term.feed(base64.b64decode(data["data"]))
+
+    def _set_terminal_visible(self, enabled: bool) -> None:
+        self._term_label.setVisible(True)
+        self._term_label.setText("Terminal enabled by host — your keystrokes run on their machine. Click here and type."
+                                 if enabled else "Terminal not enabled by the host.")
+        self._guest_term.setVisible(enabled)
+        if enabled:
+            self._guest_term.reset()
+            self._guest_resize(*self._guest_term.grid())
+            self._guest_term.setFocus()
+
+    def _guest_key(self, data: bytes) -> None:
+        if self._guest_ws:
+            self._guest_ws.sendTextMessage(json.dumps({"type": "pty_in", "data": _b64(data)}))
+
+    def _guest_resize(self, rows: int, cols: int) -> None:
+        if self._guest_ws:
+            self._guest_ws.sendTextMessage(json.dumps({"type": "pty_resize", "rows": rows, "cols": cols}))
+
+    def _leave(self) -> None:
+        if self._guest_ws:
+            self._guest_ws.close()
+            self._guest_ws = None
+        for w in (self._view, self._term_label, self._guest_term):
+            w.setVisible(False)
+        self._leave_btn.setEnabled(False)
+        self._join_btn.setEnabled(True)
+        self._guest_status.setText("Left the session.")
+
+    def _guest_closed(self) -> None:
+        self._join_btn.setEnabled(True)
+        self._leave_btn.setEnabled(False)
+        if self._view.isVisible():
+            self._guest_status.setText("Session ended (host disconnected).")
+
+    def shutdown(self) -> None:
+        self._timer.stop()
+        self._stop_pty()
+        for ws in (self._host_ws, self._guest_ws):
+            if ws:
+                ws.close()

src/rigdoctor/gui/terminal_widget.py

@@ -0,0 +1,98 @@
+"""A minimal terminal view: renders PTY output via pyte and emits keystrokes (M12, Tier 3).
+
+Used by both sides of a shared session — the host (mirrors its local PTY, can also type, e.g.
+a sudo password) and the guest (renders the streamed PTY, sends keystrokes). Monochrome for
+now; cursor addressing / layout (vim, top) work via pyte.
+"""
+
+from __future__ import annotations
+
+import pyte
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtGui import QFontDatabase, QFontMetrics, QTextCursor
+from PySide6.QtWidgets import QPlainTextEdit
+
+
+class TerminalView(QPlainTextEdit):
+    keys = Signal(bytes)        # user keystrokes -> bytes for the PTY
+    resized = Signal(int, int)  # rows, cols
+
+    def __init__(self, rows: int = 24, cols: int = 80):
+        super().__init__()
+        self.setLineWrapMode(QPlainTextEdit.LineWrapMode.NoWrap)
+        self.setFont(QFontDatabase.systemFont(QFontDatabase.SystemFont.FixedFont))
+        self.setUndoRedoEnabled(False)
+        self.setMinimumHeight(260)
+        self._rows, self._cols = rows, cols
+        self._screen = pyte.HistoryScreen(cols, rows, history=1000, ratio=0.5)
+        self._stream = pyte.ByteStream(self._screen)
+
+    def grid(self) -> tuple[int, int]:
+        return self._rows, self._cols
+
+    def feed(self, data: bytes) -> None:
+        self._stream.feed(data)
+        self._render()
+
+    def reset(self) -> None:
+        self._screen.reset()
+        self._render()
+
+    def _row_text(self, row) -> str:
+        return "".join(row[x].data for x in range(self._cols)).rstrip()
+
+    def _render(self) -> None:
+        bar = self.verticalScrollBar()
+        at_bottom = bar.value() >= bar.maximum() - 2
+        prev = bar.value()
+        history = [self._row_text(r) for r in self._screen.history.top]  # scrollback
+        self.setPlainText("\n".join(history + list(self._screen.display)))
+        if at_bottom:  # follow output; place caret at the real (row, col)
+            cursor = self.textCursor()
+            cursor.movePosition(QTextCursor.MoveOperation.Start)
+            cursor.movePosition(QTextCursor.MoveOperation.Down, QTextCursor.MoveMode.MoveAnchor, len(history) + self._screen.cursor.y)
+            cursor.movePosition(QTextCursor.MoveOperation.Right, QTextCursor.MoveMode.MoveAnchor, self._screen.cursor.x)
+            self.setTextCursor(cursor)
+            self.ensureCursorVisible()
+        else:  # user scrolled up to read — keep their place
+            bar.setValue(prev)
+
+    def resizeEvent(self, event):  # noqa: N802 (Qt override)
+        super().resizeEvent(event)
+        fm = QFontMetrics(self.font())
+        cw = max(1, fm.horizontalAdvance("M"))
+        ch = max(1, fm.height())
+        cols = max(20, self.viewport().width() // cw)
+        rows = max(6, self.viewport().height() // ch)
+        if (rows, cols) != (self._rows, self._cols):
+            self._rows, self._cols = rows, cols
+            self._screen.resize(rows, cols)
+            self._render()
+            self.resized.emit(rows, cols)
+
+    def keyPressEvent(self, event):  # noqa: N802 (Qt override)
+        data = self._translate(event)
+        if data:
+            self.keys.emit(data)
+        event.accept()  # display comes from PTY output, not local editing
+
+    @staticmethod
+    def _translate(event) -> bytes:
+        key = event.key()
+        mod = event.modifiers()
+        k = Qt.Key
+        if mod & Qt.KeyboardModifier.ControlModifier and k.Key_A.value <= key <= k.Key_Z.value:
+            return bytes([key - k.Key_A.value + 1])  # Ctrl-A..Ctrl-Z
+        special = {
+            k.Key_Return.value: b"\r", k.Key_Enter.value: b"\r",
+            k.Key_Backspace.value: b"\x7f", k.Key_Tab.value: b"\t",
+            k.Key_Escape.value: b"\x1b",
+            k.Key_Up.value: b"\x1b[A", k.Key_Down.value: b"\x1b[B",
+            k.Key_Right.value: b"\x1b[C", k.Key_Left.value: b"\x1b[D",
+            k.Key_Home.value: b"\x1b[H", k.Key_End.value: b"\x1b[F",
+            k.Key_Delete.value: b"\x1b[3~", k.Key_PageUp.value: b"\x1b[5~", k.Key_PageDown.value: b"\x1b[6~",
+        }
+        if key in special:
+            return special[key]
+        text = event.text()
+        return text.encode("utf-8") if text else b""

src/rigdoctor/gui/theme.py

@@ -14,6 +14,7 @@ CARD_BORDER = "#2a2f39"
 TRACK = "#2a2f39"
 TEXT = "#e6e8eb"
 MUTED = "#8b929c"
+INPUT_BG = "#0d0f13"  # form-control background (must stay dark — see contrast rule)
 
 ACCENT = "#38bdf8"
 COLD = "#7dd3fc"  # icey-blue
@@ -138,4 +139,15 @@ QCheckBox::indicator:checked {{
 QDialog {{ background: {BG}; }}
 QMessageBox {{ background: {CARD}; }}
 QDialog QLabel, QMessageBox QLabel {{ color: {TEXT}; background: transparent; }}
+
+/* Form controls: keep dark bg + light text (Fusion defaults to light-on-light here). */
+QLineEdit, QPlainTextEdit, QAbstractSpinBox, QComboBox {{
+    background: {INPUT_BG}; color: {TEXT};
+    border: 1px solid {CARD_BORDER}; border-radius: 6px; padding: 5px 8px;
+    selection-background-color: {ACCENT}; selection-color: #06222e;
+}}
+QLineEdit:focus, QPlainTextEdit:focus, QAbstractSpinBox:focus, QComboBox:focus {{
+    border: 1px solid {ACCENT};
+}}
+QLineEdit:disabled, QPlainTextEdit:disabled, QAbstractSpinBox:disabled {{ color: {MUTED}; }}
 """

tests/test_pty_session.py

@@ -0,0 +1,27 @@
+"""Tests for the host PTY session (M12 Tier 3)."""
+
+import time
+import unittest
+
+from rigdoctor.core.pty_session import PtySession
+
+
+class PtySessionTests(unittest.TestCase):
+    def test_runs_command_and_reads_output(self):
+        pty = PtySession(rows=24, cols=80)
+        try:
+            time.sleep(0.4)
+            pty.read()  # drain the shell prompt
+            pty.write(b"echo PTY_MARKER_42\n")
+            deadline = time.time() + 3
+            buf = ""
+            while time.time() < deadline and "PTY_MARKER_42" not in buf:
+                time.sleep(0.1)
+                buf += pty.read().decode(errors="replace")
+            self.assertIn("PTY_MARKER_42", buf)
+        finally:
+            pty.close()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_relay_frames.py

@@ -0,0 +1,38 @@
+"""Tests for M12 relay frames + guest HTML rendering (host/guest data shapes)."""
+
+import json
+import unittest
+
+from rigdoctor.core import share
+from rigdoctor.core.sampler import Sampler
+from rigdoctor.core.sources import available_sources
+
+
+class RelayFrameTests(unittest.TestCase):
+    def setUp(self):
+        self.sampler = Sampler(available_sources())
+
+    def test_full_frame_shape(self):
+        frame = json.loads(share.host_full_frame(self.sampler))
+        self.assertEqual(frame["type"], "full")
+        self.assertIn("groups", frame["snapshot"])
+        self.assertIsInstance(frame["report"], list)
+        self.assertIsInstance(frame["inventory"], dict)
+
+    def test_snapshot_frame_shape(self):
+        frame = json.loads(share.host_snapshot_frame(self.sampler))
+        self.assertEqual(frame["type"], "snapshot")
+        self.assertIn("groups", frame["snapshot"])
+
+    def test_guest_html_renders(self):
+        snap = {"groups": {"gpu": [{"name": "temp", "value": 51.0, "unit": "°C"}]}}
+        report = [{"severity": "ok", "category": "Logs", "title": "No errors"}]
+        inv = {"System": {"Kernel": "7.0.0"}}
+        html = share.guest_html(snap, report, inv)
+        self.assertIn("51.0 °C", html)
+        self.assertIn("No errors", html)
+        self.assertIn("Kernel", html)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_share.py

@@ -0,0 +1,46 @@
+"""Tests for M12 Tier 2 share server: token gating + endpoints."""
+
+import json
+import threading
+import unittest
+import urllib.error
+import urllib.request
+
+from rigdoctor.core import share
+
+
+class ShareServerTests(unittest.TestCase):
+    def setUp(self):
+        self.srv, self.token = share.make_server("127.0.0.1", 0)
+        self.port = self.srv.server_address[1]
+        self.thread = threading.Thread(target=self.srv.serve_forever, daemon=True)
+        self.thread.start()
+
+    def tearDown(self):
+        self.srv.shutdown()
+
+    def _url(self, path, token=None):
+        q = f"?t={token}" if token else ""
+        return f"http://127.0.0.1:{self.port}{path}{q}"
+
+    def test_requires_token(self):
+        with self.assertRaises(urllib.error.HTTPError) as cm:
+            urllib.request.urlopen(self._url("/api/snapshot"), timeout=10)
+        self.assertEqual(cm.exception.code, 403)
+
+    def test_bad_token_rejected(self):
+        with self.assertRaises(urllib.error.HTTPError) as cm:
+            urllib.request.urlopen(self._url("/api/snapshot", "wrong"), timeout=10)
+        self.assertEqual(cm.exception.code, 403)
+
+    def test_snapshot_with_token(self):
+        data = json.load(urllib.request.urlopen(self._url("/api/snapshot", self.token), timeout=10))
+        self.assertIn("groups", data)
+
+    def test_page_served(self):
+        body = urllib.request.urlopen(self._url("/", self.token), timeout=10).read()
+        self.assertIn(b"read-only share", body)
+
+
+if __name__ == "__main__":
+    unittest.main()