colibri/docs/ISO-ACCEPTANCE-RUNBOOK.md

ISO Acceptance Runbook — Colibri Service

Use this after Colibri has been staged into an ISO/image root and booted on FreeBSD.

0. Pre-flight

freebsd-version
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

Expected:

• colibri user exists.
• binaries are executable.
• rc.d script is executable.
• service is enabled for ISO acceptance, or can be started manually.

1. Start service

service colibri_daemon start
sleep 2
service colibri_daemon status

Expected:

• service reports running.
• /var/run/colibri/colibri.sock exists.
• /var/db/colibri/ exists and is owned by the service user.
• /var/log/colibri/daemon.log exists or is created on first output.

Triage:

tail -100 /var/log/colibri/daemon.log
ls -la /var/run/colibri /var/db/colibri
sockstat -u | grep colibri || true

2. Operator status

colibri status

Expected fields:

daemon/version/host
paths.data_dir
paths.db_path
paths.socket_path
cost.mode
cost.session_max_bytes
cost.max_uncompacted_turns
sessions
agents / agent_list
panes
tasks
scheduler.interval_secs

Confirm cost.mode matches colibri_daemon_cost_mode from rc.conf.

3. Task board check

colibri create-task --title "iso check" --description "direct CLI task"
colibri list-tasks --status queued

Expected: list contains iso check with status queued.

4. Scheduler/intake check

colibri intake-task \
  --title "iso intake check" \
  --description "scheduler should persist this" \
  --capability freebsd

# scheduler tick is currently 30s
sleep 35
colibri list-tasks --status queued

Expected: list contains iso intake check.

5. Glasspane check

colibri snapshot

Expected: valid JSON snapshot. It may have no panes before an agent is spawned.

Optional local sample-agent check if colibri-test-agent is included:

colibri spawn-local /usr/local/bin/colibri-test-agent --session-id iso-check
sleep 4
colibri snapshot

Expected: a pane transitions through idle/working/blocked/done.

6. Stop service

service colibri_daemon stop
sleep 2
service colibri_daemon status || true
ls -l /var/run/colibri/colibri.sock || true
ls -l /var/db/colibri/colibri.sqlite*

Expected:

• daemon exits.
• socket is removed or no longer connectable.
• SQLite DB remains.

7. Restart persistence

service colibri_daemon start
sleep 2
colibri list-tasks --status queued

Expected: tasks created before stop are still present.

8. Live desktop acceptance

Run when the test machine is available:

boot ISO from USB
log into XFCE
launch Zed
run colibri status from terminal
launch colibri-tui if included

Expected:

• XFCE starts.
• Zed launches with GPU behavior acceptable for our requirements.
• Colibri service is running without the TypeScript control service.
• CLI/TUI remain responsive.

Pass criteria

The ISO candidate passes Colibri service acceptance when:

• rc.d starts/stops the daemon cleanly.
• colibri status exposes paths, cost, scheduler, tasks, panes.
• direct tasks persist to SQLite.
• intake tasks drain on scheduler tick.
• glasspane snapshot is reachable.
• restart preserves SQLite state.
• no TypeScript control service is required for core supervision.