Validate Shepherd services on FreeBSD

docs/PROGRESS.md

@@ -1266,3 +1266,86 @@ Next recommended step:
 2. carry forward the separate real-checkout runtime blocker for later integration work:
   - investigate the `leave-on-EPIPE` failure in `./pre-inst-env guix --version`
 3. continue using `/frx/store` rather than `/gnu/store` for future FreeBSD integration experiments when a persistent store root is required
+
+## 2026-04-01 — Phase 4.1 completed: Shepherd built and validated as a regular FreeBSD service manager
+
+Completed work:
+
+- added a reproducible local Guile Fibers build harness:
+  - `tests/shepherd/build-local-guile-fibers.sh`
+- added a reproducible local Shepherd build harness:
+  - `tests/shepherd/build-local-shepherd.sh`
+- added a runnable multi-service Shepherd validation harness for FreeBSD:
+  - `tests/shepherd/run-freebsd-shepherd-service-prototype.sh`
+- wrote the Phase 4.1 report:
+  - `docs/reports/phase4-freebsd-shepherd-service.md`
+- ran the service-management prototype successfully and captured metadata under:
+  - `/tmp/freebsd-shepherd-service-metadata.txt`
+
+Important findings:
+
+- the current FreeBSD path now has a working local Shepherd build based on:
+  - local fixed Guile
+  - locally installed Guile Fibers `1.4.2`
+  - Shepherd `1.0.9`
+- Shepherd build/install required one concrete FreeBSD-specific toolchain adaptation:
+  - `SED=/usr/local/bin/gsed`
+  because the install phase edits wrapper scripts using GNU `sed -i` syntax that base FreeBSD `sed` does not accept
+- at runtime, Shepherd reports:
+  - `System lacks support for 'signalfd'; using fallback mechanism.`
+  but the fallback path works correctly for supervision on this host
+- the prototype successfully validated all requested regular-service capabilities:
+  - start/stop via `herd`
+  - dependency handling
+  - status monitoring
+  - crash/respawn behavior
+  - privilege-aware execution
+- the concrete service set used for validation included:
+  - an unprivileged heartbeat logger
+  - a loopback HTTP service
+  - a dependent file-monitor service
+  - a crash-once respawn test service
+- observed metadata confirmed:
+  - `logger_running=yes`
+  - `web_running=yes`
+  - `monitor_running=yes`
+  - `crashy_running=yes`
+  - `logger_uid=65534` (`nobody`)
+  - `http_response=shepherd-freebsd-ok`
+  - `monitor_detected=detected`
+  - `crashy_counter=2`
+
+Current assessment:
+
+- Phase 4.1 is now satisfied on the current FreeBSD prototype track
+- Shepherd is no longer just a theoretical later step; it now builds and supervises multiple services correctly on the host when paired with the fixed local Guile stack
+- the next question is no longer “can Shepherd run on FreeBSD at all?” but “what is the best FreeBSD init-integration strategy for it on this prototype path?”
+
+Recent commits:
+
+- `e380e88` — `Add FreeBSD Guile verification harness`
+- `cd721b1` — `Update progress after Guile verification`
+- `27916cb` — `Diagnose Guile subprocess crash on FreeBSD`
+- `02f7a7f` — `Validate local Guile fix on FreeBSD`
+- `4aebea4` — `Add native GNU Hello FreeBSD build harness`
+- `c944cdb` — `Validate Guix builder phases on FreeBSD`
+- `0a2e48e` — `Validate GNU which builder phases on FreeBSD`
+- `245a47d` — `Document gaps to real Guix FreeBSD builds`
+- `d62e9b0` — `Investigate Guix derivation generation on FreeBSD`
+- `c0a85ed` — `Build local Guile-GnuTLS on FreeBSD`
+- `15b9037` — `Build local Guile-Git on FreeBSD`
+- `47d31e8` — `Build local Guile-JSON on FreeBSD`
+- `d82195b` — `Advance Guix checkout on FreeBSD`
+- `9bf3d30` — `Document FreeBSD syscall mapping`
+- `7621798` — `Prototype FreeBSD jail build isolation`
+- `d65b2af` — `Prototype FreeBSD build user isolation`
+- `e404e2e` — `Prototype FreeBSD store management`
+- `eb0d77c` — `Adapt GNU build phases for FreeBSD`
+- `d47dc9b` — `Prototype FreeBSD package definitions`
+
+Next recommended step:
+
+1. complete Phase 4.2 by prototyping how Shepherd should be launched and stopped through FreeBSD init conventions while validating boot/shutdown dependency ordering for essential services
+2. after that, bridge Shepherd to key FreeBSD service concepts such as rc.d management, loopback/network configuration, filesystem setup, and temporary user/group administration
+3. continue carrying the separate real-checkout runtime blocker for later integration work:
+  - investigate the `leave-on-EPIPE` failure in `./pre-inst-env guix --version`