# Doc 75: Process Supervisor, Shadow Binary Execution & Shared Memory Control Plane

> **Mã định danh tài liệu**: `DOC-75-SUPERVISOR-SHADOW-BIN-SSOT-2026`  
> **Mốc thời gian (Timestamp)**: 20/09/2026  
> **Trạng thái**: `[SSoT - HOÀN THIỆN & ĐÃ KIỂM CHỨNG THỰC TẾ]`  
> **Các tài liệu liên quan**: [Doc 50](./50_two_tier_asymmetric_hybrid_architecture_specification.md) · [Doc 06](./06_binary_ipc_protocol_spec.md) · [Doc 72](./72_hardware_safety_and_focus_interlock_specification.md) · [`AGENTS.md`](../../AGENTS.md)

---

## 1. Bối Cảnh & Vấn Đề Kỹ Thuật (Problem Statement)

Trong học thuyết Tác chiến Song song Kép (Dual-Track Doctrine), hệ thống đòi hỏi:
- **Tuyến Thực địa (Live Ops Track)**: Vận hành liên tục trên client game `PathOfExile.exe`, cày map và thu thập dữ liệu thật.
- **Tuyến Phát triển (Dev & QA Track)**: Các Sub-Agent và kỹ thuật viên tiếp tục refactor, tối ưu thuật toán, và biên dịch C++23 song song.

### 3 "Tử Huyệt" Của Mô Hình Cũ (Ad-hoc Script / Cron Loop):
1. **Lỗi khóa file `LNK1104`**: Khi `AutoPOE2_Core.exe` đang chạy, Windows khóa file nhị phân khiến MSVC / CMake không thể biên dịch đè bản build mới.
2. **Nghẽn I/O & Race Condition từ File JSON**: Ghi và đọc log telemetry liên tục ra đĩa gây xung đột file lock giữa tiến trình ghi và đọc.
3. **Ảo giác từ Cron LLM**: Việc dùng cron định kỳ (15p/30p) đánh thức LLM khi game không mở khiến AI tự biên tự diễn kết quả cày cuốc.

---

## 2. Kiến Trúc 4 Lớp Giải Pháp (Architectural Solution)

```mermaid
flowchart TD
    subgraph "DEV & QA TRACK (Song song)"
        A["Developer / Sub-Agents"] -->|"Compile C++23 bất kỳ lúc nào"| B["bin/Release/AutoPOE2_Core.exe (Nguồn)"]
        B -->|"Test Suites PASS"| C["Tín hiệu Hot-Swap"]
    end

    subgraph "SUPERVISOR ENGINE (tools/poe2_supervisor.py)"
        D["AutoPOE2 Process Supervisor"] -->|"1. Quản lý sinh tử PID"| E["Game Client: PathOfExile.exe"]
        D -->|"2. Nhân bản Shadow Binary"| F["bin/Release/AutoPOE2_Core_Runtime.exe"]
        D -->|"3. Mở Control Plane"| G["HTTP API: http://127.0.0.1:8088/status"]
        C -.->|"POST /swap"| G
    end

    subgraph "ZERO-LATENCY TELEMETRY (RAM 100%)"
        F -->|"Cập nhật 120Hz O(1)"| H["Shared Memory Seqlock<br/>Local\\POE2_Auto_SharedMem_v1 (4MB)"]
        H -->|"Đọc snapshot_id & timestamp_ms"| D
    end
```

---

## 3. Các Thành Phần Cốt Lõi

### A. Cơ Chế Shadow Binary Execution (`INV-SUPERVISOR-SHADOW-EXEC`)
- Supervisor không chạy trực tiếp `bin/Release/AutoPOE2_Core.exe`.
- Thay vào đó, nó kiểm tra mã băm SHA256 và nhân bản sang `bin/Release/AutoPOE2_Core_Runtime.exe` rồi mới kích hoạt.
- **Hiệu quả thực tế**: Trình biên dịch C++ (MSVC cl.exe / link.exe) có toàn quyền ghi đè `AutoPOE2_Core.exe` mà **không bao giờ bị lỗi `LNK1104: cannot open file`**.

### B. Nguồn Chân Lý Telemetry Duy Nhất (`INV-SUPERVISOR-ZERO-HALLUCINATION`)
- Toàn bộ dữ liệu sống còn (HP, ES, Mana, XYZ, FSM State, số quái vật) được đọc trực tiếp từ khối nhớ chia sẻ 4MB `Local\POE2_Auto_SharedMem_v1` thông qua `CoreShmBridge`.
- **Cơ chế chống giả mạo**: Mỗi snapshot có `snapshot_id` tăng dần và `timestamp_ms` nhị phân. Nếu thời gian cập nhật cách hiện tại $> 4000\text{ms}$, hàm `is_heartbeat_alive()` trả về `False` ngay lập tức, triệt tiêu hoàn toàn khả năng AI bịa đặt dữ liệu farm.

### C. Local Control Plane (HTTP Port 8088)
Cung cấp giao diện chuẩn REST/JSON không phụ thuộc thư viện bên ngoài:
- `GET /status`: Trả về trạng thái đầy đủ (Game PID, Runtime PID, Telemetry).
- `POST /pause`: Tạm dừng bot và giải phóng input.
- `POST /resume`: Khởi động lại bot.
- `POST /swap`: Hoán đổi sang binary mới khi vừa build xong.

---

## 4. Danh Mục Mã Bất Biến Kiến Trúc Bổ Sung

| Mã Bất Biến | Quy Tắc | Module Giám Sát |
|---|---|---|
| **INV-SUPERVISOR-SHADOW-EXEC** | Bot runtime bắt buộc chạy trên bản sao Shadow Binary (`AutoPOE2_Core_Runtime.exe`), giải phóng 100% binary nguồn cho trình biên dịch C++23. | `tools/poe2_supervisor.py` |
| **INV-SUPERVISOR-ZERO-HALLUCINATION** | Telemetry bắt buộc trích xuất trực tiếp từ Shared Memory header (`snapshot_id`, `timestamp_ms`). Nếu timestamp quá 4000ms, báo cáo `HEARTBEAT_DEAD / OFFLINE`. | `core_shm_bridge.py`, `poe2_supervisor.py` |

---

## 5. Bằng Chứng Nghiệm Thu (Empirical Evidence)

1. **Bộ kiểm thử Supervisor Suite**:
   `pytest tests/test_poe2_supervisor.py -v` $\to$ **5/5 PASSED (3.24s)**.
2. **Kiểm thử hồi quy an toàn phần cứng**:
   `pytest tests/test_focus_interlock.py tests/test_poe2_supervisor.py -q` $\to$ **22/22 PASSED (4.43s)**.
3. **Kiểm thử C++23 Hot Path Suite**:
   `build\bin\Release\AutoPOE2_Tests.exe` $\to$ **1230/1230 PASSED (0 failures)**.
4. **Single-shot Probe**:
   `python tools/poe2_supervisor.py --probe` $\to$ Báo cáo trung thực 100% trạng thái client `OFFLINE`.