diff --git a/README.md b/README.md index 2070835..6626b54 100644 --- a/README.md +++ b/README.md @@ -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`. diff --git a/docs/FREEBSD-BUILD-LANE-HANDOFF.md b/docs/FREEBSD-BUILD-LANE-HANDOFF.md new file mode 100644 index 0000000..ff447cd --- /dev/null +++ b/docs/FREEBSD-BUILD-LANE-HANDOFF.md @@ -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 +# /clawdie-iso +# /colibri +# /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 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-.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`. diff --git a/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md b/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md index 75abe93..52aeceb 100644 --- a/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md +++ b/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md @@ -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