clawdie-iso/docs/LIVE-COLIBRI-REBUILD.md

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:

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

Live operator ISOs include these packages to make this path available out of the box:

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:

gmake
cmake

One-time readiness check

Run on the live USB:

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.

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:

git checkout c967698
# or:
# git switch fix/some-branch

Build Colibri release binaries

Minimal live USB build set:

cd /home/clawdie/ai/colibri-build
cargo build --release \
  -p colibri-daemon \
  -p colibri-client \
  -p colibri-mcp \
  -p colibri-glasspane-tui

Expected outputs:

target/release/colibri-daemon
target/release/colibri
target/release/colibri-test-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.

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-test-agent /usr/local/bin/colibri-test-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 does not, stop the command, collect the service file and daemon log, and hand those back through git before continuing.

Validate runtime

service colibri_daemon status
colibri status
colibri list-skills | head
colibri-mcp tools

Useful deeper checks:

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:

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 <<EOF
{
  "repo": "https://code.smilepowered.org/clawdie/colibri.git",
  "branch": "${branch}",
  "commit": "${commit}",
  "installed_at": "${now}",
  "note": "Built and installed on running live USB"
}
EOF

mdo -u root install -m 0644 /tmp/colibri-live-rebuild.json /var/db/colibri/live-rebuild.json
mdo -u root sha256 /usr/local/bin/colibri-daemon /usr/local/bin/colibri /usr/local/bin/colibri-mcp /usr/local/bin/colibri-tui \
  > /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:

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 -n /usr/local/etc/rc.d/colibri_daemon
service colibri_daemon status
colibri status

Expected:

• the rc.d script has valid shell syntax.
• service colibri_daemon start returns to the shell.
• colibri status can connect to /var/run/colibri/colibri.sock.

Future ISO improvement

A future helper script, tentatively /usr/local/bin/colibri-live-rebuild, should automate 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.