hermes-portable-rescue/docs/architecture.md

Hermes Portable Rescue — Architecture Document

Status: Draft v1.0
Author: Kanban Orchestrator (t_25bcd02c)
Date: 2026-07-04
Dependencies: Research T1 (boot-env), T2 (llm-strat), T3 (pc-repair-workflows)

---

Table of Contents

1. Executive Summary
2. Chosen Boot Environment
3. USB Layout & Filesystem
4. LLM Strategy
5. Tool Packaging Strategy
6. Portable Hermes Runtime Structure
7. Auto-Launch Flow on Boot
8. Diagnostic Pipeline Order
9. Build Pipeline
10. Risks & Mitigations

---

1. Executive Summary

Hermes Portable Rescue is an LLM-driven autonomous diagnostic and repair USB toolkit. The target user inserts a USB drive into a broken Windows PC, boots from it, and an AI agent auto-launches, diagnoses the system (BSOD analysis, hardware inventory, stress tests, disk health), and guides the repair process.

Architecture at a glance:

Component	Decision	Rationale
Bootloader	Ventoy	GPL-licensed, MS-signed Secure Boot, multi-ISO capable
Primary OS	Custom Arch Linux ISO (archiso)	glibc-based, Python-native, full package manager, latest kernel
Secondary OS	WinPE ISO (optional)	Native chkdsk/sfc/dism for Windows-targeted repairs
Persistence	NTFS data partition	Survives across sessions, readable from Windows
LLM Runtime	llama.cpp (CPU)	Offline-capable, no GPU needed
LLM Model (Primary)	Qwen2.5-7B-Instruct Q4_K_M (~4.3 GB)	Best-in-class structured reasoning at 7B size
LLM Model (Fallback)	Phi-3-mini-3.8B Q4_K_M (~2.2 GB)	Runs on any hardware (4 GB+ RAM)
API Fallback	opencode.go / Ollama	Unlocks GPT-4-class reasoning when network is available
USB Size Target	32 GB minimum (64 GB ideal)	Fits OS + both models + tools + output space

---

2. Chosen Boot Environment

Primary: Ventoy + Custom Arch Linux ISO

Ventoy serves as the bootloader foundation. It installs a tiny (~10 MB) bootloader on the USB, and ISOs are simply copied as files to the FAT32 partition. Ventoy handles UEFI, Legacy BIOS, and Secure Boot via Microsoft-signed shim.

Arch Linux (archiso) was chosen as the live environment for the following reasons:

• glibc-based — full Python 3.11+ compatibility (unlike Alpine's musl)
• Rolling release — latest kernel (6.x), best driver support for NVMe, USB3, modern chipsets
• archiso tooling — fully customizable ISO builds (pre-install Python, pip, all tools)
• Package manager (pacman) — can install additional tools live (TTY-only if needed)
• ~800 MB base — leaves room for models and tools on a 32 GB USB
• GPL-licensed — completely free to redistribute (no WinPE licensing headaches)

Secondary: WinPE ISO (Optional Add-on)

A WinPE-based ISO (such as Hiren's Boot CD PE, ~2.5 GB) can be included as a companion for:

• Running native Windows tools (chkdsk, sfc, DISM, diskpart)
• BitLocker management (manage-bde)
• Any scenario where Windows-native tooling is strictly required

Why NOT WinPE as Primary

• Restrictive licensing for redistribution
• Python bootstrap is fragile — must bundle embedded distribution + VC runtime DLLs + pip
• No package manager — all dependencies must be pre-bundled
• Higher engineering cost for less capability

Boot Selection Flow

Ventoy Boot Menu
  ├── 1. Hermes Rescue (Arch Linux) — DEFAULT, auto-boot after 10s
  │     └── Auto-launches Hermes agent
  ├── 2. Windows PE (Optional) — Manual selection
  │     └── Manual tool use
  └── 3. Boot from local disk — Bypass rescue

---

3. USB Layout & Filesystem

USB Drive (≥32 GB)
━━━ EFI System Partition (FAT32, ~500 MB)
    └── Ventoy bootloader (EFI/BOOT/, EFI/ventoy/)
━━━ ISO/ (FAT32 or exFAT, copy ISOs here)
    ├── hermes-rescue-linux.iso          ~1 GB  (custom Arch Linux)
    ├── hirens-boot-cd-pe.iso            ~2.5 GB (optional WinPE)
    └── memtest86plus.iso                ~20 MB  (RAM tester, optional)
━━━ DATA/ (NTFS, uses remainder of drive)
    ├── hermes/
    │   ├── config.yaml                  — Hermes agent config
    │   ├── models/
    │   │   ├── qwen2.5-7b-q4_k_m.gguf  — Primary LLM (~4.3 GB)
    │   │   └── phi3-mini-q4_k_m.gguf    — Fallback LLM (~2.2 GB)
    │   ├── logs/
    │   │   └── session_YYYYMMDD_HHMMSS.log
    │   ├── diagnostics/
    │   │   ├── hardware_report_*.json
    │   │   ├── bsod_analysis_*.json
    │   │   ├── stress_test_*.json
    │   │   └── driver_scan_*.json
    │   ├── backups/
    │   │   ├── registry/                — Registry hive exports
    │   │   ├── system_files/            — File-level backups
    │   │   └── disk_images/             — DD/partclone images
    │   └── scripts/
    │       ├── custom_recovery.sh       — User-customizable repair script
    │       └── post_diagnostic_hook.sh  — Runs after diagnostics complete
    └── hermes_agent.squashfs            — Bundled Hermes runtime (see §6)

Partition Table

Partition	Size	FS	Label	Purpose
/dev/sda1	~500 MB	FAT32	VTOYEFI	Ventoy boot + EFI
/dev/sda2	~16 GB	FAT32/exFAT	VTOYISO	ISOs (Ventoy reads ISOs from any partition)
/dev/sda3	Remainder	NTFS	DATA	Persistence, config, models, logs

Why NTFS for DATA: Windows-readable without extra tools, supports large files (models), journaled for crash recovery.

---

4. LLM Strategy

Decision: Hybrid Local-First + API Fallback

                    ┌──────────────┐
                    │  User boots  │
                    │  from USB    │
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  Hermes CLI  │
                    │  auto-starts │
                    └──────┬───────┘
                           │
              ┌────────────┴────────────┐
              │                         │
     ┌────────▼────────┐      ┌─────────▼─────────┐
     │   Qwen2.5-7B    │      │  Network Available?│
     │   Q4_K_M (LOCAL)│      │         │          │
     │   ~5 GB RAM     │      │    YES  │  NO      │
     │   ~15-25 tok/s  │      │         │          │
     └────────┬────────┘      └────┬────┘          │
              │                    │               │
              │         ┌──────────▼──┐            │
              │         │ API Fallback│            │
              │         │(opencode.go│            │
              │         │  or Ollama) │            │
              │         └──────────┬──┘            │
              │                    │               │
              └────────┬───────────┘               │
                       │                           │
                       └──────┬────────────────────┘
                              │
                    ┌─────────▼────────┐
                    │  Fallback:       │
                    │  Phi-3-mini Q4   │
                    │  ~2.9 GB RAM     │
                    │  (if primary     │
                    │   won't load)    │
                    └─────────────────┘

Local Models

Role	Model	Quant	File Size	RAM Needed	tok/s
Primary	Qwen2.5-7B-Instruct	Q4_K_M	~4.3 GB	~5.0 GB	15-25
Fallback	Phi-3-mini-4k-instruct	Q4_K_M	~2.2 GB	~2.9 GB	25-40

Model selection rationale:

• Qwen2.5-7B offers best-in-class structured reasoning for BSOD analysis (parsing bugcheck codes, parameter dumps) and instruction following for multi-step diagnostic workflows
• Phi-3-mini as fallback covers 4 GB RAM systems where Qwen won't fit
• Both run CPU-only via llama.cpp — no GPU required

API Fallback

When the target PC has internet access, the agent can fall back to:

• opencode.go (recommended) — for complex multi-step diagnosis
• Ollama server query — if the user has Ollama on their home network
• OpenAI-compatible API — for any compatible provider

The API fallback enables GPT-4-class reasoning for edge cases the local model cannot handle (unusual BSOD codes, complex driver chains, recovery planning).

USB Storage Budget

Component	32 GB USB	64 GB USB
OS ISO	1.0 GB	1.0 GB
Primary model (Qwen Q4_K_M)	4.3 GB	4.3 GB
Fallback model (Phi-3 Q4_K_M)	2.2 GB	2.2 GB
Tools + Runtime	2.0 GB	2.0 GB
WinPE ISO (optional)	2.5 GB	2.5 GB
Total (with WinPE)	12.0 GB	12.0 GB
Remaining for output	~20 GB	~52 GB

Both model files fit comfortably on 32 GB+ USB.

---

5. Tool Packaging Strategy

Bundled on the Arch Linux ISO

Pre-installed via pacman into the custom ISO:

Core diagnostics:

• smartmontools — SMART health checks
• dmidecode — DMI/BIOS information
• lshw — full hardware inventory
• lspci / lsusb — PCI/USB device enumeration
• ddrescue — disk rescue imaging
• testdisk / photorec — partition recovery + file recovery
• ntfs-3g — NTFS read/write
• dislocker — BitLocker volume access
• parted / gpart — partition management

Stress & burn-in:

• stress-ng — CPU/RAM stress testing (with thermal monitoring)
• memtest86+ (separate ISO on USB, bootable via Ventoy) — dedicated RAM test

Network & connectivity:

• curl / wget — HTTP/HTTPS
• openssh — SSH client for remote support
• networkmanager — WiFi/Ethernet management

Python ecosystem:

• python (3.11+)
• python-pip
• python-setuptools
• python-virtualenv

Bundled in the DATA partition

• Hermes runtime (hermes_agent.squashfs) — squashfs archive of the Hermes Python environment with all dependencies
• GGUF model files (models/) — Qwen2.5-7B + Phi-3-mini
• Config (config.yaml) — Hermes agent configuration
• SquashFS mount script — mounts runtime at boot

Not Bundled (Downloaded on Demand if Network Available)

• Full OS updates (kernel, packages via pacman)
• Additional models (if user wants larger quantizations)
• Windows driver packages (sourced from vendor websites)

---

6. Portable Hermes Runtime Structure

DATA/hermes_agent.squashfs  (compressed, ~200-400 MB)
  ├── venv/
  │   ├── bin/
  │   │   ├── python3          — Python 3.11 interpreter
  │   │   ├── hermes           — Hermes CLI entry point
  │   │   └── llama-cli        — llama.cpp inference binary (static)
  │   └── lib/python3.11/
  │       └── site-packages/
  │           ├── hermes/      — Hermes agent core
  │           ├── pyyaml/      — YAML config parsing
  │           ├── requests/    — HTTP client
  │           └── [deps]       — All pip dependencies
  ├── src/hermes_portable/
  │   ├── __init__.py
  │   ├── diagnostics/
  │   │   ├── hardware.py      — Hardware enumeration (T6)
  │   │   ├── bsod.py          — Minidump parser & LLM analysis (T7)
  │   │   ├── drivers.py       — Driver scanner (T8)
  │   │   ├── backup.py        — Backup/restore engine (T9)
  │   │   └── stress.py        — Stress test orchestration (T10)
  │   ├── llm/
  │   │   ├── engine.py        — llama.cpp wrapper
  │   │   └── prompts.py       — Diagnostic prompt templates
  │   └── agent/
  │       ├── pipeline.py      — Diagnostic pipeline orchestrator
  │       └── repair.py        — Guided repair flow
  ├── config.yaml              — Default agent config
  └── boot/
      └── autorun.sh           — Entry point script (§7)

Why SquashFS: Compressed read-only filesystem keeps the runtime compact. The runtime is mounted read-only, with all mutable state going to DATA/hermes/. This prevents corruption from unclean shutdown.

---

7. Auto-Launch Flow on Boot

USB Boot (via Ventoy)
        │
        ▼
Arch Linux ISO boots
        │
        ▼
systemd starts (custom archiso)
        │
        ▼
┌───────────────────────────────┐
│  1. Mount DATA partition      │  Mounts /dev/sda3 (NTFS) to /mnt/data
│     (ntfs-3g /dev/sda3 /mnt/data)
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  2. Mount Hermes runtime      │  Mounts squashfs to /mnt/hermes
│     (mount -o loop /mnt/data/  │
│      hermes_agent.squashfs    │
│      /mnt/hermes)             │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  3. Initialize Python venv    │  Symlinks or bind-mounts venv
│     from squashfs             │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  4. Detect LLM model          │  Checks /mnt/data/hermes/models/
│     (fallback logic)          │  for Qwen GGUF → tries to load
│                                │  → falls back to Phi-3-mini
│                                │  → if both fail, pure API mode
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  5. Network detection         │  Checks internet connectivity
│     (curl --connect-timeout 5 │  If up: enable API fallback
│      https://1.1.1.1)         │  If down: local-only mode
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  6. Launch Hermes agent       │  hermes --config /mnt/data/hermes/
│     (auto-diagnostic mode)    │  config.yaml diagnose
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│  7. Display diagnostic        │  TUI or terminal output
│     progress & results        │  Session logged to /mnt/data/hermes/logs/
└───────────────────────────────┘

Init System Detail

The custom ISO will use a oneshot systemd service (hermes-autorun.service) that runs the autorun script after the live environment boots. The ISO is configured for:

• Auto-login to a TTY (no X server needed — saves RAM and boot time)
• Quiet boot (no verbose kernel messages)
• 10-second Ventoy timeout before auto-selecting Hermes Rescue

The autorun/service does NOT require user interaction to start the diagnostic pipeline — it launches immediately on boot.

---

8. Diagnostic Pipeline Order

The pipeline follows a risk-tiered approach — non-destructive, read-only diagnostics first, then progressively more invasive tests.

Phase 1: Inventory & Health Check (Non-Destructive)

Step 1: Hardware Inventory
  ├── CPU: model, cores, frequency
  ├── RAM: total, slot layout, speed (dmidecode)
  ├── GPU: model, VRAM, driver
  ├── Disks: model, capacity, interface, media type (lshw + lsblk)
  └── Network: adapters, MAC, IP (ip link, lspci)

Step 2: SMART Health (All Physical Disks)
  ├── Read smartctl -a for each disk
  ├── Check: reallocated_sectors, pending_sectors, raw_read_error_rate
  ├── Check: temperature, power_on_hours, wear_level (SSDs)
  └── Flag: PASS / WARNING / FAIL

Step 3: Boot Configuration Analysis
  ├── List Windows installations (if any NTFS volumes found)
  ├── Check BCD store (via ntfs-3g mount → bcdedit or registry)
  ├── Check for BitLocker protection
  └── Report: bootable? encrypted? last successful boot?

Actions if Phase 1 completes clean: Stop here. Report "System appears healthy."

Phase 2: Targeted Diagnostics (Data-Driven)

Step 4: BSOD/Minidump Analysis (if Windows installed)
  ├── Locate .dmp files in C:\Windows\Minidump\
  ├── Locate MEMORY.DMP in C:\Windows\
  ├── Parse dump headers for bugcheck code + parameters
  ├── LLM: interpret stop code, identify likely driver/cause
  └── Suggest: driver rollback, update, hardware test

Step 5: Disk Integrity Check (if NTFS partitions detected)
  ├── Attempt ntfsfix (non-destructive repair)
  ├── Check filesystem consistency (ntfs-3g debug flags)
  └── Report: clean / fixable / needs chkdsk from Windows

Step 6: Registry Sanity Check (if Windows installed)
  ├── Mount SYSTEM hive (via ntfs-3g)
  ├── Check for: corrupted hives, missing critical keys
  └── Extract: driver version info, startup programs

Phase 3: Interactive Repair (User-Initiated)

Step 7: Offer Repair Actions (LLM-guided, user confirms each)
  ├── Boot repair: mount BCD → rebuildbcd
  ├── System file repair: sfc /scannow (requires WinPE)
  ├── Image repair: DISM /RestoreHealth (requires WinPE + source)
  ├── Registry backup: export current hives
  ├── System Restore: enumerate restore points
  ├── Driver rollback: identify problematic drivers → guide rollback
  └── BitLocker recovery: unlock + suspend (if recovery key available)

Step 8: Backup (Before Any Destructive Action)
  ├── Registry hive export (all hives)
  ├── Critical user data backup (Documents, Desktop, AppData)
  ├── Full disk image (ddrescue) — optional, space-permitting
  └── Verify backup integrity (hash comparison)

Step 9: Stress Tests (If Hardware Issue Suspected)
  ├── CPU stress: stress-ng --cpu 0 --timeout 300s
  ├── RAM test: prompt to reboot into MemTest86+
  └── GPU test: basic OpenGL/compute test

Phase 4: Recovery & Verification

Step 10: Apply Repairs (With Rollback)
  ├── Each repair step is logged with undo information
  ├── Before/after state comparison
  └── Verification test after each change

Step 11: Final Report
  ├── What was found
  ├── What was fixed
  ├── What needs manual attention
  ├── USB session logs path
  └── Recommendations for long-term health

---

9. Build Pipeline

The build process follows this order:

1. Build Arch Linux custom ISO (archiso)
   └── Pre-install Python 3.11+, pip, all diagnostic tools
   └── Configure auto-login + systemd autorun service
   └── Set up Hermes autorun service
   └── Output: hermes-rescue-linux.iso

2. Build Hermes runtime squashfs
   └── Create Python venv with Hermes + dependencies
   └── Bundle diagnostic source modules
   └── Include static llama.cpp binary
   └── Compress into squashfs
   └── Output: hermes_agent.squashfs

3. Download LLM model GGUF files
   └── Qwen2.5-7B-Instruct Q4_K_M from Hugging Face
   └── Phi-3-mini-4k-instruct Q4_K_M from Hugging Face

4. Prepare USB
   └── Partition: FAT32 (VTOYEFI + VTOYISO) + NTFS (DATA)
   └── Install Ventoy to USB
   └── Copy ISOs, models, runtime, config
   └── Verify bootability

5. Test (on real hardware)
   └── Cycle through: boot → autorun → diagnostic pipeline → repair → verify
   └── Test on: gaming PC, business PC, VM with simulated failures

Build Scripts (in build/)

Script	Purpose	Dependencies
build-iso.sh	Build custom Arch ISO via archiso	archiso, Docker
build-runtime.sh	Build Hermes runtime squashfs	Python 3.11, squashfs-tools
download-models.sh	Download GGUF models from Hugging Face	curl, Hugging Face hub
prepare-usb.sh	Partition + install Ventoy + copy files	Ventoy, parted, mkfs.*
verify-boot.sh	QEMU boot test of the ISO	qemu-system-x86_64

---

10. Risks & Mitigations

Risk	Likelihood	Impact	Mitigation
Secure Boot blocks boot	Medium	High	Ventoy's shim is MS-signed; Arch ISO uses shim-signed
Python package incompatibility on Arch	Low	Medium	Pin package versions in build; test with target Python 3.11
Target PC has only 4 GB RAM	Medium	Medium	Phi-3-mini fallback runs in ~2.9 GB; API mode if both models fail
USB3 boot fails on old hardware	Low	Medium	Ventoy handles USB2 fallback; test on multiple machines
BitLocker prevents disk access	Medium	Medium	dislocker works on Win 10/11 BitLocker; requires recovery key
NTFS partition corruption on unclean shutdown	Medium	Low	Data is session-based logs; corruption affects last session only
llama.cpp crashes on unsupported CPU	Low	Medium	Detect CPU features (AVX2) before loading model; fallback to API
User has no network for API fallback	Medium	Low	Local model handles 95% of diagnostics offline
Arch ISO too large for 32 GB USB	Low	Medium	Base is ~800 MB + tools ~200 MB = ~1 GB; models fit comfortably
Windows repair needs native Win tools	Medium	Low	Optional WinPE ISO on the same USB; user can reboot into it

---

Appendix A: Research Sources

T1 — Boot Environment Research

• Microsoft Learn: WinPE technical documentation
• Ventoy project (GitHub, 65k+ stars)
• Arch Linux wiki: archiso
• Alpine Linux documentation
• SystemRescue homepage
• Hiren's Boot CD PE forum
• Medicat USB Discord community

T2 — LLM Strategy Research

• Llama.cpp quantization benchmarks (community)
• Qwen2.5-7B technical report (Alibaba)
• Phi-3 technical report (Microsoft)
• OpenRouter model comparison data
• Hugging Face Open LLM Leaderboard

T3 — PC Repair Workflows Research

• Microsoft Learn: bootrec, DISM, SFC, WinRE, chkdsk
• Microsoft KB: registry backup/restore
• Sysnative forums, BleepingComputer, TenForums
• ERUNT project documentation
• Hiren's Boot CD PE tool inventory
• Community knowledge: gaming vs business failure patterns

---

Appendix B: Quick-Reference Command Set

Boot Repair Commands (via WinPE)

bootrec /fixmbr        — Repair MBR
bootrec /fixboot       — Repair boot sector
bootrec /scanos        — Scan for Windows installations
bootrec /rebuildbcd    — Rebuild BCD store
bcdboot C:\Windows     — Copy boot files to EFI partition

System File Repair Commands (via WinPE)

sfc /scannow           — System File Checker
DISM /Online /Cleanup-Image /RestoreHealth   — Component Store Repair
DISM /Online /Cleanup-Image /ScanHealth      — Component Store Scan
DISM /Online /Cleanup-Image /CheckHealth     — Component Store Check
chkdsk C: /f /r        — Check disk + repair + recover bad sectors

Registry & Backup Commands

regedit /e backup.reg  — Export entire registry
reg save HKLM\SYSTEM system.hiv    — Save SYSTEM hive
reg restore HKLM\SOFTWARE software.hiv  — Restore SOFTWARE hive
rstrui.exe             — System Restore wizard
wbadmin start backup   — Command-line backup