From 09259394b9e4bd234be101ed5d54020b1bb98248 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Wed, 27 May 2026 16:06:40 +0200 Subject: [PATCH] docs: add corrected shared cutover plan (Sam & Claude) Verified, shared version of the cutover orchestration plan in docs/, correcting the .hermes/plans draft against the actual repos: - Kill the fabricated clawdie-ai crates/colibri-daemon (no crates/ dir exists there; the real daemon is Unix-socket in the colibri repo, not axum/HTTP). - Fix baseline to 160dd11 (65 tests pass/0 fail, clippy -D warnings clean); eb37784 was not clippy-clean. - Reaffirm the Herdr boundary: Linux/macOS display/remote plane, no Herdr on FreeBSD; colibri-glasspane is the native answer (Lane 2 reframed). - Correct ownership: Claude=domedog=Linux, Codex=osa=FreeBSD, Hermes=debby=Linux. - Surface the Postgres coupling as an explicit open decision, not a given. - Downgrade the overclaimed debby<->domedog herdr smoke test to "not yet done." Leaves the .hermes draft untouched; marked DRAFT/PROPOSED pending ratification. Co-Authored-By: Claude Opus 4.7 --- docs/COLIBRI-CUTOVER-PLAN.md | 164 +++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 docs/COLIBRI-CUTOVER-PLAN.md diff --git a/docs/COLIBRI-CUTOVER-PLAN.md b/docs/COLIBRI-CUTOVER-PLAN.md new file mode 100644 index 0000000..fe654be --- /dev/null +++ b/docs/COLIBRI-CUTOVER-PLAN.md @@ -0,0 +1,164 @@ +# Colibri Cutover Plan — clawdie-ai (TS) → Colibri (Rust) + +**Status:** DRAFT / PROPOSED — 27.maj.2026. Shared, verified version of the +orchestration plan. Supersedes the working draft `.hermes/plans/2026-05-27-colibri-cutover.md` +(see "Corrections from the draft" below). + +**Goal:** progressively replace the clawdie-ai TypeScript control plane with the +Colibri Rust core as the FreeBSD system service, with the FreeBSD-native +supervision boundary intact and each step proven before takeover. + +--- + +## Corrections from the `.hermes` draft + +The earlier draft asserted several things that don't match the repos. Fixed here: + +| Draft claim | Reality (verified 27.maj) | +|-------------|---------------------------| +| `clawdie` repo has `crates/colibri-daemon/` (event.rs/state.rs/ingestor.rs/snapshot.rs, **axum HTTP**) | `clawdie-ai` has **no `crates/` dir**. The Rust daemon lives only in the **`colibri` repo**, and it is **Unix-socket** (`socket.rs` `UnixListener`), not HTTP. | +| Baseline `eb37784` — "62 tests, clippy-clean" | `eb37784` carried the `collapsible_match` clippy errors (fixed in `5d45a0f`). Accurate baseline: **`160dd11` — 65 tests passed/0 failed, `clippy -D warnings` clean**. | +| "`herdr --remote` debby↔domedog already smoke-tested" | Only a one-off domedog→debby attach occurred. The **hub direction (debby→domedog) is not tested** — herdr client isn't installed on debby yet (see `HERDR-HUB-RUNBOOK.md`). | +| Herdr as "drop-in for Clawdie's tmux-based agent **execution**" on FreeBSD | Contradicts the settled boundary (`MIGRATION-INVENTORY.md` §3, `862204c`): **no Herdr on FreeBSD**. Herdr is a Linux/macOS **display/remote** client; `colibri-glasspane` is the FreeBSD-native supervision. Reframed in Lane 2. | +| Owner "Claude (osa, FreeBSD validation)" | **Claude = domedog = Linux. Codex = osa = FreeBSD. Hermes = debby = Linux.** FreeBSD validation/build is Codex's lane. | + +--- + +## Verified current state (27.maj.2026) + +| Repo | Branch | Baseline | Notes | +|------|--------|----------|-------| +| `colibri` | main | `160dd11` | 65 tests pass / 0 fail; `clippy -D warnings` clean; 7 crates | +| `clawdie-ai` | main | `169bee2` | TS control plane (the cutover *source*); **no Rust crates** | +| `clawdie-iso` | main | `b9803d8` | has a Colibri dependency section in `AGENTS.md` | +| `herdr` | main | `ede2059` *(per Hermes; not verified from domedog)* | Linux/macOS display client | + +### What actually exists in Colibri today + +- **Rust workspace, 7 crates** (`colibri-contracts`, `-deepseek`, `-runtime`, + `-glasspane`, `-daemon`, `-client`, `-glasspane-tui` + root bins). Builds and + tests green on Linux (debby/domedog) and FreeBSD (osa). +- **`colibri-daemon`** — always-on service over a **Unix socket** (newline-JSON): + `config/daemon/session/socket/spawner`. Not HTTP. +- **`colibri-glasspane`** — FreeBSD-native agent supervision; 5-state machine + derived from Pi `--mode json` events; `clawdie.glasspane.snapshot.v1`. +- **`colibri-client`** — typed Unix-socket client; live socket smoke test. +- Proof gates 1–6 green per `MIGRATION-INVENTORY.md`; gate 7 (multi-host + coordination) pending. + +### The TS side being retired (in `clawdie-ai`) + +Contract sources already mirrored into Rust: `src/colibri-pi-events.ts`, +`colibri-run-manifest.ts`, `colibri-runtime-inventory.ts`, `colibri-host-status.ts`, +`colibri-pi-run.ts`. Load-bearing runtime kept until cutover: `agent-runner.ts` +(the Pi host runner), `jail-exec-runner.ts` (`jailPi`), `watchdog.ts`, `hostd`. + +--- + +## Open decisions (resolve before the lanes they gate) + +1. **Coordination-core storage (gates Lane 1 / Phase 3).** The draft assumed + "Postgres-backed (reuse clawdie-ai's `system_ops` DB)." That couples the lean + cross-platform Colibri core to clawdie-ai's existing schema — convenient for + dual-run parity, but the opposite of a clean-room cutover and a heavy dep for + a "single small binary." **Decide explicitly:** (a) reuse `system_ops` + Postgres, (b) Colibri-owned Postgres, or (c) embedded store (SQLite) with a + Postgres adapter. Default lean choice: (c) unless dual-run parity needs (a). +2. **Herdr boundary (gates Lane 2).** Reaffirmed: Herdr stays Linux/macOS + display/remote only. If anyone wants Herdr in the FreeBSD execution path, + that reopens `MIGRATION-INVENTORY.md` §3 and needs an explicit reversal. + +--- + +## Lane 1 — Colibri core + +**Owner:** Hermes (debby/Linux) → Codex (osa/FreeBSD validation). + +- **T1.1 Stabilize baseline.** `cargo test --workspace && cargo clippy + --workspace --all-targets -- -D warnings`; record exact counts; commit any + fmt/clippy fixes. *(Green at `160dd11`.)* +- **T1.2 Phase 3 — coordination core.** Task board with explicit lifecycle + (queued→claimed→started→done/failed); agents-as-teammates; skills catalog. + **Blocked on Open Decision #1 (storage).** +- **T1.3 Phase 4 — execution & scheduling.** cron/interval/one-time scheduler; + Pi engine integration via the events parser; Telegram-intake compatibility. +- **T1.4 Phase 5 — cache-first prompt discipline.** Deterministic 3-region + prompt assembler; cost modes (fast/smart/max); visible escalation. +- **T1.5 Phase 6 — gated cutover.** Replace TS control-plane paths only after + proof gates pass; **separate deprecation PR per path**. +- **FreeBSD validation (each step):** push → Codex on osa runs `cargo test` on + FreeBSD 15 → record `rustc --version`, `freebsd-version`, exact output. + +*(Phase numbers per `clawdie-ai/doc/COLIBRI-CONTROLPLANE-PLAN.md`; distinct from +the migration phases in `MIGRATION-INVENTORY.md`.)* + +## Lane 2 — Herdr compatibility (Linux display plane) + +**Owner:** Hermes (debby) + Codex (osa, for the FreeBSD-side socket). + +Herdr consumes Colibri's socket/snapshot API as a **display/remote client**; +it is not an execution layer and not on FreeBSD. + +- **T2.1 Snapshot API consumption.** Verify a Herdr-Linux client can read + `clawdie.glasspane.snapshot.v1` over the daemon Unix socket (and the future + HTTP/SSE transport when it lands). +- **T2.2 Remote attach over Tailscale.** Complete the debby→domedog hub attach + (install herdr client on debby; `herdr --remote domedog-ts-herdr`). Per + `HERDR-HUB-RUNBOOK.md`. *(Not yet done — supersedes the draft's "already + smoke-tested.")* +- **T2.3 Compatibility manifest.** Produce `herdr-clawdie-compat.v1`: protocol + version, socket/snapshot schema, transport, known gaps. +- **Gate:** compat manifest signed → IMG deployment unblocked. + +## Lane 3 — ISO build chain + +**Owner:** Hermes (coordination) → Codex (osa, FreeBSD build). + +- **T3.1 Assess ISO state.** Review the operator-USB round scope; check the + Colibri dependency section in `clawdie-iso/AGENTS.md`. +- **T3.2 Colibri artifact integration.** Define which Colibri binary the ISO + bundles; FreeBSD `rc.d` service for the daemon; firstboot starts Colibri + alongside clawdie-ai **during the dual-run transition only**. +- **T3.3 Build handoff.** ISO handoff doc for Codex: exact Colibri commit hash, + target triple (`x86_64-unknown-freebsd`), TLS = rustls, build flags. + +## Lane 4 — Gradual phase-out (clawdie-ai TS → Colibri Rust) + +**Owner:** shared (Hermes + Claude + Codex + Sam). Conservative, reversible. + +- **T4.1 Dual-run (passive).** Colibri daemon runs beside clawdie-ai on FreeBSD; + both consume Pi JSONL; compare state snapshots. No takeover. +- **T4.2 State-parity gates.** Task-board state, agent lifecycle transitions, + and watchdog host-status ingestion all match between the TS control plane and + the Rust daemon. +- **T4.3 Read-only takeover.** Colibri serves snapshots; clawdie-ai's TS UI reads + from the Colibri API. Prove the Rust daemon is the source of truth. +- **T4.4 Write takeover.** Colibri owns scheduling + agent dispatch; clawdie-ai + reduced to Telegram intake. +- **T4.5 Full cutover.** clawdie-ai control plane stopped; Colibri `rc.d` service + is the sole control plane; clawdie-ai service disabled. Watchdog/`hostd` + FreeBSD safety stays locally authoritative throughout. + +--- + +## Dependency graph + +```text +Lane 1 (Colibri core) ───────────────────────────┐ + ├──→ Lane 4 (phase-out) +Lane 2 (Herdr display compat) ──→ IMG unblocked ──┤ + │ +Lane 3 (ISO build) ───────────→ Colibri in ISO ───┘ +``` + +## Conventions + +- Commit prefixes `feat:`/`fix:`/`docs:`/`refactor:`/`test:`. +- Attribution `(Sam & Hermes)` / `(Sam & Claude)` / `(Sam & Codex)`. +- Cross-repo references in the commit body when relevant. + +## Next actions + +1. Resolve Open Decision #1 (coordination-core storage) — unblocks Lane 1 T1.2. +2. Complete Lane 2 T2.2 (debby→domedog herdr attach) per the runbook. +3. Reconcile or retire the `.hermes` draft against this version.