Colibri

Colibri is the Clawdie-AI event and control fabric. It normalizes what the agent runtime and the host already emit — Pi events, watchdog status, cross-host run manifests, runtime inventories — into structured inputs that update Clawdie’s task and control state.

Colibri is a coordination layer, not a new runtime and not a dashboard. Agent reasoning happens in Pi; host safety stays in the watchdog; privileged operations stay in hostd. Colibri reads their outputs and gives the operator one coherent control state instead of many ad-hoc surfaces.

Note

The ingestion modules described here are implemented and tested (src/colibri-*.ts). The wider simplification — collapsing legacy multi-runner orchestration onto Pi — now continues on main behind the proof gates. Source plan: doc/COLIBRI-PI-CONTROL-PLAN.md.

What Colibri is — and isn’t

Colibri grew out of evaluating a Linux terminal multiplexer (Herdr) as a control surface. The conclusion: Herdr cannot be the cross-host bus or the FreeBSD runtime (it is Linux/macOS-only and AGPL-licensed). So Colibri is our own fabric, and the agent runtime is Pi only.

• It is a normalizer and aggregator of structured feeds — Pi JSONL events, watchdog status, run manifests, runtime inventories — into Clawdie control state.
• It is not a second agent runtime, a replacement for the watchdog or hostd, or a bundle of third-party operator tools.
• Herdr stays an optional, Linux-side operator dashboard / terminal surface — never a FreeBSD dependency, and never vendored into Clawdie.

Core decisions

• Use Pi as the only agent runtime.
• Keep Herdr as an optional Linux-side surface — not a cross-host message bus and not the FreeBSD runtime.
• Colibri is the Clawdie-AI control/event fabric name.
• Do not vendor or copy Herdr code; do not port Herdr to FreeBSD.
• Do not delete existing orchestration until the replacement loop is proven.

Component map

Pi        — agent reasoning/runtime; emits structured JSON/SDK events
Colibri   — Clawdie-AI event/control fabric; consumes Pi events + host feeds,
            updates Clawdie task/control state
watchdog  — FreeBSD runtime governor (keep); its status socket is a Colibri input
hostd     — privileged host operations: bastille, zfs, pf, services, packages (keep)
Herdr     — optional Linux operator dashboard/terminal surface
doctor / pi-profile — existing watchdog-status consumers; must keep working

Ingestion modules

Colibri’s implemented surface is a set of pure parsers/normalizers plus one read-only socket client. With the exception of the host-status reader’s socket, they have no FreeBSD dependency, so Linux agents can develop and test them.

Module	Purpose	Schema / source
colibri-pi-events.ts	Normalize Pi --mode json JSONL into typed events	flat top-level type records
colibri-pi-run.ts	Summarize a whole Pi run (counts, tools, usage)	pi-jsonl
colibri-host-status.ts	Read the watchdog IPC socket into a status record	watchdog-socket
colibri-run-manifest.ts	Validate cross-host inter-agent run manifests	clawdie.interagent.run-manifest.v1
colibri-runtime-inventory.ts	Validate runtime inventories; compute drift	clawdie.runtime-version-inventory.v1

Pi event ingestion

colibri-pi-events.ts turns Pi’s --mode json output — flat, newline-framed JSON records — into a normalized ColibriPiEvent union. The first stdout line is the session header ({"type":"session","id":…,"cwd":…}); subsequent lines are events. parsePiJsonLine / parsePiJsonLines are total and never throw — malformed lines surface as parse errors rather than crashing.

Normalized event kinds:

pi.session_started     pi.message_text_delta   pi.tool_finished
pi.agent_started       pi.message_finished     pi.queue_updated
pi.agent_finished      pi.tool_started         pi.compaction_started/finished
pi.turn_started        pi.tool_updated         pi.retry_started/finished
pi.turn_finished       pi.message_started      pi.unknown

colibri-pi-run.ts rolls a full run up with summarizeColibriPiRun(raw), which returns a ColibriPiRunSummary: sessionId, cwd, per-kind eventCounts, toolNames, parseErrorCount, textDeltaChars, finalAssistantText, and runtimeUsage. buildColibriPiTaskResult maps that to the values Clawdie records per run — tokensUsed, output, actualProvider, actualModel, costTotalUsd — which line up with the control plane’s actual_* runtime observability fields.

Host-status ingestion

colibri-host-status.ts connects to the watchdog Unix socket, sends {"cmd":"status"}, reads the newline-framed {ok,data} reply, and normalizes it into a ColibriHostStatus record:

source: 'watchdog-socket'
mode, throttled, freeMemoryMB, activeJails, queuedGroups, controlplaneStatus

It mirrors the wire protocol already used by doctor.ts, is additive and read-only (a new consumer alongside doctor, not a change to the watchdog), and never throws — every failure resolves to { ok: false, error }.

Inter-agent run manifests

Cross-host coordination (for example, the network-throughput playground) is exchanged as structured manifests, not free-form chat or raw captures. colibri-run-manifest.ts validates the clawdie.interagent.run-manifest.v1 schema with parseColibriRunManifest / parseColibriRunManifestJson and renders a compact <colibri-run-manifest> text block via summarizeColibriRunManifest.

Fields: test_id, role, host, agent?, started_at, ended_at?, protocols, network, artifacts, summary, raw_transfer_required, notes. Raw pcaps stay out of git; the manifest is the structured handoff.

Runtime version inventory and drift

colibri-runtime-inventory.ts validates the clawdie.runtime-version-inventory.v1 schema (host, os, node?, npm?, pi?, npm_prefix?, package_manager?, iso_npm_globals_pin, notes). Each host emits its own inventory; buildRuntimeDriftReport compares them against a target (default Node major 24, optional pinned Pi version) and returns which hosts drift on Node, Pi, a missing Pi, or an ISO npm-globals pin. summarizeRuntimeDriftReport renders a <colibri-runtime-drift> block.

Relationship to the watchdog

The watchdog is load-bearing runtime safety, not a dashboard. Colibri reads its socket as an input; it does not own, replace, or merge it. src/watchdog.ts:

• reads FreeBSD free memory via sysctl vm.stats.vm.v_free_count
• throttles jail-queue concurrency under memory pressure
• exposes run modes (auto, slow, fast, permanent)
• answers structured IPC: {"cmd":"status"} and {"cmd":"mode","value":…}

doctor and pi-profile are existing consumers of that status and must keep working — they are hard gates, not deletion targets.

Proof gates before removing legacy paths

No legacy runner or status code is removed until all of these hold:

1. Pi runs an end-to-end task on Linux.
2. Pi runs an end-to-end task on FreeBSD.
3. Pi JSON/SDK events map into Clawdie task/activity state.
4. A DeepSeek lane works through Pi on Linux using --mode json.
5. Colibri consumes watchdog status without breaking doctor or pi-profile.
6. Herdr can display/launch the Linux operator workflow without becoming a required FreeBSD dependency.
7. The network-throughput coordination test has produced structured manifests from at least two hosts.

Runtime drift and version sync

Colibri is also the coordination layer for runtime hygiene:

Node: 24.x on Linux and FreeBSD
Pi:   pinned per host inventory, not assumed from PATH
ISO npm globals: pinned in the ISO repo, not fetched from moving latest tags

Each host emits a small inventory manifest; the coordinator compares manifests before upgrades; FreeBSD package actions stay locally authorized and rollback-aware. The supporting skills are pi-provider-smoke (validates a provider lane through Pi --mode json) and runtime-version-sync (inventories and aligns Node, Pi, npm globals, and ISO pins across hosts).

Non-goals

• No Herdr FreeBSD port; no Herdr vendoring.
• No deletion of the watchdog or hostd.
• No replacement of FreeBSD local safety with Linux-side orchestration.
• No broad agent-backend deletion before caller inventory and proof gates.

References

• Control Plane — the orchestration layer Colibri feeds.
• Provider Fallback — provider switching that produces the effective_* vs actual_* divergence Colibri records.
• doc/COLIBRI-PI-CONTROL-PLAN.md — the source plan and phase breakdown.
• doc/INTERAGENT-RUN-CONTRACT.md — the inter-agent run-manifest contract.