From 1ee39d5f558813797ec371f64a76c95e7c9f01c3 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Tue, 2 Jun 2026 18:11:32 +0200 Subject: [PATCH 1/2] Add OSA Clawdie build handoff (Sam & Codex) --- doc/CLAWDIE-CODEX-HANDOFF.md | 128 +++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 doc/CLAWDIE-CODEX-HANDOFF.md diff --git a/doc/CLAWDIE-CODEX-HANDOFF.md b/doc/CLAWDIE-CODEX-HANDOFF.md new file mode 100644 index 00000000..63093a73 --- /dev/null +++ b/doc/CLAWDIE-CODEX-HANDOFF.md @@ -0,0 +1,128 @@ +# Clawdie Simplified Binary — OSA Build + Acceptance Handoff + +**From:** Sam & Codex +**Date:** 02.jun.2026 +**Status:** OPEN + +This handoff is the current build/runbook for the simplified `clawdie` lane. +The source-side blocker is closed on `main`; the remaining work is OSA build +and live validation. + +## Current baseline + +- `clawdie-iso origin/main = f2004158fc173f9827c2849f78461a11733b75f5` +- `colibri origin/main = 067fee778cb8e81aeb2580d81eb8ea78b573e4de` + +Important: this local worktree is still on `xfce-operator-usb`. Do not build +from that branch. Build from `main` in both repos. + +## What this fix changes + +The live USB now carries two distinct DB paths, which is the intended +architecture: + +- `colibri_daemon_db_path="/var/db/colibri/colibri.sqlite"` +- `clawdie_db_path="/var/db/clawdie/clawdie.sqlite"` + +That separation avoids `clawdie` falling back to the full Colibri daemon DB +path under `/var/db/colibri`, which previously caused a `Store::open` panic and +restart loop when the `clawdie` user could not open the `colibri`-owned file. + +## OSA build checklist + +- [ ] `~/clawdie-iso` is on `main` and fast-forwarded to `origin/main` +- [ ] `~/colibri` is on `main` and fast-forwarded to `origin/main` +- [ ] `cargo build --workspace --release` succeeds in `~/colibri` +- [ ] `sh -n build.sh` succeeds in `~/clawdie-iso` +- [ ] `./scripts/check-format.sh` succeeds in `~/clawdie-iso` +- [ ] `FEATURE_CLAWDIE=YES` ISO build completes on OSA +- [ ] Live hardware boot proves `clawdie` is stable and uses + `/var/db/clawdie/clawdie.sqlite` + +## Exact OSA commands + +### 1. Update both repos to main + +```sh +cd ~/clawdie-iso +git checkout main +git pull --ff-only + +cd ~/colibri +git checkout main +git pull --ff-only +``` + +### 2. Build Colibri artifacts first + +```sh +cd ~/colibri +cargo build --workspace --release +``` + +Optional quick proof: + +```sh +ls -lh target/release/clawdie +file target/release/clawdie +``` + +### 3. Run the ISO-side preflight + +```sh +cd ~/clawdie-iso +sh -n build.sh +./scripts/check-format.sh +``` + +### 4. Build the test image with the simplified Clawdie lane enabled + +```sh +cd ~/clawdie-iso +FEATURE_CLAWDIE=YES ./build.sh +``` + +If you want a build log, use the normal repo-local `tmp/` pattern: + +```sh +cd ~/clawdie-iso +mkdir -p tmp +/usr/bin/script -q tmp/clawdie-main-build.log env FEATURE_CLAWDIE=YES ./build.sh +``` + +## Live acceptance checks + +Boot the image on real hardware and prove the DB-path fix directly. + +### Required checks + +```sh +service clawdie status +ls -l /var/db/clawdie/clawdie.sqlite +ls -ld /var/db/colibri 2>/dev/null +tail /var/log/clawdie/clawdie.log +sockstat | grep clawdie +``` + +### Expected results + +- `service clawdie status` shows one stable service instance, not a flapping + restart loop +- `/var/db/clawdie/clawdie.sqlite` exists and is owned by `clawdie:clawdie` +- `/var/db/colibri` is not being used by `clawdie` +- `tail /var/log/clawdie/clawdie.log` shows startup once, without repeating + `Store::open` panic output +- `sockstat | grep clawdie` shows the expected service socket binding + +## Deletion criteria + +- [ ] OSA build from `main` succeeded +- [ ] Hardware boot succeeded +- [ ] `clawdie` uses `/var/db/clawdie/clawdie.sqlite` +- [ ] No restart loop / panic remains +- [ ] Findings are recorded elsewhere and this temporary handoff is no longer + needed + +## Results + +Pending OSA build + live validation. -- 2.45.3 From 5c2239216b084b623646b3fbbde7224337b9ae7c Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Thu, 4 Jun 2026 18:44:31 +0200 Subject: [PATCH 2/2] Document ML350p bhyve-first verification plan (Sam & Codex) --- BUILD.md | 21 ++++++++++++++++++++- TESTING.md | 30 +++++++++++++++++++++++++----- doc/CLAWDIE-CODEX-HANDOFF.md | 19 +++++++++++++++++++ 3 files changed, 64 insertions(+), 6 deletions(-) diff --git a/BUILD.md b/BUILD.md index 2ad8dc33..66419e2a 100644 --- a/BUILD.md +++ b/BUILD.md @@ -585,13 +585,32 @@ full `sudo ./build.sh` once after pulling current `main`. ## Testing -Before writing to hardware, use bhyve when available: +Default verification order for the operator USB is now: + +1. static artifact verification on the build host +2. bhyve boot verification on the ML350p virtualization lane +3. physical hardware validation for the final acceptance pass + +Use bhyve before writing to hardware whenever the lane is available: ```sh sudo ./scripts/bhyve-pf-allow.sh sudo ./scripts/bhyve-test.sh ``` +Current ML350p bhyve plan: + +- host RAM budget: ZFS ARC 6G + Poudriere tmpfs 4G + headroom 6G +- bhyve RAM budget: FreeBSD ISO test 4G + Linux cross-compile 4G + FreeBSD builder 4G + spare 4G +- intended VM roles: + - ISO boot verification after each build + - Linux target validation + - FreeBSD/Poudriere test lane + +Use bhyve to catch boot, SDDM/XFCE, and service-start regressions early. Keep +real hardware as the final proof for GPU quirks, Wi-Fi, audio, touchpad, and +display/panel behavior. + See [TESTING.md](TESTING.md) for the full validation checklist. --- diff --git a/TESTING.md b/TESTING.md index 60abcb42..42177212 100644 --- a/TESTING.md +++ b/TESTING.md @@ -329,10 +329,27 @@ sudo mdconfig -d -u md0 --- -## Level 2: Optional bhyve Smoke Boot +## Level 2: bhyve Verification Gate -Use bhyve for a quick boot smoke test when hardware is not immediately -available. Treat this as a convenience check, not the final authority. +Use bhyve as the standard pre-hardware gate when the ML350p lane is available. +This is no longer just an opportunistic smoke test; it is the default +middle-stage verification between static artifact checks and physical hardware. + +Treat bhyve as authoritative for boot/runtime plumbing and still treat real +hardware as the final authority for GPU, panel, input, Wi-Fi, and audio polish. + +### ML350p resource plan + +| Resource | Allocation | +| ----------- | ---------------------------------------------------------------------------- | +| Host (16G) | ZFS ARC 6G + Poudriere tmpfs 4G + headroom 6G | +| bhyve (16G) | FreeBSD ISO test 4G + Linux cross-compile 4G + FreeBSD builder 4G + spare 4G | + +Planned bhyve roles: + +- ISO boot verification after each build +- Linux target validation +- FreeBSD/Poudriere test lane ### Host preflight @@ -349,7 +366,7 @@ Optional PF helper for guest internet: sudo ./scripts/bhyve-pf-allow.sh ``` -### Run the smoke boot +### Run the boot verification ```sh cd /home/clawdie/clawdie-iso @@ -361,14 +378,17 @@ sudo ./scripts/bhyve-test.sh - image boots at all - SDDM/XFCE path appears instead of dropping straight to a dead console - no immediate package/rootfs failure +- Clawdie/Colibri service staging does not crash the session at first boot bhyve is useful for catching: - broken bootcode - missing live-session payload - obvious SDDM/Xorg startup regressions +- obvious service-start regressions after build-time staging changes -It is **not** enough for final GPU confidence. +It is **not** enough for final GPU confidence or laptop-specific UI/device +behavior. --- diff --git a/doc/CLAWDIE-CODEX-HANDOFF.md b/doc/CLAWDIE-CODEX-HANDOFF.md index 63093a73..8d470d8a 100644 --- a/doc/CLAWDIE-CODEX-HANDOFF.md +++ b/doc/CLAWDIE-CODEX-HANDOFF.md @@ -36,6 +36,7 @@ restart loop when the `clawdie` user could not open the `colibri`-owned file. - [ ] `sh -n build.sh` succeeds in `~/clawdie-iso` - [ ] `./scripts/check-format.sh` succeeds in `~/clawdie-iso` - [ ] `FEATURE_CLAWDIE=YES` ISO build completes on OSA +- [ ] bhyve boot verification passes before touching physical hardware - [ ] Live hardware boot proves `clawdie` is stable and uses `/var/db/clawdie/clawdie.sqlite` @@ -90,6 +91,24 @@ mkdir -p tmp /usr/bin/script -q tmp/clawdie-main-build.log env FEATURE_CLAWDIE=YES ./build.sh ``` +### 5. Run the bhyve gate before hardware + +Use the ML350p bhyve lane as the default post-build gate: + +```sh +cd ~/clawdie-iso +sudo ./scripts/bhyve-pf-allow.sh +sudo ./scripts/bhyve-test.sh +``` + +Minimum bhyve acceptance: + +- image boots +- SDDM/XFCE path appears +- no immediate `clawdie` or `colibri` startup failure on boot + +Only move to physical hardware after that passes. + ## Live acceptance checks Boot the image on real hardware and prove the DB-path fix directly. -- 2.45.3