docs: FreeBSD build-lane handoff for Codex (ISO Gate 1 runtime proof) #68
3 changed files with 173 additions and 4 deletions
|
|
@ -4,9 +4,9 @@ The Clawdie control plane core — a small, cross-platform (FreeBSD + Linux) Rus
|
|||
daemon that unifies coordination (task board, agent registry, skills catalog)
|
||||
with cache-first cost discipline (byte-stable prompt prefixes, cache-hit metering).
|
||||
|
||||
**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO staging wiring, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state.
|
||||
**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO boot/runtime validation, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state.
|
||||
|
||||
Next ISO integration plan: `docs/ISO-INTEGRATION-PLAN.md`.
|
||||
FreeBSD build lane handoff: `docs/FREEBSD-BUILD-LANE-HANDOFF.md`.
|
||||
ISO acceptance runbook: `docs/ISO-ACCEPTANCE-RUNBOOK.md`.
|
||||
Clawdie Studio/Zed proposal: `docs/CLAWDIE-STUDIO-PROPOSAL.md`.
|
||||
External MCP host prototype: `docs/COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`.
|
||||
|
|
|
|||
169
docs/FREEBSD-BUILD-LANE-HANDOFF.md
Normal file
169
docs/FREEBSD-BUILD-LANE-HANDOFF.md
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
# FreeBSD Build Lane — ISO Validation Handoff
|
||||
|
||||
**For:** Codex (FreeBSD 15 host) · **Goal:** produce a Colibri-backed ISO
|
||||
candidate and prove ISO Gate 1 (passive service) on real FreeBSD.
|
||||
|
||||
This is the runtime-proof step for **Priority 1** of
|
||||
`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`. The build-side wiring is already done on
|
||||
Linux — `clawdie-iso build.sh` stages the Colibri binaries, installs the rc.d
|
||||
script, creates the `colibri` user, and enables the service. What remains is
|
||||
work only a FreeBSD host can do: build the FreeBSD binaries, run the image
|
||||
build, boot it, and run the acceptance checks.
|
||||
|
||||
Linux agents cannot cross-compile the `x86_64-unknown-freebsd` binaries, so
|
||||
this lane belongs to the FreeBSD agent end to end.
|
||||
|
||||
## 0. Host evidence to report
|
||||
|
||||
Run once and paste into the validation report:
|
||||
|
||||
```sh
|
||||
freebsd-version
|
||||
uname -a
|
||||
rustc --version
|
||||
cargo --version
|
||||
go version
|
||||
```
|
||||
|
||||
## 1. Sources
|
||||
|
||||
Three repos must sit side by side (the ISO build defaults to `../colibri`):
|
||||
|
||||
```sh
|
||||
# expected layout
|
||||
# <work>/clawdie-iso
|
||||
# <work>/colibri
|
||||
# <work>/zot
|
||||
git -C colibri pull --ff-only # or: git reset --hard origin/main
|
||||
git -C clawdie-iso pull --ff-only
|
||||
git -C zot pull --ff-only
|
||||
```
|
||||
|
||||
`colibri` main tip for this handoff includes the staged-env tests and the
|
||||
ISO Priority 1 re-scope; `zot` provides the agent binary that the ISO version
|
||||
auto-tracks.
|
||||
|
||||
## 2. Build the FreeBSD artifacts (host toolchains, not on the image)
|
||||
|
||||
```sh
|
||||
# Colibri release binaries — staged by the ISO build, never compiled by it
|
||||
cd colibri
|
||||
cargo build --workspace --release
|
||||
cargo test --workspace # confirm green on real FreeBSD; report output
|
||||
cargo clippy --workspace --all-targets -- -D warnings
|
||||
|
||||
# zot agent binary (Go) — see zot/README for the exact build target
|
||||
cd ../zot
|
||||
# build per zot's instructions; produces the static agent binary
|
||||
```
|
||||
|
||||
After the cargo build, these must exist (the ISO preflight checks them):
|
||||
|
||||
```sh
|
||||
ls -l colibri/target/release/colibri-daemon \
|
||||
colibri/target/release/colibri \
|
||||
colibri/target/release/colibri-smoke-agent
|
||||
# colibri-tui is optional (staged if present)
|
||||
```
|
||||
|
||||
## 3. Build the image
|
||||
|
||||
```sh
|
||||
cd clawdie-iso
|
||||
sudo ./build.sh # FEATURE_COLIBRI defaults to YES
|
||||
```
|
||||
|
||||
`build.sh` will:
|
||||
|
||||
- `preflight_colibri_artifacts` — fail early if any of the three binaries above
|
||||
are missing (it prints the exact `cargo build` command to fix it).
|
||||
- `install_colibri_service` — run `scripts/stage-colibri-iso.sh` against the
|
||||
image root, then `pw -R <root> useradd colibri` and write
|
||||
`colibri_daemon_enable=YES` into the image.
|
||||
|
||||
Useful overrides (defaults are fine for a standard run):
|
||||
|
||||
- `COLIBRI_REPO=/path/to/colibri` if not at `../colibri`.
|
||||
- `COLIBRI_ARTIFACT_DIR=...` if binaries live outside `target/release`.
|
||||
- `COLIBRI_COST_MODE=smart|fast|max` (default `smart`).
|
||||
- `FEATURE_COLIBRI=NO` to skip Colibri staging (not for this lane).
|
||||
|
||||
Output image name encodes the zot version, e.g. `clawdie-quindecim-<ver>.img`.
|
||||
|
||||
## 4. Boot and validate Colibri (ISO Gate 1)
|
||||
|
||||
Boot the image in a bhyve VM or on hardware, then run the full
|
||||
`docs/ISO-ACCEPTANCE-RUNBOOK.md`. Minimum pass set:
|
||||
|
||||
```sh
|
||||
# pre-flight
|
||||
id colibri
|
||||
ls -l /usr/local/bin/colibri /usr/local/bin/colibri-daemon
|
||||
ls -l /usr/local/etc/rc.d/colibri_daemon
|
||||
sysrc colibri_daemon_enable
|
||||
|
||||
# lifecycle + smoke
|
||||
service colibri_daemon start
|
||||
colibri status # paths, cost.mode, scheduler, tasks
|
||||
colibri create-task --title "iso smoke"
|
||||
colibri list-tasks --status queued # contains "iso smoke"
|
||||
colibri intake-task --title "iso intake smoke" --capability freebsd
|
||||
sleep 35 # one scheduler tick (~30s)
|
||||
colibri list-tasks --status queued # contains "iso intake smoke"
|
||||
service colibri_daemon stop # socket gone, SQLite remains
|
||||
service colibri_daemon start && colibri list-tasks --status queued # persistence
|
||||
```
|
||||
|
||||
Confirm `cost.mode` matches the `COLIBRI_COST_MODE` baked at build time.
|
||||
|
||||
## 5. Validate the Hermes rc.d service
|
||||
|
||||
`hermes_daemon` is **not** staged by the clawdie-iso build (only Colibri is) —
|
||||
install it manually from the `hermes-bsd` repo on the booted image (or any
|
||||
FreeBSD host) per `hermes-bsd/README-FreeBSD.md`:
|
||||
|
||||
```sh
|
||||
# one-time setup (from hermes-bsd checkout)
|
||||
sudo pw groupadd hermes
|
||||
sudo pw useradd hermes -g hermes -d /var/db/hermes -s /usr/sbin/nologin
|
||||
sudo cp packaging/freebsd/hermes_daemon.in /usr/local/etc/rc.d/hermes_daemon
|
||||
sudo chmod 555 /usr/local/etc/rc.d/hermes_daemon
|
||||
sudo sysrc hermes_daemon_enable=YES
|
||||
|
||||
# missing-config abort: must fail cleanly, NOT crash-loop under daemon(8) -r
|
||||
sudo service hermes_daemon start # expect exit 1 + clear "config not found"
|
||||
|
||||
# after `hermes setup` + `hermes model` write /var/db/hermes/config.yaml:
|
||||
sudo service hermes_daemon start
|
||||
sudo service hermes_daemon health # "healthy (pid N alive)"
|
||||
sudo service hermes_daemon stop # supervisor exits, child does not respawn
|
||||
```
|
||||
|
||||
Confirm both the supervisor and child pidfiles under `/var/run/hermes/` are
|
||||
removed on stop.
|
||||
|
||||
## 6. Report + acceptance
|
||||
|
||||
Report back: host evidence (§0), full `cargo test` output, the runbook results,
|
||||
and the Hermes checks. File any FreeBSD-specific differences from Linux-built
|
||||
behavior as a PR, not a silent local fix.
|
||||
|
||||
Delete this doc when all are true:
|
||||
|
||||
- [ ] `cargo test --workspace` passes on FreeBSD 15 (output + versions reported).
|
||||
- [ ] `sudo ./build.sh` produces an image with Colibri staged (preflight passed,
|
||||
`colibri` user present, service enabled).
|
||||
- [ ] Booted image passes the Colibri acceptance runbook (start/status/task/
|
||||
intake/stop/restart-persistence).
|
||||
- [ ] Hermes rc.d: missing-config start aborts (no crash loop); configured
|
||||
start/health/stop work and pidfiles are cleaned up.
|
||||
- [ ] Any platform differences are filed as a PR and reported.
|
||||
|
||||
## Notes
|
||||
|
||||
- The build host needs Go + Rust; the image does not (binaries are staged, not
|
||||
compiled on device). See `clawdie-iso/REQUIREMENTS.md`.
|
||||
- `/var/run` is tmpfs on FreeBSD — both rc.d scripts recreate their run dirs in
|
||||
prestart, so a fresh boot is the correct test.
|
||||
- Cost-mode _enforcement_ wiring is Priority 3 (Linux-doable, separate lane);
|
||||
this lane only confirms the baked `cost.mode` is surfaced by `colibri status`.
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Created:** 2026-06-14 (Sam & Hermes)
|
||||
**Status:** open for any agent to pick up
|
||||
**Replaces:** ad-hoc priorities from `ISO-INTEGRATION-PLAN.md` work lanes
|
||||
**Replaces:** ad-hoc ISO work-lane priorities
|
||||
|
||||
Round 2 audit is fully closed. All repos are green (164 tests, clippy clean,
|
||||
fmt clean). The three items below are the highest-leverage work toward getting
|
||||
|
|
@ -84,7 +84,7 @@ Gate 1 (passive service) is unproven.
|
|||
- `scripts/stage-colibri-iso.sh` — the staging script (dir creation, bin copy, rc.d install, rc.conf.sample generation)
|
||||
- `packaging/freebsd/colibri_daemon.in` — rc.d script
|
||||
- `docs/ISO-ACCEPTANCE-RUNBOOK.md` — acceptance commands to run on the booted image
|
||||
- `docs/ISO-INTEGRATION-PLAN.md` §Lane A — full plan with gap audit
|
||||
- `docs/FREEBSD-BUILD-LANE-HANDOFF.md` — step-by-step build/boot/validate handoff for the FreeBSD agent
|
||||
- clawdie-iso `build.sh` — `install_colibri_service()` already wires staging, user creation, and service enable
|
||||
- `hermes-bsd` `packaging/freebsd/hermes_daemon.in` + `README-FreeBSD.md` — Hermes rc.d service and setup steps
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue