docs: handoff — rc.d / release gate audit findings (Sam & Hermes)
Cross-repo audit after colibri PR #75 and clawdie-iso PR #59. Four items: 1. CRITICAL: clippy broken on colibri main (serve() returns io::Result, 4 test call sites don't handle it) 2. build.sh bare $(hostname) in rc.conf write 3. build.sh chmod 0755 too wide for colibri service dirs 4. Colibri staging script stale vs ISO repo version Includes context on what was already fixed and what's not a bug.
This commit is contained in:
Sam & Claude
parent
3a530c0744
commit
e4d392317d
2 changed files with 187 additions and 0 deletions
186
docs/HANDOFF-RC-D-RELEASE-GATE-AUDIT.md
Normal file
186
docs/HANDOFF-RC-D-RELEASE-GATE-AUDIT.md
Normal file
|
|
@ -0,0 +1,186 @@
|
|||
# Handoff — rc.d / Release Gate Audit
|
||||
|
||||
**Created:** 2026-06-15 (Sam & Hermes)
|
||||
**Status:** open — items below are independently pickable
|
||||
**Repos involved:** `colibri` (main `2addce9`), `clawdie-iso` (main `1569a04`)
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
After landing PR #75 (6 rc.d bug fixes) and pulling the clawdie-iso
|
||||
`feat/release-gate-whole-stack` PR #59, a cross-repo audit found four remaining
|
||||
issues. Two are in colibri, two are in clawdie-iso. The most urgent is a clippy
|
||||
breakage on colibri main that would block a release-channel build.
|
||||
|
||||
PR #59 delivered:
|
||||
|
||||
- **Release gate** — `check_release_gate()` in `build.sh` asserts all 4 repos
|
||||
(iso/colibri/zot/clawdie-ai) have clean working trees for
|
||||
`BUILD_CHANNEL=release`. Uses `git status --porcelain` (catches untracked
|
||||
files, not just modified).
|
||||
- **Product version 0.10.0** — ISO_VERSION is standalone; build-manifest.json
|
||||
records `colibri_commit`/`colibri_modified`.
|
||||
- **ISO repo staging script ahead of colibri repo** — the clawdie-iso copy of
|
||||
`scripts/stage-colibri-iso.sh` has rc.d validation checks, `colibri-mcp`
|
||||
staging, `provider.env.sample`, and already uses `colibri_daemon_cost_mode`
|
||||
and `$(/bin/hostname)`.
|
||||
|
||||
The CHANGELOG (0.10.0, line 34) explicitly references colibri PR #75:
|
||||
> Colibri daemon now handles SIGTERM (graceful socket cleanup + agent reaping
|
||||
> on `service stop`), refuses to steal a live socket, and fails closed if it
|
||||
> cannot bind a control socket (colibri PR #75).
|
||||
|
||||
---
|
||||
|
||||
## Work items
|
||||
|
||||
### Item 1 (CRITICAL): Fix clippy breakage on colibri main
|
||||
|
||||
**Repo:** colibri
|
||||
**Owner:** any Rust agent (Linux-doable)
|
||||
**Blocks:** release-channel ISO builds (release gate needs a clean repo; a
|
||||
clippy failure prevents validation confidence)
|
||||
|
||||
The live-host commits `b32c3ac` and `4517e13` (merged via PR #75) changed
|
||||
`socket::serve()` to return `io::Result<()>` instead of `()`. Four call sites
|
||||
in the client integration test were not updated:
|
||||
|
||||
```
|
||||
crates/colibri-client/tests/live_socket_check.rs:102
|
||||
crates/colibri-client/tests/live_socket_check.rs:153
|
||||
crates/colibri-client/tests/live_socket_check.rs:216
|
||||
crates/colibri-client/tests/live_socket_check.rs:319
|
||||
```
|
||||
|
||||
Each currently reads:
|
||||
|
||||
```rust
|
||||
socket::serve(server_state, shutdown).await;
|
||||
```
|
||||
|
||||
Clippy with `-D warnings` treats the unused `Result` as an error. Fix each call
|
||||
site:
|
||||
|
||||
```rust
|
||||
let _ = socket::serve(server_state, shutdown).await;
|
||||
```
|
||||
|
||||
Or, better, assert the result is Ok in tests that expect the server to start
|
||||
successfully.
|
||||
|
||||
**Verify:**
|
||||
|
||||
```sh
|
||||
cargo clippy --workspace --all-targets -- -D warnings
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Item 2 (Low): build.sh writes bare `$(hostname)` to rc.conf
|
||||
|
||||
**Repo:** clawdie-iso
|
||||
**Owner:** any agent
|
||||
**Location:** `build.sh:893`
|
||||
|
||||
```sh
|
||||
set_config_line "${MOUNT_POINT}/etc/rc.conf" 'colibri_daemon_host="$(hostname)"'
|
||||
```
|
||||
|
||||
The ISO staging script's `rc.conf.sample` already uses `$(/bin/hostname)`, and
|
||||
the colibri rc.d script uses `$(/bin/hostname)` as its default. But `build.sh`
|
||||
writes directly to `/etc/rc.conf` with the bare `$(hostname)`. During early
|
||||
boot, if PATH is not yet populated, the bare command could fail.
|
||||
|
||||
**Fix:**
|
||||
|
||||
```sh
|
||||
set_config_line "${MOUNT_POINT}/etc/rc.conf" 'colibri_daemon_host="$(/bin/hostname)"'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Item 3 (Low): build.sh sets `chmod 0755` on colibri service dirs
|
||||
|
||||
**Repo:** clawdie-iso
|
||||
**Owner:** any agent
|
||||
**Location:** `build.sh:874-877`
|
||||
|
||||
```sh
|
||||
chmod 0755 \
|
||||
"${MOUNT_POINT}/var/db/colibri" \
|
||||
"${MOUNT_POINT}/var/run/colibri" \
|
||||
"${MOUNT_POINT}/var/log/colibri"
|
||||
```
|
||||
|
||||
The rc.d script's prestart creates these directories as `0750` (owner + group
|
||||
only). The build ships them as `0755` (world-readable/traversable). On first
|
||||
boot, prestart's `install -d -m 0750` corrects this, but the initial image
|
||||
ships with wider permissions than intended.
|
||||
|
||||
**Fix:** Change `0755` to `0750`.
|
||||
|
||||
---
|
||||
|
||||
### Item 4 (Low): Colibri repo staging script is stale
|
||||
|
||||
**Repo:** colibri
|
||||
**Owner:** any agent (coordinate with Sam)
|
||||
|
||||
The colibri repo's `scripts/stage-colibri-iso.sh` is behind the clawdie-iso
|
||||
repo's copy. The ISO repo version has:
|
||||
|
||||
- `colibri-mcp` staging (line 64)
|
||||
- rc.d validation checks (lines 73-88) — catches stale colibri checkouts
|
||||
- `provider.env.sample` (lines 106-117)
|
||||
- `colibri_daemon_provider_env` in rc.conf.sample (line 101)
|
||||
- `$(/bin/hostname)` (line 102)
|
||||
|
||||
The colibri repo version lacks all of these. The ISO build uses its own copy, so
|
||||
this doesn't block builds, but the split-brain is a maintenance trap: an agent
|
||||
reading the colibri repo version would not know about the validation checks or
|
||||
`colibri-mcp`.
|
||||
|
||||
**Options:**
|
||||
|
||||
1. Sync the colibri repo version to match the ISO repo version (recommended).
|
||||
2. Delete it from the colibri repo and reference the ISO repo as canonical.
|
||||
3. Leave as-is and document that the ISO repo version is authoritative.
|
||||
|
||||
Option 1 is lowest-risk. The ISO repo version should be considered canonical
|
||||
since it's the one used in production builds.
|
||||
|
||||
---
|
||||
|
||||
## What we already fixed (PR #75, merged)
|
||||
|
||||
For reference, these were fixed in the colibri repo and are now on main:
|
||||
|
||||
1. `colibri_cost_mode` → `colibri_daemon_cost_mode` (rc.subr naming convention)
|
||||
2. Removed redundant socket `chmod 660` in rc.d poststart (Rust sets 0770)
|
||||
3. Removed unnecessary pidfile `chmod 644` in rc.d poststart
|
||||
4. Fixed ISO-SERVICE-LAYOUT.md stale permissions + wrong pidfile labels
|
||||
5. health_cmd now checks daemon response, not just connectivity
|
||||
6. rc.conf.sample uses `$(/bin/hostname)` consistently
|
||||
|
||||
The live host also contributed (via PR #75 branch):
|
||||
- SIGTERM handling in `main.rs` (graceful shutdown on `service stop`)
|
||||
- Liveness-aware socket cleanup in `socket.rs` (`clear_stale_socket`)
|
||||
- rc.d prestart no longer `rm -f` the socket (daemon handles it safely)
|
||||
|
||||
---
|
||||
|
||||
## Not bugs (noted for context)
|
||||
|
||||
- **clawdie installer's generated rc.d** (`crates/clawdie/src/platform.rs:102`)
|
||||
uses `daemon(8) -f -u` without pidfile/procname — `service status` won't work
|
||||
reliably for clawdie-installed hosts. This is a separate code path from the ISO
|
||||
rc.d and is the planned deployed-system service, not the live USB service.
|
||||
- **Release gate test** (`scripts/test-release-gate.sh`) extracts
|
||||
`assert_clean_repo` from build.sh using `sed`. This is fragile but works
|
||||
today; if the function formatting changes significantly, the test breaks.
|
||||
- **ISO rc.d validation** (clawdie-iso staging script lines 73-88) is excellent
|
||||
and should be kept updated as the rc.d script evolves. It currently checks for
|
||||
`colibri_daemon_cost_mode`, `colibri_daemon_provider_env`, no
|
||||
`-u ${colibri_daemon_user}`, and no socket rm in prestart.
|
||||
|
|
@ -12,6 +12,7 @@ A quick-reference guide to every document in this folder.
|
|||
| [`COLIBRI-TOKENOMICS-TRIFECTA.md`](COLIBRI-TOKENOMICS-TRIFECTA.md) | Strategic vision: useful tokens, cost-per-intelligence, measurement | All |
|
||||
| [`HEADROOM-SIDECAR.md`](HEADROOM-SIDECAR.md) | Optional `headroom-ai` tool-result compression sidecar | Agents |
|
||||
| [`INTEGRATION-LAYERED-SOUL.md`](INTEGRATION-LAYERED-SOUL.md) | How Colibri consumes `layered-soul` reviewed context today vs planned | Agents |
|
||||
| [`HANDOFF-RC-D-RELEASE-GATE-AUDIT.md`](HANDOFF-RC-D-RELEASE-GATE-AUDIT.md) | Post-PR-#75 audit: clippy fix, build.sh hostname/chmod, staging script sync | All agents |
|
||||
| [`ISO-ACCEPTANCE-RUNBOOK.md`](ISO-ACCEPTANCE-RUNBOOK.md) | Post-boot acceptance commands after staging Colibri into an ISO | Codex (FreeBSD) |
|
||||
| [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All |
|
||||
| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | **Current sprint**: ISO staging wiring, Pi spawn path, cost mode enforcement | All agents |
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue