From 54c92d599357c49f0e59549a649ce95c28a8ce8e Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 14 Jun 2026 23:14:32 +0200 Subject: [PATCH] docs: add live Colibri rebuild runbook (Sam & Codex) Document how a running live USB can clone, build, install, and validate Colibri without a full ISO rebuild, plus the future helper-script shape.\n\nChecks: npx --yes prettier@3 --check docs/LIVE-COLIBRI-REBUILD.md; git diff --check. Note: ./scripts/check-format.sh still reports existing PLAN-OPERATOR-USB-NEXT.md formatting drift outside this change. --- docs/LIVE-COLIBRI-REBUILD.md | 225 +++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 docs/LIVE-COLIBRI-REBUILD.md diff --git a/docs/LIVE-COLIBRI-REBUILD.md b/docs/LIVE-COLIBRI-REBUILD.md new file mode 100644 index 00000000..d91f2a7d --- /dev/null +++ b/docs/LIVE-COLIBRI-REBUILD.md @@ -0,0 +1,225 @@ +# Live USB Colibri rebuild lane + +This runbook documents how a running Clawdie live USB can rebuild and redeploy +Colibri without waiting for a full ISO rebuild. + +Use this for **field repair and validation** when the USB boots but a Colibri +binary, rc.d script, or small runtime behavior needs testing. A successful live +rebuild does **not** replace the release ISO process; it proves the fix before +the next image is rebuilt. + +## Why this exists + +The live USB currently stages `/home/clawdie/ai/colibri` as a source snapshot +from `git archive`. That snapshot is useful for inspection, but it is not a real +git checkout and has no `.git` directory: + +```sh +cd /home/clawdie/ai/colibri +git remote -v +# fatal: not a git repository (or any of the parent directories): .git +``` + +For rebuilds, clone a fresh working checkout into a separate directory such as +`/home/clawdie/ai/colibri-build` or `/var/tmp/colibri-build`. + +## Required live packages + +Future ISOs should include these packages to make this path available out of the +box: + +```text +rust +pkgconf +git +``` + +`git` is already in the live operator package list. `rust` provides `cargo` on +FreeBSD. `pkgconf` is needed by common Rust native dependency build scripts. + +Optional if future dependencies need them: + +```text +gmake +cmake +``` + +## One-time readiness check + +Run on the live USB: + +```sh +rustc --version +cargo --version +git --version +pkgconf --version +``` + +If `rustc` or `cargo` is missing, the current USB cannot rebuild Colibri from +source without installing packages first or using a newer ISO. + +## Clone or update Colibri + +Use HTTPS unless the live USB has an SSH key configured for Forgejo. + +```sh +mkdir -p /home/clawdie/ai +cd /home/clawdie/ai + +if [ ! -d colibri-build/.git ]; then + git clone https://code.smilepowered.org/clawdie/colibri.git colibri-build +fi + +cd /home/clawdie/ai/colibri-build +git fetch --prune origin +git switch main +git pull --ff-only +``` + +To test a specific commit or branch: + +```sh +git checkout c967698 +# or: +# git switch fix/some-branch +``` + +## Build Colibri release binaries + +Minimal live USB build set: + +```sh +cd /home/clawdie/ai/colibri-build +cargo build --release \ + -p colibri-daemon \ + -p colibri-client \ + -p colibri-mcp \ + -p colibri-glasspane-tui +``` + +Expected outputs: + +```text +target/release/colibri-daemon +target/release/colibri +target/release/colibri-smoke-agent +target/release/colibri-mcp +target/release/colibri-tui +``` + +## Install rebuilt Colibri into the running USB + +The live USB does not use `sudo`. Privileged actions use `mdo`. + +```sh +cd /home/clawdie/ai/colibri-build + +mdo -u root service colibri_daemon stop || true +mdo -u root pkill -f colibri-daemon || true +mdo -u root rm -f /var/run/colibri/colibri.sock +mdo -u root rm -f /var/run/colibri/colibri-daemon.pid +mdo -u root rm -f /var/run/colibri/colibri-daemon-supervisor.pid + +mdo -u root install -m 0555 target/release/colibri-daemon /usr/local/bin/colibri-daemon +mdo -u root install -m 0555 target/release/colibri /usr/local/bin/colibri +mdo -u root install -m 0555 target/release/colibri-smoke-agent /usr/local/bin/colibri-smoke-agent +mdo -u root install -m 0555 target/release/colibri-mcp /usr/local/bin/colibri-mcp +mdo -u root install -m 0555 target/release/colibri-tui /usr/local/bin/colibri-tui +mdo -u root install -m 0555 packaging/freebsd/colibri_daemon.in /usr/local/etc/rc.d/colibri_daemon + +mdo -u root chown -R colibri:colibri /var/run/colibri /var/db/colibri /var/log/colibri +mdo -u root service colibri_daemon start +``` + +`service colibri_daemon start` should return to the shell after a few seconds. If +it stays in the foreground, check that the rc.d script uses +`colibri_daemon_binary`, not `colibri_daemon_program`, and that `command=` is +`/usr/sbin/daemon`. + +## Validate runtime + +```sh +service colibri_daemon status +colibri status +colibri list-skills | head +colibri-mcp tools +``` + +Useful deeper checks: + +```sh +service colibri_daemon health +tail -80 /var/log/colibri/daemon.log +ls -l /var/run/colibri +sockstat -u | grep colibri || true +``` + +## Record what was installed + +After a successful live rebuild, write a small local manifest: + +```sh +cd /home/clawdie/ai/colibri-build +commit=$(git rev-parse HEAD) +branch=$(git symbolic-ref --short -q HEAD || echo detached) +now=$(date -u +%Y-%m-%dT%H:%M:%SZ) + +cat > /tmp/colibri-live-rebuild.json < /tmp/colibri-live-rebuild.sha256 +mdo -u root install -m 0644 /tmp/colibri-live-rebuild.sha256 /var/db/colibri/live-rebuild.sha256 +``` + +Report both files with validation notes when handing findings back through git. + +## Fast rc.d-only repair + +If only the service script is broken and no binary rebuild is needed, fetch the +current Colibri rc.d source directly: + +```sh +mdo -u root fetch -o /usr/local/etc/rc.d/colibri_daemon \ + https://code.smilepowered.org/clawdie/colibri/raw/branch/main/packaging/freebsd/colibri_daemon.in +mdo -u root chmod 555 /usr/local/etc/rc.d/colibri_daemon +mdo -u root service colibri_daemon restart +``` + +Sanity checks: + +```sh +grep -n 'colibri_daemon_program\|colibri_daemon_binary\|^command=\|^command_args=' /usr/local/etc/rc.d/colibri_daemon +``` + +Expected: + +- `colibri_daemon_binary` exists. +- `command="/usr/sbin/daemon"` exists. +- no `colibri_daemon_program` remains. +- no `-u ${colibri_daemon_user}` remains in `command_args`. + +## Future ISO improvement + +Add a helper script, tentatively `/usr/local/bin/colibri-live-rebuild`, that +automates this runbook: + +1. clone/update `/home/clawdie/ai/colibri-build` +2. checkout requested branch or commit +3. run the release build +4. stop `colibri_daemon` +5. install binaries and rc.d script +6. clean stale socket/pid files +7. restart and validate `colibri status` +8. write `/var/db/colibri/live-rebuild.json` and `.sha256` + +This keeps the live USB usable as a self-hosted Colibri validation target while +preserving ISO rebuilds for release artifacts. -- 2.45.3