stack-guardian 0.1.0__tar.gz

stack_guardian-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LuminariSoftwares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stack_guardian-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: stack-guardian
+Version: 0.1.0
+Summary: A health doctor for a home AI stack: Ollama nodes, GPUs and tailnet, with graded confidence.
+Author: LuminariSoftwares
+License: MIT
+Project-URL: Homepage, https://github.com/LuminariSoftwares/stack-guardian
+Project-URL: Issues, https://github.com/LuminariSoftwares/stack-guardian/issues
+Project-URL: Changelog, https://github.com/LuminariSoftwares/stack-guardian/blob/main/CHANGELOG.md
+Keywords: ollama,gpu,vram,tailscale,health-check,local-llm,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stack-guardian
+
+[![ci](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/ci.yml)
+[![privacy](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/privacy.yml/badge.svg)](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/privacy.yml)
+
+A health doctor for a home AI stack. It collects a snapshot of your nodes (Ollama endpoints, loaded models, NVIDIA
+GPUs, tailnet peers), runs small Python rules against it, remembers the last runs, and reports findings with a
+confidence grade: one sample is at most `LIKELY`, the same finding twice in a row is `VERIFIED`. A finding can carry a
+typed fix that you run on purpose, never automatically.
+
+Status: **0.1.0, first release.** Standard library only, Python 3.11+.
+
+## Install
+
+```
+pip install stack-guardian
+```
+
+This gives you three commands: `stack-guardian` (the CLI), `stack-guardian-serve` and `stack-guardian-mcp`.
+
+Try it offline first: the example snapshot makes every shipped rule fire once.
+
+```
+curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/snapshot.json
+curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/ctx.json
+stack-guardian doctor --snapshot snapshot.json --ctx ctx.json
+```
+
+From a clone instead (for writing rules or running the tests):
+
+```
+git clone https://github.com/LuminariSoftwares/stack-guardian.git
+cd stack-guardian
+python -m venv .venv
+.venv\Scripts\activate          # Windows;  macOS/Linux: source .venv/bin/activate
+pip install -e .
+stack-guardian doctor --snapshot examples/snapshot.json --ctx examples/ctx.json
+```
+
+## For coding agents
+
+- **MCP server** (any MCP client): `stack-guardian-mcp` speaks MCP over stdio with three read-only tools,
+  `stack_health`, `stack_snapshot` and `explain`. In Claude Code:
+
+  ```
+  claude mcp add stack-guardian -e STACK_GUARDIAN_NODES=/path/to/nodes.json -- stack-guardian-mcp
+  ```
+
+  Other clients: command `stack-guardian-mcp`, args `["--nodes", "/path/to/nodes.json"]`. `stack_health` grades
+  against the saved run history without adding to it, and reuses one snapshot for 10 s (`--ttl SECONDS`).
+- **DSH plugin** (`npm install dsh-stack-guardian`, source in `dsh/`, Node 20+): adds one line at the start of a DeepSeek Harness session when the doctor reports
+  WARN or FAIL, and nothing otherwise. It runs `stack-guardian doctor --json --quiet`, so set `STACK_GUARDIAN_NODES`
+  to your nodes file in the harness environment.
+
+## What it does
+
+### 1. `doctor` - run the checks
+
+Describe your nodes in a JSON file (see [examples/nodes.json](examples/nodes.json)) and check them live:
+
+```
+stack-guardian doctor --nodes examples/nodes.json --ctx examples/ctx.json
+```
+
+With neither `--snapshot` nor `--nodes`, `doctor` reads the nodes file named by `$STACK_GUARDIAN_NODES`.
+
+Options: `--checks-dir DIR` (your own rules, default is the shipped `checks.d`), `--ctx FILE` (rule settings such as
+the model each node is expected to hold), `--state FILE` (default `$STACK_GUARDIAN_STATE` or
+`~/.stack-guardian/state.json`), `--json`, `--quiet` (print nothing when all is OK).
+
+Exit codes: `0` all OK/INFO, `1` a WARN, `2` a FAIL, `3` usage, `4` the doctor itself crashed.
+
+Shipped rules: `node.unreachable`, `ollama.unreachable`, `model.not_loaded`, `vram.unattributed`, `gpu.unavailable`,
+`tailnet.unavailable`, `tailnet.peer_offline`, `tailnet.relayed`. Each raises one finding per affected node. A rule that
+raises becomes a `check.crashed` WARN - a buggy rule never reports a broken stack.
+
+### 2. `doctor --fix ID` - run a finding's typed fix
+
+A rule may attach `fix={"action": ..., "args": {...}}` to a finding. There are exactly three actions and never a raw
+shell string:
+
+| action | what it does | needs |
+|---|---|---|
+| `unload_model` | POST `keep_alive: 0` to an Ollama `/api/generate` | `node`, `url`, `model` |
+| `restart_lane` | runs the argv list you declared for that lane | `lane` declared in `--config` |
+| `set_env` | writes `NAME=value` to `<state folder>/env` and sets it for the process | `name`, `value` |
+
+```
+stack-guardian doctor --checks-dir examples/checks.d --snapshot examples/snapshot.json --fix ollama.stuck --config examples/lanes.json
+```
+
+That is a **dry run**: it prints the plan and changes nothing. Add `--apply` to perform it. An applied fix first saves
+the snapshot under `<state folder>/snapshots/`, then runs, then appends one JSON line to `<state folder>/fixes.jsonl`
+(`--audit FILE` to move it). A `set_env` value is never written to the audit, only its length. `ID` is the finding
+code, or `code@node` when several nodes raise the same code. With `--fix`, the exit code is the fix's: `0` plan or
+success, `1` refused or failed, `3` usage.
+
+### 3. Other commands
+
+- `stack-guardian snapshot --nodes FILE` prints the raw snapshot the rules read.
+- `stack-guardian-serve --nodes FILE [--port 8788]` serves a fresh snapshot at `GET /snapshot` (read-only, loopback
+  unless you pass `--host H --allow-remote`), so one machine can ask another for its health.
+  no auth: bind to localhost or a tailnet IP only.
+- `stack-guardian-mcp --nodes FILE [--ctx FILE] [--state FILE] [--ttl SECONDS]`: see [For coding agents](#for-coding-agents).
+
+## Writing a rule
+
+```python
+from stack_guardian import finding as F
+
+def ollama_up(snapshot, ctx):
+    if not snapshot["nodes"]["gpu-box"].get("reachable"):
+        return F.make_finding("ollama.unreachable", "missing", "FAIL", "gpu-box", "Ollama does not answer")
+    return None
+
+CHECKS = [("ollama.up", ollama_up)]
+```
+
+Drop the file in a folder and point `--checks-dir` at it. A full example with a fix is in
+[examples/checks.d/20_ollama_fix.py](examples/checks.d/20_ollama_fix.py). A rule may also return a list of findings,
+one per node.
+
+## Examples
+
+| file | what it is |
+|---|---|
+| `examples/nodes.json` | three nodes: a local one with GPUs, two remote ones over the tailnet |
+| `examples/ctx.json` | rule settings: which model gpu-box-2 should hold |
+| `examples/snapshot.json` | an offline snapshot on which every shipped rule fires once, for trying `doctor` and `--fix` |
+| `examples/lanes.json` | the lanes `restart_lane` is allowed to run |
+| `examples/checks.d/20_ollama_fix.py` | a custom rule whose finding carries a fix |
+
+## Test
+
+```
+pip install pytest
+python -m pytest -q
+```
+
+CI runs this on Ubuntu, Windows and macOS with Python 3.11, plus a privacy scan of every tracked file.
+
+## License
+
+MIT

stack_guardian-0.1.0/README.md

@@ -0,0 +1,144 @@
+# stack-guardian
+
+[![ci](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/ci.yml)
+[![privacy](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/privacy.yml/badge.svg)](https://github.com/LuminariSoftwares/stack-guardian/actions/workflows/privacy.yml)
+
+A health doctor for a home AI stack. It collects a snapshot of your nodes (Ollama endpoints, loaded models, NVIDIA
+GPUs, tailnet peers), runs small Python rules against it, remembers the last runs, and reports findings with a
+confidence grade: one sample is at most `LIKELY`, the same finding twice in a row is `VERIFIED`. A finding can carry a
+typed fix that you run on purpose, never automatically.
+
+Status: **0.1.0, first release.** Standard library only, Python 3.11+.
+
+## Install
+
+```
+pip install stack-guardian
+```
+
+This gives you three commands: `stack-guardian` (the CLI), `stack-guardian-serve` and `stack-guardian-mcp`.
+
+Try it offline first: the example snapshot makes every shipped rule fire once.
+
+```
+curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/snapshot.json
+curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/ctx.json
+stack-guardian doctor --snapshot snapshot.json --ctx ctx.json
+```
+
+From a clone instead (for writing rules or running the tests):
+
+```
+git clone https://github.com/LuminariSoftwares/stack-guardian.git
+cd stack-guardian
+python -m venv .venv
+.venv\Scripts\activate          # Windows;  macOS/Linux: source .venv/bin/activate
+pip install -e .
+stack-guardian doctor --snapshot examples/snapshot.json --ctx examples/ctx.json
+```
+
+## For coding agents
+
+- **MCP server** (any MCP client): `stack-guardian-mcp` speaks MCP over stdio with three read-only tools,
+  `stack_health`, `stack_snapshot` and `explain`. In Claude Code:
+
+  ```
+  claude mcp add stack-guardian -e STACK_GUARDIAN_NODES=/path/to/nodes.json -- stack-guardian-mcp
+  ```
+
+  Other clients: command `stack-guardian-mcp`, args `["--nodes", "/path/to/nodes.json"]`. `stack_health` grades
+  against the saved run history without adding to it, and reuses one snapshot for 10 s (`--ttl SECONDS`).
+- **DSH plugin** (`npm install dsh-stack-guardian`, source in `dsh/`, Node 20+): adds one line at the start of a DeepSeek Harness session when the doctor reports
+  WARN or FAIL, and nothing otherwise. It runs `stack-guardian doctor --json --quiet`, so set `STACK_GUARDIAN_NODES`
+  to your nodes file in the harness environment.
+
+## What it does
+
+### 1. `doctor` - run the checks
+
+Describe your nodes in a JSON file (see [examples/nodes.json](examples/nodes.json)) and check them live:
+
+```
+stack-guardian doctor --nodes examples/nodes.json --ctx examples/ctx.json
+```
+
+With neither `--snapshot` nor `--nodes`, `doctor` reads the nodes file named by `$STACK_GUARDIAN_NODES`.
+
+Options: `--checks-dir DIR` (your own rules, default is the shipped `checks.d`), `--ctx FILE` (rule settings such as
+the model each node is expected to hold), `--state FILE` (default `$STACK_GUARDIAN_STATE` or
+`~/.stack-guardian/state.json`), `--json`, `--quiet` (print nothing when all is OK).
+
+Exit codes: `0` all OK/INFO, `1` a WARN, `2` a FAIL, `3` usage, `4` the doctor itself crashed.
+
+Shipped rules: `node.unreachable`, `ollama.unreachable`, `model.not_loaded`, `vram.unattributed`, `gpu.unavailable`,
+`tailnet.unavailable`, `tailnet.peer_offline`, `tailnet.relayed`. Each raises one finding per affected node. A rule that
+raises becomes a `check.crashed` WARN - a buggy rule never reports a broken stack.
+
+### 2. `doctor --fix ID` - run a finding's typed fix
+
+A rule may attach `fix={"action": ..., "args": {...}}` to a finding. There are exactly three actions and never a raw
+shell string:
+
+| action | what it does | needs |
+|---|---|---|
+| `unload_model` | POST `keep_alive: 0` to an Ollama `/api/generate` | `node`, `url`, `model` |
+| `restart_lane` | runs the argv list you declared for that lane | `lane` declared in `--config` |
+| `set_env` | writes `NAME=value` to `<state folder>/env` and sets it for the process | `name`, `value` |
+
+```
+stack-guardian doctor --checks-dir examples/checks.d --snapshot examples/snapshot.json --fix ollama.stuck --config examples/lanes.json
+```
+
+That is a **dry run**: it prints the plan and changes nothing. Add `--apply` to perform it. An applied fix first saves
+the snapshot under `<state folder>/snapshots/`, then runs, then appends one JSON line to `<state folder>/fixes.jsonl`
+(`--audit FILE` to move it). A `set_env` value is never written to the audit, only its length. `ID` is the finding
+code, or `code@node` when several nodes raise the same code. With `--fix`, the exit code is the fix's: `0` plan or
+success, `1` refused or failed, `3` usage.
+
+### 3. Other commands
+
+- `stack-guardian snapshot --nodes FILE` prints the raw snapshot the rules read.
+- `stack-guardian-serve --nodes FILE [--port 8788]` serves a fresh snapshot at `GET /snapshot` (read-only, loopback
+  unless you pass `--host H --allow-remote`), so one machine can ask another for its health.
+  no auth: bind to localhost or a tailnet IP only.
+- `stack-guardian-mcp --nodes FILE [--ctx FILE] [--state FILE] [--ttl SECONDS]`: see [For coding agents](#for-coding-agents).
+
+## Writing a rule
+
+```python
+from stack_guardian import finding as F
+
+def ollama_up(snapshot, ctx):
+    if not snapshot["nodes"]["gpu-box"].get("reachable"):
+        return F.make_finding("ollama.unreachable", "missing", "FAIL", "gpu-box", "Ollama does not answer")
+    return None
+
+CHECKS = [("ollama.up", ollama_up)]
+```
+
+Drop the file in a folder and point `--checks-dir` at it. A full example with a fix is in
+[examples/checks.d/20_ollama_fix.py](examples/checks.d/20_ollama_fix.py). A rule may also return a list of findings,
+one per node.
+
+## Examples
+
+| file | what it is |
+|---|---|
+| `examples/nodes.json` | three nodes: a local one with GPUs, two remote ones over the tailnet |
+| `examples/ctx.json` | rule settings: which model gpu-box-2 should hold |
+| `examples/snapshot.json` | an offline snapshot on which every shipped rule fires once, for trying `doctor` and `--fix` |
+| `examples/lanes.json` | the lanes `restart_lane` is allowed to run |
+| `examples/checks.d/20_ollama_fix.py` | a custom rule whose finding carries a fix |
+
+## Test
+
+```
+pip install pytest
+python -m pytest -q
+```
+
+CI runs this on Ubuntu, Windows and macOS with Python 3.11, plus a privacy scan of every tracked file.
+
+## License
+
+MIT

stack_guardian-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stack-guardian"
+version = "0.1.0"
+description = "A health doctor for a home AI stack: Ollama nodes, GPUs and tailnet, with graded confidence."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "LuminariSoftwares" }]
+keywords = ["ollama", "gpu", "vram", "tailscale", "health-check", "local-llm", "mcp"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Environment :: Console",
+  "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/LuminariSoftwares/stack-guardian"
+Issues = "https://github.com/LuminariSoftwares/stack-guardian/issues"
+Changelog = "https://github.com/LuminariSoftwares/stack-guardian/blob/main/CHANGELOG.md"
+
+[project.scripts]
+stack-guardian = "stack_guardian.cli:main"
+stack-guardian-mcp = "stack_guardian.mcp_server:main"
+stack-guardian-serve = "stack_guardian.serve:main"
+
+[tool.setuptools]
+packages = ["stack_guardian"]
+
+[tool.setuptools.package-data]
+# the shipped rules are plain .py files in a non-package folder; without this a wheel installs with no rules
+stack_guardian = ["checks.d/*.py"]

stack_guardian-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stack_guardian-0.1.0/stack_guardian/__init__.py

@@ -0,0 +1,13 @@
+"""stack-guardian: a health doctor for a home AI stack (Ollama nodes, GPUs, tailnet).
+
+Check files (checks.d/*.py) export ``CHECKS = [(check_id, fn(snapshot, ctx) -> finding | None)]`` and build findings with
+``stack_guardian.finding.make_finding``. ``import sg_finding`` keeps working inside a check file: the package registers
+that name for checks written against the flat module.
+"""
+import sys
+
+from . import finding
+
+__version__ = "0.1.0.dev0"
+
+sys.modules.setdefault("sg_finding", finding)

stack_guardian-0.1.0/stack_guardian/__main__.py

@@ -0,0 +1,6 @@
+"""python -m stack_guardian doctor ..."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

stack_guardian-0.1.0/stack_guardian/checks.d/10_core.py

@@ -0,0 +1,174 @@
+"""Core 0.1 rules for stack-guardian, a health doctor for a home AI stack.
+
+Each rule inspects a whole snapshot and returns a list with ONE finding per
+failing node (empty when the stack is healthy along that axis), so every node
+keeps its own streak, matches a node= filter and can be named as code@node.
+"""
+
+import sys
+
+import sg_finding as F
+
+
+def _nodes(snapshot):
+    """Return the snapshot's nodes as a list of (name, node) pairs, node None -> {}."""
+    nodes = (snapshot or {}).get("nodes") or {}
+    return [(name, node or {}) for name, node in nodes.items()]
+
+
+def node_unreachable(snapshot, ctx):
+    return [F.make_finding("node.unreachable", "missing", "FAIL", name,
+                           "node did not answer the collector: %s" % node["error"],
+                           evidence=["%s: %s" % (name, node["error"])],
+                           try_=["check the machine is on and reachable", "raise timeout_s if the node is just slow"])
+            for name, node in _nodes(snapshot) if node.get("error")]
+
+
+def ollama_unreachable(snapshot, ctx):
+    out = []
+    for name, node in _nodes(snapshot):
+        bad = [(ep.get("url"), ep.get("error")) for ep in (node.get("ollama") or []) if (ep or {}).get("error")]
+        if bad:
+            out.append(F.make_finding(
+                "ollama.unreachable", "missing", "FAIL", name,
+                "%d Ollama endpoint(s) do not answer: %s" % (len(bad), ", ".join(url for url, _ in bad)),
+                evidence=["%s %s: %s" % (name, url, error) for url, error in bad],
+                try_=["check the Ollama service on that node"]))
+    return out
+
+
+def model_not_loaded(snapshot, ctx):
+    expect = (ctx or {}).get("expect") or {}
+    out = []
+    for name, node in _nodes(snapshot):
+        want = (expect.get(name) or {}).get("model")
+        if not want or not node.get("reachable"):
+            continue
+        running = [(m or {}).get("name") for ep in (node.get("ollama") or []) for m in ((ep or {}).get("running") or [])]
+        if want not in running:
+            out.append(F.make_finding("model.not_loaded", "partial", "WARN", name,
+                                      "expected model not loaded: %s wants %s" % (name, want),
+                                      evidence=["%s running: %s" % (name, ", ".join(running) or "nothing")]))
+    return out
+
+
+def vram_unattributed(snapshot, ctx):
+    limit = int((ctx or {}).get("vram_unattributed_mib", 2048))
+    out = []
+    for name, node in _nodes(snapshot):
+        bad = [((gpu or {}).get("name"), int((gpu or {}).get("unattributed_mib") or 0)) for gpu in (node.get("gpus") or [])]
+        bad = [(gpu, mib) for gpu, mib in bad if mib >= limit]
+        if bad:
+            out.append(F.make_finding("vram.unattributed", "partial", "WARN", name,
+                                      "%d GPU(s) hold VRAM no listed process explains" % len(bad),
+                                      evidence=["%s %s: %d MiB unattributed" % (name, gpu, mib) for gpu, mib in bad]))
+    return out
+
+
+def gpu_unavailable(snapshot, ctx):
+    return [F.make_finding("gpu.unavailable", "partial", "INFO", name, "GPU status unavailable",
+                           evidence=["%s: %s" % (name, node["gpu_error"])], try_=["check nvidia-smi runs on that node"])
+            for name, node in _nodes(snapshot) if node.get("gpu_error")]
+
+
+def _tailnet(node):
+    return (node.get("tailnet") or {}) if "tailnet" in node else None
+
+
+def tailnet_unavailable(snapshot, ctx):
+    return [F.make_finding("tailnet.unavailable", "partial", "INFO", name, "tailnet status unavailable",
+                           evidence=["%s: %s" % (name, _tailnet(node).get("error") or "tailscale gave no status")],
+                           try_=["check tailscale is installed and tailscaled is running"])
+            for name, node in _nodes(snapshot) if _tailnet(node) is not None and _tailnet(node).get("peer") is None]
+
+
+def tailnet_peer_offline(snapshot, ctx):
+    return [F.make_finding("tailnet.peer_offline", "missing", "FAIL", name, "tailnet peer offline: " + name)
+            for name, node in _nodes(snapshot) if _tailnet(node) is not None and _tailnet(node).get("peer") is False]
+
+
+def tailnet_relayed(snapshot, ctx):
+    out = []
+    for name, node in _nodes(snapshot):
+        tailnet = node.get("tailnet") or {}
+        if tailnet.get("peer") and tailnet.get("direct") is False:
+            out.append(F.make_finding("tailnet.relayed", "partial", "INFO", name,
+                                      "tailnet traffic is relayed, not direct: %s via %s" % (name, tailnet.get("derp"))))
+    return out
+
+
+CHECKS = [
+    ("node.unreachable", node_unreachable),
+    ("ollama.unreachable", ollama_unreachable),
+    ("model.not_loaded", model_not_loaded),
+    ("vram.unattributed", vram_unattributed),
+    ("gpu.unavailable", gpu_unavailable),
+    ("tailnet.unavailable", tailnet_unavailable),
+    ("tailnet.peer_offline", tailnet_peer_offline),
+    ("tailnet.relayed", tailnet_relayed),
+]
+
+
+def _selftest():
+    def snap(**over):
+        box = {"reachable": True, "latency_ms": 5, "ollama": [{"url": "http://a:11434", "error": None, "running": [{"name": "qwen3:30b"}]}],
+               "tailnet": {"peer": True, "direct": True, "derp": None, "ips": []}}
+        box2 = {"reachable": True, "latency_ms": 1, "ollama": [{"url": "http://n:11435", "error": None, "running": []}],
+                "gpus": [{"name": "RTX 3060", "used_mib": 300, "unattributed_mib": 300}]}
+        box.update(over.get("gpu-box", {}))
+        box2.update(over.get("gpu-box-2", {}))
+        return {"schema": 1, "taken_at": "T", "nodes": {"gpu-box": box, "gpu-box-2": box2}}
+
+    ctx = {"expect": {"gpu-box": {"model": "qwen3:30b"}}, "vram_unattributed_mib": 2048}
+
+    def t_clean_snapshot_no_findings():
+        return all(fn(snap(), ctx) == [] for _, fn in CHECKS)
+
+    def t_dead_endpoint_fail():
+        [f] = ollama_unreachable(snap(**{"gpu-box-2": {"ollama": [{"url": "http://n:11435", "error": "OSError: refused", "running": []}]}}), ctx)
+        return f["code"] == "ollama.unreachable" and f["level"] == "FAIL" and f["node"] == "gpu-box-2" and "refused" in f["evidence"][0]
+
+    def t_model_not_loaded_warn():
+        [f] = model_not_loaded(snap(**{"gpu-box": {"ollama": [{"url": "http://a:11434", "error": None, "running": [{"name": "qwen3-coder:30b"}]}]}}), ctx)
+        return f["level"] == "WARN" and f["node"] == "gpu-box" and "qwen3-coder:30b" in f["evidence"][0]
+
+    def t_unreachable_node_not_blamed_for_model():
+        return model_not_loaded(snap(**{"gpu-box": {"reachable": False}}), ctx) == []
+
+    def t_vram_threshold():
+        [f] = vram_unattributed(snap(**{"gpu-box-2": {"gpus": [{"name": "RTX 4070", "used_mib": 9000, "unattributed_mib": 8000}]}}), ctx)
+        return f["level"] == "WARN" and "8000 MiB" in f["evidence"][0]
+
+    def t_tailnet_offline_and_relayed():
+        [off] = tailnet_peer_offline(snap(**{"gpu-box": {"tailnet": {"peer": False, "direct": None, "derp": None, "ips": []}}}), ctx)
+        [rel] = tailnet_relayed(snap(**{"gpu-box": {"tailnet": {"peer": True, "direct": False, "derp": "ord", "ips": []}}}), ctx)
+        return off["level"] == "FAIL" and rel["level"] == "INFO" and "ord" in rel["summary"]
+
+    def t_empty_snapshot():
+        return all(fn({}, {}) == [] for _, fn in CHECKS) and all(fn(None, None) == [] for _, fn in CHECKS)
+
+    checks = [
+        ("clean_snapshot_no_findings", t_clean_snapshot_no_findings),
+        ("dead_endpoint_fail", t_dead_endpoint_fail),
+        ("model_not_loaded_warn", t_model_not_loaded_warn),
+        ("unreachable_node_not_blamed_for_model", t_unreachable_node_not_blamed_for_model),
+        ("vram_threshold", t_vram_threshold),
+        ("tailnet_offline_and_relayed", t_tailnet_offline_and_relayed),
+        ("empty_snapshot", t_empty_snapshot),
+    ]
+    passed = 0
+    for name, fn in checks:
+        try:
+            ok = bool(fn())
+        except Exception as exc:  # noqa: BLE001 - a crashed check is a failed check
+            ok = False
+            name = "%s (raised %s: %s)" % (name, type(exc).__name__, exc)
+        passed += ok
+        print(("ok   " if ok else "FAIL ") + name)
+    failed = len(checks) - passed
+    print("sg_checks_core selftest: %d checks, %d passed, %d failed" % (len(checks), passed, failed))
+    return 0 if failed == 0 and checks else 1
+
+
+if __name__ == "__main__":
+    sys.exit(_selftest() if "--selftest" in sys.argv else 2)