From 61c929d891c60b247bb7cc745b479cabf83104d2 Mon Sep 17 00:00:00 2001 From: c4ch3c4d3 Date: Sat, 22 Aug 2026 18:17:27 -0600 Subject: [PATCH] docs: reliability core subsystem guide (v1.4.0) --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index e57f9b6..a40009f 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,44 @@ terminal I/O, and reboot persistence. ## Stability notes (Pager 24.10.1) +### Reliability Core (v1.4.0) + +The factory `/etc/config/pineapd` ships every crash source below enabled, so +guards that only live inside Mark VIII revert on every reset/upgrade. v1.4.0 +makes the fixes structural (payload-only — no firmware changes): + +- **Boot guard** (`mk8-guard`, START=49): enforces the known-good UCI set + before the S50 pineapple stack starts; idempotent, diff-only commits, + logged to `/tmp/mk8-guard.log` and the event journal. +- **Profiles + rollback watchdogs**: every risky operation (AP deploy, + client-mode change, profile restore) first snapshots UCI under + `/mmc/mk8/profiles/`, then spawns a detached watchdog probing *local* + liveness (`127.0.0.1:8080` + monitor presence). Sustained failure → + automatic snapshot restore + `wifi reload`; recovery → promotes + `lastknown-good`. Watchdogs self-exit after 120 quiet ticks. +- **RF plan**: phy0 is always 2.4GHz ops; phy1 role-switches + uplink/attack/idle (`POST /api/rfplan/role`). The uplink STA lives on + radio1, so client-mode no longer blinds 2.4GHz recon. Hop governance + belongs to the role manager, not the boot guard. +- **Supervisor**: passive sampler (pidof/iw//proc only — never pineapd's + socket), bounded JSONL journal at `/mmc/mk8/events.log`, boot-marker + unexpected-reboot detection, memory watermark alerts. Dashboard shows + events feed + reliability counters + guard sync chip. +- **Atomic deploys**: `scripts/deploy.sh` stamps `VERSION` into build + copies only, sha256-verifies the upload, swaps `/mmc/mk8/releases/` + with a `current` symlink, polls local health, and auto-rolls back to the + previous release on failure. +- **Smoke suite**: `scripts/smoke.sh` on-device (read-only checks always; + `--write` adds reconcile/watchdog drills; `SMOKE_UPLINK_SSID=...` enables + the RF-role drill). All checks verified against live hardware including + reboot persistence. + +Persistent state lives in `/mmc/mk8/` and survives reboots *and* firmware +upgrades (overlay wipes). A pre-reliability config backup is captured at +first deploy. + +### pineapd crash sources found and fixed on this firmware + pineapd crash sources found and fixed on this firmware (verified on-device, zero crashes over sustained watches):