feat(colibri): gate test-agent staging by build mode (Sam & Pi)

Add COLIBRI_STAGE_TEST_AGENT with dev/release defaults so validation builds can include colibri-test-agent while production/release operator USB images omit it by default. Keep poudriere guidance test-friendly and document binary roles in BUILD.md.\n\nValidation: sh -n build.sh scripts/stage-colibri-iso.sh live/operator-session/colibri-live-rebuild; ./scripts/check-format.sh; ./scripts/test-release-gate.sh; build.cfg default/override checks.

AGENTS.md

@@ -104,10 +104,12 @@ the ISO does **not** build Rust while the image is mounted.
   skill (§Colibri artifact preflight).
 - Staging layout (installed paths, rc.d, directory ownership) is owned by
   Colibri `docs/ISO-INTEGRATION-PLAN.md`.
-- Required by ISO preflight: `colibri-daemon`, `colibri`, `colibri-test-agent`,
-  and `colibri-mcp`.
-  `colibri-tui` is optional in staging code but desired for this USB target and
-  should be verified alongside the required binaries.
+- Required by ISO preflight for production images: `colibri-daemon`, `colibri`,
+  and `colibri-mcp`. `colibri-tui` is optional in staging code but desired for
+  this USB target and should be verified alongside the required binaries.
+  `colibri-test-agent` is a development/validation helper: stage it only for
+  explicit test builds with `COLIBRI_STAGE_TEST_AGENT=YES`, not for the default
+  release/prod operator USB.
 
 **Invariant:** do not `cargo clean` `/home/clawdie/ai/colibri` until the ISO
 preflight/build has consumed `/home/clawdie/ai/colibri/target/release`.

BUILD.md

@@ -81,15 +81,15 @@ Do not use that for operator-USB validation builds; the accepted USB runtime is
 Colibri-backed. The image includes:
 
 ```text
-/usr/local/bin/colibri-daemon
-/usr/local/bin/colibri
-/usr/local/bin/colibri-test-agent
+/usr/local/bin/colibri-daemon      # always-on Colibri control-plane daemon
+/usr/local/bin/colibri             # operator CLI for status, tasks, skills, and spawning
 /usr/local/bin/colibri-mcp         # MCP bridge for Zed/Claude Code/Cursor
-/usr/local/bin/colibri-tui              # if present in the artifact dir
-/usr/local/etc/rc.d/colibri_daemon
-/var/db/colibri
-/var/run/colibri
-/var/log/colibri
+/usr/local/bin/colibri-tui         # optional terminal dashboard if present in artifacts
+/usr/local/bin/colibri-test-agent  # dev/validation only when COLIBRI_STAGE_TEST_AGENT=YES
+/usr/local/etc/rc.d/colibri_daemon # FreeBSD service wrapper for colibri-daemon
+/var/db/colibri                    # persistent SQLite/state directory
+/var/run/colibri                   # runtime socket and PID directory
+/var/log/colibri                   # daemon logs
 ```
 
 The build also creates the `colibri` service user/group and writes rc.conf

build.cfg

@@ -115,6 +115,16 @@ COLIBRI_COST_MODE="${COLIBRI_COST_MODE:-smart}"
 # build host compiles it: (cd $ZOT_REPO && git checkout $ZOT_VERSION &&
 #   ZOT_BUILD_VERSION="${ZOT_VERSION:-v0.2.29}" && VERSION="${ZOT_BUILD_VERSION#v}" make build)
 COLIBRI_STAGE_AGENT="${COLIBRI_STAGE_AGENT:-YES}"
+# Development-only local fake-agent binary. Auto mode includes it for dev
+# builds and omits it from release/prod images; override with YES/NO for
+# explicit validation builds.
+COLIBRI_STAGE_TEST_AGENT="${COLIBRI_STAGE_TEST_AGENT:-auto}"
+if [ "${COLIBRI_STAGE_TEST_AGENT}" = "auto" ]; then
+    case "${BUILD_CHANNEL}" in
+        release|prod|production) COLIBRI_STAGE_TEST_AGENT="NO" ;;
+        *) COLIBRI_STAGE_TEST_AGENT="YES" ;;
+    esac
+fi
 ZOT_VERSION="${ZOT_VERSION:-v0.2.29}"
 ZOT_REPO="${ZOT_REPO:-/home/clawdie/ai/zot}"
 ZOT_ARTIFACT_DIR="${ZOT_ARTIFACT_DIR:-}"

build.sh

@@ -131,7 +131,7 @@ echo "    Pkg     : ${DEFAULT_PKG_BRANCH}"
 echo "    GPU     : ${GPU_DRIVER:-auto-detect}"
 echo "    NVIDIA universal : ${NVIDIA_UNIVERSAL:-NO}"
 echo "    Target  : ${TARGET:-baremetal}"
-echo "    Colibri : ${FEATURE_COLIBRI:-NO} (agent ${ZOT_VERSION:-} / stage ${COLIBRI_STAGE_AGENT:-YES})"
+echo "    Colibri : ${FEATURE_COLIBRI:-NO} (agent ${ZOT_VERSION:-} / stage ${COLIBRI_STAGE_AGENT:-YES} / test-agent ${COLIBRI_STAGE_TEST_AGENT:-NO})"
 echo ""
 
 # Name the output: clawdie-<freebsd-codename>-<version>.img, where the version is
@@ -332,7 +332,7 @@ preflight_colibri_artifacts() {
         echo "       Set COLIBRI_REPO=/path/to/colibri or FEATURE_COLIBRI=NO."
         exit 1
     fi
-    for _colibri_bin in colibri-daemon colibri colibri-test-agent colibri-mcp; do
+    for _colibri_bin in colibri-daemon colibri colibri-mcp; do
         if [ ! -x "${_resolved_colibri_artifact_dir}/${_colibri_bin}" ]; then
             echo "ERROR: Colibri release binary missing: ${_resolved_colibri_artifact_dir}/${_colibri_bin}"
             command -v cargo >/dev/null 2>&1 || \
@@ -342,6 +342,12 @@ preflight_colibri_artifacts() {
             exit 1
         fi
     done
+    if [ "${COLIBRI_STAGE_TEST_AGENT:-NO}" = "YES" ] && \
+       [ ! -x "${_resolved_colibri_artifact_dir}/colibri-test-agent" ]; then
+        echo "ERROR: Colibri test-agent staging requested, but binary is missing: ${_resolved_colibri_artifact_dir}/colibri-test-agent"
+        echo "       Set COLIBRI_STAGE_TEST_AGENT=NO for production images, or rebuild Colibri with cargo build --workspace --release."
+        exit 1
+    fi
 }
 
 resolve_zot_paths() {
@@ -870,6 +876,7 @@ install_colibri_service() {
         COLIBRI_REPO="${_resolved_colibri_repo}" \
         COLIBRI_ARTIFACT_DIR="${_resolved_colibri_artifact_dir}" \
         COLIBRI_STAGE_ENABLE="${COLIBRI_DAEMON_ENABLE:-YES}" \
+        COLIBRI_STAGE_TEST_AGENT="${COLIBRI_STAGE_TEST_AGENT:-NO}" \
         COLIBRI_COST_MODE="${COLIBRI_COST_MODE:-smart}" \
         "${SCRIPT_DIR}/scripts/stage-colibri-iso.sh" "${MOUNT_POINT}"
 
@@ -2425,6 +2432,7 @@ write_build_manifest "${USB_SHARE}/build-manifest.json"
     [ -n "${TELEGRAM_ADMIN_IDS:-}" ]    && echo "TELEGRAM_ADMIN_IDS=\"${TELEGRAM_ADMIN_IDS}\""
     [ -n "${FEATURE_TELEGRAM:-}" ]      && echo "FEATURE_TELEGRAM=\"${FEATURE_TELEGRAM}\""
     [ -n "${FEATURE_COLIBRI:-}" ]       && echo "FEATURE_COLIBRI=\"${FEATURE_COLIBRI}\""
+    [ -n "${COLIBRI_STAGE_TEST_AGENT:-}" ] && echo "COLIBRI_STAGE_TEST_AGENT=\"${COLIBRI_STAGE_TEST_AGENT}\""
     [ -n "${COLIBRI_DAEMON_ENABLE:-}" ] && echo "COLIBRI_DAEMON_ENABLE=\"${COLIBRI_DAEMON_ENABLE}\""
     [ -n "${COLIBRI_COST_MODE:-}" ]     && echo "COLIBRI_COST_MODE=\"${COLIBRI_COST_MODE}\""
     [ -n "${SSH_PUBLIC_KEY:-}" ]        && echo "SSH_PUBLIC_KEY=\"${SSH_PUBLIC_KEY}\""

docs/LIVE-COLIBRI-REBUILD.md

@@ -98,9 +98,10 @@ Expected outputs:
 ```text
 target/release/colibri-daemon
 target/release/colibri
-target/release/colibri-test-agent
 target/release/colibri-mcp
 target/release/colibri-tui
+# target/release/colibri-test-agent is installed only for explicit
+# COLIBRI_STAGE_TEST_AGENT=YES validation builds.
 ```
 
 ## Install rebuilt Colibri into the running USB
@@ -118,8 +119,10 @@ 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
+if [ "${COLIBRI_STAGE_TEST_AGENT:-NO}" = "YES" ]; then
+  mdo -u root install -m 0555 target/release/colibri-test-agent /usr/local/bin/colibri-test-agent
+fi
 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
 

docs/POUDRIERE-BUILD-SERVER.md

@@ -181,9 +181,11 @@ reappears here. Key facts:
 
 - `LICENSE= MIT` (per `colibri/Cargo.toml`; same as layered-soul).
 - `USES= cargo`; source from the Forgejo archive (tagged `v${DISTVERSION}`).
-- Ships 6 binaries: `clawdie`, `colibri`, `colibri-daemon`, `colibri-mcp`,
-  `colibri-test-agent`, `colibri-tui` — plus the `colibri_daemon` / `colibri_bridge`
-  rc.d services.
+- Ships runtime binaries: `clawdie`, `colibri`, `colibri-daemon`,
+  `colibri-mcp`, `colibri-tui` — plus the `colibri_daemon` / `colibri_bridge`
+  rc.d services. Keep `colibri-test-agent` available for poudriere validation
+  builds, but treat it as a development/test helper rather than a default
+  production ISO payload.
 - `CARGO_CRATES` is committed and kept in sync with `Cargo.lock` by
   `check-cargo-crates.sh` (colibri CI). `distinfo` is generated on the build host
   with `make makesum`.
@@ -242,9 +244,10 @@ This gives us:
 
 - `colibri`
 - `colibri-daemon`
-- `colibri-test-agent`
 - `colibri-mcp`
 - `colibri-tui` (optional in current raw-binary staging, desired for operator USB)
+- `colibri-test-agent` only in validation/dev package builds, not default
+  production images
 
 All with proper pkg metadata, upgradeable, with dependencies tracked.
 

docs/RELEASE-BUILD-RUNBOOK.md

@@ -96,9 +96,12 @@ cd ../clawdie-iso
 ```sh
 ls -l ../colibri/target/release/colibri-daemon \
       ../colibri/target/release/colibri \
-      ../colibri/target/release/colibri-test-agent \
       ../colibri/target/release/colibri-mcp \
       ../zot/bin/zot
+
+# Development/validation helper only; default release/prod images omit it.
+[ "${COLIBRI_STAGE_TEST_AGENT:-NO}" != "YES" ] || \
+  ls -l ../colibri/target/release/colibri-test-agent
 # colibri-tui is optional (staged if present)
 ```
 

live/operator-session/bootstrap.html

@@ -91,7 +91,7 @@
           <li><code>colibri-daemon</code> — agent supervisor, skills catalog, Glasspane state machine</li>
           <li><code>colibri-tui</code> — live ratatui dashboard (agent states, spawn/kill, sessions)</li>
           <li><code>colibri-mcp</code> — MCP bridge for Zed, Claude Code, Cursor, and other MCP clients</li>
-          <li><code>colibri-test-agent</code> — local no-network Colibri launch check</li>
+          <li><code>colibri-test-agent</code> — optional dev/validation helper when explicitly staged</li>
           <li>Firefox browser</li>
           <li>Tailscale package (needs auth key)</li>
           <li><code>pi</code> coding agent harness (npm global)</li>
@@ -122,6 +122,7 @@ colibri list-tasks         # Coordination board
 colibri list-skills        # Skills catalog
 colibri-mcp tools          # MCP bridge, read-only by default
 COLIBRI_MCP_WRITE=1 colibri-mcp tools  # trusted write-capable profile
+[ -x /usr/local/bin/colibri-test-agent ] && \
   colibri spawn-local /usr/local/bin/colibri-test-agent --session-id local-check
 colibri create-task --title "check network"
 colibri list-tasks --status queued</pre>

live/operator-session/colibri-live-rebuild

@@ -16,7 +16,10 @@ REF=""
 BUILD_DIR="/home/clawdie/ai/colibri-build"
 SEED_SRC="/home/clawdie/ai/colibri" # git-backed source staged on the image
 REMOTE="https://code.smilepowered.org/clawdie/colibri.git"
-BINS="colibri-daemon colibri colibri-test-agent colibri-mcp colibri-tui"
+BINS="colibri-daemon colibri colibri-mcp colibri-tui"
+if [ "${COLIBRI_STAGE_TEST_AGENT:-NO}" = "YES" ]; then
+  BINS="${BINS} colibri-test-agent"
+fi
 
 usage() { echo "usage: colibri-live-rebuild [--ref <branch|commit>] [--build-dir <path>]"; exit "${1:-0}"; }
 while [ $# -gt 0 ]; do

scripts/stage-colibri-iso.sh

@@ -22,6 +22,7 @@ COLIBRI_REPO=${COLIBRI_REPO:-"/home/clawdie/ai/colibri"}
 COLIBRI_ARTIFACT_DIR=${COLIBRI_ARTIFACT_DIR:-"${COLIBRI_REPO}/target/release"}
 COLIBRI_STAGE_ENABLE=${COLIBRI_STAGE_ENABLE:-YES}
 COLIBRI_STAGE_INCLUDE_TUI=${COLIBRI_STAGE_INCLUDE_TUI:-1}
+COLIBRI_STAGE_TEST_AGENT=${COLIBRI_STAGE_TEST_AGENT:-NO}
 COLIBRI_COST_MODE=${COLIBRI_COST_MODE:-smart}
 
 BIN_DIR="${DESTDIR}/usr/local/bin"
@@ -60,9 +61,12 @@ mkdir -p "${BIN_DIR}" "${RC_DIR}" "${ETC_DIR}" "${NEWSYSLOG_DIR}" "${DB_DIR}" "$
 
 copy_bin colibri-daemon
 copy_bin colibri
-copy_bin colibri-test-agent
 copy_bin colibri-mcp
 
+if [ "${COLIBRI_STAGE_TEST_AGENT}" = "YES" ]; then
+    copy_bin colibri-test-agent
+fi
+
 if [ "${COLIBRI_STAGE_INCLUDE_TUI}" != "0" ] && [ -x "${COLIBRI_ARTIFACT_DIR}/colibri-tui" ]; then
     copy_bin colibri-tui
 fi
@@ -150,7 +154,6 @@ Runtime validation:
 
   service colibri_daemon start
   colibri status
-  colibri spawn-local /usr/local/bin/colibri-test-agent --session-id iso-check
   colibri create-task --title "iso check"
   colibri list-tasks --status queued
   colibri-mcp tools
@@ -166,4 +169,5 @@ Staged Colibri into ${DESTDIR}
   rc.d     : ${RC_SOURCE}
   enable   : ${COLIBRI_STAGE_ENABLE}
   cost     : ${COLIBRI_COST_MODE}
+  test bin : ${COLIBRI_STAGE_TEST_AGENT}
 EOF

skills/iso-build/SKILL.md

@@ -150,14 +150,19 @@ cargo build --workspace --release
 
 ls -lh target/release/colibri-daemon \
        target/release/colibri \
-       target/release/colibri-test-agent \
        target/release/colibri-mcp
 
 file target/release/colibri-daemon \
      target/release/colibri \
-     target/release/colibri-test-agent \
      target/release/colibri-mcp
 
+# Development/validation helper. Required only when explicitly building with
+# COLIBRI_STAGE_TEST_AGENT=YES; default release/prod images omit it.
+if [ "${COLIBRI_STAGE_TEST_AGENT:-NO}" = "YES" ]; then
+  ls -lh target/release/colibri-test-agent
+  file target/release/colibri-test-agent
+fi
+
 # Optional in the staging script, but desired for this operator USB target.
 if [ -x target/release/colibri-tui ]; then
   ls -lh target/release/colibri-tui