diff --git a/.agent-handoff.md b/.agent-handoff.md deleted file mode 100644 index e56f566..0000000 --- a/.agent-handoff.md +++ /dev/null @@ -1,268 +0,0 @@ -# Agent Handoff Protocol - -Standardized protocol for transferring context between agents in the Colibri multiagent development cycle. - -## Before Handoff - -- [ ] All tests pass (`cargo test --workspace`) -- [ ] Relevant proof gates documented in `docs/PROOF-GATES.md` -- [ ] Cross-platform validation recorded (osa/domedog/debby) -- [ ] Next agent's entry point clearly marked -- [ ] No uncommitted changes that break existing functionality - -## Handoff Template - -```json -{ - "agent_from": "agent_name", - "agent_to": "agent_name", - "focus_area": "brief description", - "proof_gates_pending": ["gate-1", "gate-2"], - "known_limitations": ["limitation 1", "limitation 2"], - "next_steps": ["step 1", "step 2"], - "context_files": ["file1.rs", "file2.md"], - "test_evidence": ["manifests/file1.json", "manifests/file2.json"] -} -``` - -## Current Proof Gates Status - -- **Gate #1**: Contract round-tripping (11 golden tests) - ✅ PASSING -- **Gate #2**: DeepSeek live cache manifest - ✅ PASSING -- **Gate #3**: Runtime inventory parity - ✅ PASSING -- **Gate #4**: Cross-platform build/test - ✅ PASSING -- **Gate #5**: Watchdog socket reader - ✅ PASSING -- **Gate #6**: Caller inventory & retirement - ⏸️ PRECONDITION CHECK - -## Platform Matrix - -| Platform | Host | Status | Notes | -| -------- | -------------------- | ---------- | --------------------------------------- | -| FreeBSD | osa.smilepowered.org | ✅ Active | Primary target, FreeBSD 15.0-RELEASE-p8 | -| Linux | domedog | ✅ Active | Development/testing, Linux 6.8.0 | -| Linux | debby | ⏸️ Partial | Node 24, no Pi yet | - -## After Handoff - -- [ ] Receiving agent confirms understanding -- [ ] Test suite updated if new functionality added -- [ ] Documentation sync'd -- [ ] Handoff entry added to this file with timestamp - -## Handoff History - -### 2026-05-27T10:00:00Z - Initial Setup - -- **Agent**: System -- **Purpose**: Establish handoff protocol for Colibri multiagent development -- **Context**: TypeScript → Rust migration in progress, 6 proof gates defined -- **Next**: First agent handoff to be logged here - -### 2026-05-27T12:30:00Z - Glasspane Integration - -- **Agent From**: hermes -- **Agent To**: sam -- **Focus Area**: colibri-glasspane TUI and client integration -- **Proof Gates**: Gate #5 complete, daemon socket API working -- **Evidence**: - - `manifests/2026-05-26-osa-watchdog-host-status.json` - - `crates/colibri-glasspane-tui/` created -- **Known Limitations**: PTY launch not yet validated on FreeBSD -- **Next Steps**: - - Complete colibri-client crate - - Add glasspane-snapshot command to socket API - - Live FreeBSD PTY validation -- **Context Files**: - - `crates/colibri-glasspane/src/lib.rs` - - `crates/colibri-daemon/src/socket.rs` - - `docs/COLIBRI-GLASSPANE-DESIGN.md` - -### 2026-05-27T13:15:00Z - Herdr Remote + TUI Dashboard + Platform Matrix - -- **Agent From**: hermes -- **Agent To**: sam & claude -- **Focus Area**: Herdr Tailscale remote smoke, colibri-glasspane-tui, multiagent workflow tools -- **Proof Gates**: All 6 gates green (see proof-gate-tracker). `b325c38` baseline. -- **Evidence**: - - `clawdie-ai/docs/internal/sessions/2026-05-27-herdr-tailscale-remote-smoke.md` — bidirectional debby↔domedog over Tailscale - - `crates/colibri-glasspane-tui/` — 8th crate, ratatui dashboard (live snapshot polling, color-coded states, stalled detection) - - `crates/colibri-client/src/bin/colibri_ctl.rs` — operator CLI (snapshot, status, spawn/kill) - - `crates/colibri-client/src/bin/colibri_smoke_agent.rs` — offline local-fake-Pi smoke agent - - `tests/platform-matrix.rs` — cross-platform parity tests (FreeBSD + Linux) - - `tools/proof-gate-tracker.rs` — automated 6-gate validation binary -- **Known Limitations**: - - Herdr FreeBSD port parked — boundary decided (Linux/macOS display only) - - `herdr --remote` requires interactive terminal for first install - - Platform matrix omits debby (no Pi installed) — needs colibri-smoke-agent integration - - Debby's sshd was dead for 2 days (ListenAddress=100.66.193.10 → fixed to 0.0.0.0) -- **Next Steps**: - - Claude: review and merge handoff updates - - Wire debby into platform-matrix with colibri-smoke-agent - - CI/CD wiring for proof-gate-tracker (self-hosted Forgejo Actions/webhooks) -- **Context Files**: - - `.agent-handoff.md` (this file) - - `docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md` - - `docs/MIGRATION-INVENTORY.md` - - `clawdie-ai/docs/internal/sessions/2026-05-27-herdr-tailscale-remote-smoke.md` - -### 2026-05-27T19:35:00Z - FreeBSD Daemon + Scheduler Validation Planning - -- **Agent From**: claude (domedog/Linux) -- **Agent To**: codex (osa/FreeBSD) -- **Focus Area**: OSA FreeBSD daemon bring-up with comprehensive scheduler validation -- **Proof Gates**: All 6 gates green, baseline `a48afa1` (89 tests pass/0 fail, FreeBSD-safe test isolation) -- **Context**: Significant scope expansion at commit `db5737b` — scheduler module (506 lines) + rc.d service file landed -- **Evidence**: - - `crates/colibri-daemon/src/scheduler.rs` — NEW 506-line scheduler module (Once/Interval/Cron schedules, job management, agent capability matching) - - `packaging/freebsd/colibri_daemon.in` — rc.d service file (50 lines, review-only, not installed) - - `crates/colibri-store/` — NEW SQLite coordination store crate - - `docs/internal/sessions/2026-05-27-scheduler-freebsd-store-isolation-finding.md` — FreeBSD test isolation fix documented - - `docs/COLIBRI-CUTOVER-PLAN.md` — updated with T1.3b next action: FreeBSD smoke test at current main -- **What Changed Since Last Handoff**: - - **NEW**: Full scheduler implementation (T1.3) embedded in `DaemonState.scheduler` - - **NEW**: SQLite coordination store via `colibri-store` crate - - **NEW**: rc.d service file for `/usr/local/etc/rc.d/colibri_daemon` (not installed yet) - - **FIXED**: FreeBSD test isolation bug (production path permissions in unit tests) - - **UPDATED**: Cutover plan reflects scheduler landing + T1.3b FreeBSD smoke test as next action -- **Three Validation Options Analyzed**: - 1. **Option 1 (RECOMMENDED)**: Comprehensive scheduler + daemon smoke — single test validates both core daemon AND new scheduler functionality on FreeBSD - 2. **Option 2**: Incremental validation — core daemon first, then scheduler in separate cycle - 3. **Option 3**: Minimal smoke — core only, defer scheduler validation -- **Critical Questions to Answer Before Execution**: - 1. **`colibri-ctl` Binary Exists?** The smoke plan uses `target/release/colibri-ctl` but I don't see it in the workspace. Is this a CLI wrapper around `colibri-client`? - → **ANSWERED (hermes):** Yes. Built from `crates/colibri-client/src/bin/colibri_ctl.rs`. `cargo build --release` produces `target/release/colibri-ctl`. - 2. **Scheduler Socket Commands?** Does `crates/colibri-daemon/src/socket.rs` implement scheduler commands (`add_job`, `list_jobs`, `submit_task`)? - → **ANSWERED (hermes):** `intake-task` socket command exists (for Telegram/remote task submission). Job management (`add_job`, `list_jobs`) is currently in-memory only via `Scheduler::add_job()` — no socket commands for those yet. The smoke should test `intake-task` via socket and verify jobs fire via daemon logs. - 3. **Fake Agent for Spawn?** The plan references `target/release/colibri-smoke-agent`. Does this exist from the previous handoff? - → **ANSWERED (hermes):** Yes. Built from `crates/colibri-client/src/bin/colibri_smoke_agent.rs`. Produces Pi-format JSONL output for glasspane ingestion. - 4. **SQLite WAL on FreeBSD?** Are there FreeBSD-specific considerations for SQLite WAL journaling? - → **ANSWERED (hermes):** WAL is filesystem-level, not OS-specific. The `bundled` rusqlite feature compiles SQLite from source (no system lib dependency). Works on FreeBSD. WAL files (`-wal`, `-shm`) will appear alongside the `.sqlite` file — normal. - 5. **Baseline Confirmation**: Verify we're pulling from `origin/main` which includes the FreeBSD test isolation fix at `a48afa1` - → **ANSWERED (hermes):** Current main is `b898c97` (claude's handoff) which includes `a48afa1`. 72 tests, clippy-clean. -- **Recommended Path**: Option 1 — Comprehensive smoke testing both core daemon (socket, status, snapshot, spawn) AND scheduler functionality (jobs, schedules, task intake) in isolated `/tmp` paths -- **Smoke Test Scope (Option 1)**: - - **Part A: Core Daemon**: `COLIBRI_DAEMON_DATA_DIR=/tmp/colibri-osa-smoke-$USER`, start daemon, verify socket/SQLite, test `colibri-ctl status/snapshot/spawn-local`, TUI display, cleanup - - **Part B: Scheduler**: Submit interval/once/cron jobs via socket, verify jobs fire, check tasks in SQLite store, confirm scheduler tick works on FreeBSD -- **Session Report**: `docs/internal/sessions/2026-05-27-osa-freebsd-daemon-scheduler-smoke.md` -- **Evidence to Record**: - - FreeBSD version (`freebsd-version`) - - Rust version (`rustc --version`) - - Commit hash (`git rev-parse HEAD`) - - Exact env vars and paths - - Socket/SQLite creation verification - - Scheduler job/task counts before/after - - Daemon logs showing job execution - - Cleanup success/failure (stale socket handling) -- **Known Limitations**: - - Scheduler developed on Linux, may have FreeBSD edge cases - - SQLite coordination store untested on FreeBSD yet - - rc.d file is review-only, not installed to system - - No Herdr on FreeBSD (boundary reaffirmed) -- **Next Steps**: - 1. Answer 5 critical questions above - 2. Verify baseline (`a48afa1` or newer) - 3. Confirm `colibri-ctl` exists or define socket commands - 4. Execute smoke on osa at current main (`db5737b`) - 5. Document findings in session report - 6. Update `.agent-handoff.md` with results -- **Context Files**: - - `.agent-handoff.md` (this file) - - `docs/COLIBRI-CUTOVER-PLAN.md` - - `docs/internal/sessions/2026-05-27-scheduler-freebsd-store-isolation-finding.md` - - `packaging/freebsd/colibri_daemon.in` - - `crates/colibri-daemon/src/scheduler.rs` - - `crates/colibri-daemon/src/socket.rs` - - `crates/colibri-daemon/src/daemon.rs` - -### 2026-05-27T16:00:00Z - Cutover plan reconciliation (FYI, not a debate) - -- **Agent From**: claude (domedog) -- **Agent To**: hermes (debby) -- **Focus Area**: shared cutover plan is now authoritative; storage decided -- **Summary**: - - `docs/COLIBRI-CUTOVER-PLAN.md` (`0925939`, then this commit) is the **shared - verified** cutover plan. `.hermes/plans/2026-05-27-colibri-cutover.md` is - **superseded where it conflicts** — please reconcile or retire it. - - **Storage DECIDED (Sam):** Colibri owns its own store; **embedded SQLite** - first; Postgres adapter only if parity/integration proves the need. Do not - reuse clawdie-ai `system_ops` Postgres by default. -- **Conflicts fixed (verified 27.maj)**: - - No `crates/colibri-daemon` in `clawdie-ai` — it has **no `crates/` dir**. - The real daemon is **Unix-socket** in the `colibri` repo, not axum/HTTP. - - **No Herdr in the FreeBSD execution path** — Linux/macOS display/remote - only; `colibri-glasspane` is the native answer (`MIGRATION-INVENTORY.md` §3). - - Baseline corrected to `160dd11` (65 tests pass/0 fail, clippy clean); - `eb37784` was **not** clippy-clean. - - Ownership: **Claude=domedog=Linux, Codex=osa=FreeBSD, Hermes=debby=Linux**. - - "debby↔domedog herdr already smoke-tested" downgraded: as of my 27.maj check - the **herdr client is not installed on debby**, so the hub direction - (debby→domedog) is still pending (Lane 2 T2.2). Conflicts with the T13:15 - "bidirectional" entry above — flagging so it gets actually closed. -- **Next Steps (hermes)**: - - Reconcile/retire the `.hermes` draft against `docs/COLIBRI-CUTOVER-PLAN.md`. - - Install herdr client on debby → close Lane 2 T2.2 per `HERDR-HUB-RUNBOOK.md`. -- **Context Files**: - - `docs/COLIBRI-CUTOVER-PLAN.md` - - `docs/HERDR-HUB-RUNBOOK.md` - - `docs/MIGRATION-INVENTORY.md` - -### 2026-05-27T23:30:00Z - ISO build: Colibri release binaries needed on OSA - -- **Agent From**: hermes (debby) -- **Agent To**: codex (osa/FreeBSD) -- **Focus Area**: Build Colibri release binaries so the ISO build can consume them -- **Context**: `clawdie-iso` branch `xfce-operator-usb` (`d3deafd`) has - `FEATURE_COLIBRI=YES` wired in `build.sh`. The build preflight checks for - Colibri artifacts in `../colibri/target/release/`. They are not present yet. -- **Steps**: - 1. Build Colibri: - ```sh - cd /home/clawdie/colibri - git pull --ff-only origin main - git rev-parse --short HEAD - cargo build --workspace --release - ``` - 2. Verify binaries exist and are FreeBSD executables: - ```sh - ls -lh target/release/colibri-daemon \ - target/release/colibri \ - target/release/colibri-smoke-agent \ - target/release/colibri-tui - file target/release/colibri-daemon target/release/colibri - target/release/colibri --help | head - ``` - 3. Verify ISO build preflight passes (without starting root image assembly): - ```sh - cd /home/clawdie/clawdie-iso - git checkout xfce-operator-usb - FEATURE_COLIBRI=YES ./build.sh --skip-fetch - ``` - Expected: passes Colibri preflight, stops at step 5 (root/mdconfig required). - 4. `cargo clean` after successful build per `AGENTS.md` cleanup rule. -- **No debby cross-build** unless OSA build fails. -- **Context Files**: - - `AGENTS.md` (cleanup rule) - - `docs/ISO-INTEGRATION-PLAN.md` - - `docs/ISO-ACCEPTANCE-RUNBOOK.md` - -### 2026-05-29T09:10:00Z - Forgejo cutover: self-hosted source forge is primary - -- **Agent From**: claude (debby/Linux) -- **Agent To**: hermes / sam / codex -- **Focus Area**: Stop tracking Codeberg as the active Colibri remote; use self-hosted Forgejo. -- **Decision**: `code.smilepowered.org` is now the primary source forge for Colibri and the Clawdie repos. Codeberg is stale/archival unless Sam explicitly requests a sync. -- **Evidence**: - - SSH auth works with key `claude-code-clawdie` on Forgejo SSH port `2222`. - - Colibri remote now points to `git@code.smilepowered.org:clawdie/colibri.git`. - - `git fetch origin --prune` succeeds and local `main` tracks `origin/main` at `da31b5c`. -- **Known Limitations**: - - Branch protection, per-agent users/keys, and Forgejo webhook-driven FreeBSD validation are still pending. - - Other clones should update remotes or reclone from Forgejo; do not assume Codeberg has current state. -- **Next Steps**: - 1. Hermes finishes syncing `clawdie-ai` and cleaned `clawdie-iso` to Forgejo. - 2. Create per-host/per-agent credentials (`hermes-debby`, `claude-domedog`, `codex-osa`) and retire bootstrap/admin credentials from daily use. - 3. Add branch protection for `main` and wire Forgejo push webhooks to OSA FreeBSD validation. -- **Context Files**: - - `AGENTS.md` - - `.ssh/config` host entry for `code.smilepowered.org` - - `docs/HERDR-HUB-RUNBOOK.md` diff --git a/AGENTS.md b/AGENTS.md index a8e0144..e835244 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,7 +92,7 @@ It is intentionally separate from: ## Multiagent Workflow -- **Handoff doc:** `.agent-handoff.md` — always update before handing off +- **Handoff doc:** `doc/-HANDOFF.md` — always update before handing off - **Proof gate tracker:** `cargo run --bin proof-gate-tracker` - **Platform matrix:** `cargo test --test platform-matrix` - **Herdr remote smoke:** `clawdie-ai/docs/internal/sessions/2026-05-27-herdr-tailscale-remote-smoke.md` diff --git a/README.md b/README.md index 81c71ed..a0d9fa7 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,6 @@ with cache-first cost discipline (byte-stable prompt prefixes, cache-hit meterin **Status:** 8 crates; workspace gates are expected to be fmt/clippy/test/release green. Avoid fixed test-count status here — run the gate commands below for the current count. Phase 3 (coordination core) is in progress. -Design doc + cutover plan: `docs/COLIBRI-CUTOVER-PLAN.md`. Next ISO integration plan: `docs/ISO-INTEGRATION-PLAN.md`. ISO acceptance runbook: `docs/ISO-ACCEPTANCE-RUNBOOK.md`. Clawdie Studio/Zed proposal: `docs/CLAWDIE-STUDIO-PROPOSAL.md`. diff --git a/docs/CALLER-INVENTORY.md b/docs/CALLER-INVENTORY.md deleted file mode 100644 index bebd614..0000000 --- a/docs/CALLER-INVENTORY.md +++ /dev/null @@ -1,94 +0,0 @@ -# Caller Inventory & Retirement Plan (gate #6 prerequisite) - -Read-only "who-imports-what" of the clawdie-ai TS drop candidates, so retirement -is explicit and safe. **No code changed.** Method: import grep across -`clawdie-ai/src/` + content classification. Snapshot for rollback: -`archive/multitenant-claude-pre-divergence`. - -**Headline: the inventory corrected the earlier drop list** — `agent-runner.ts` -and `jail-exec-runner.ts` are load-bearing (they run **Pi**), not droppable. The -real, safe drop set is narrow and contained in one dispatch hub. - -## Findings - -| TS file | Callers (live) | Verdict | Why / replacement | -| --------------------------------- | ---------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `agent-runner.ts` | `config.ts`, `task-scheduler.ts`, `ipc.ts`, `index.ts` (4) | **KEEP** | It _is_ the Pi host runner — "spawns `pi` directly… `--print` mode". Mislabeled "multi-backend" in the plan. Dropping it breaks the Pi runtime. | -| `jail-exec-runner.ts` | `controlplane-heartbeat-executor.ts` (+ test) | **KEEP, trim** | Exports `jailPi` (Pi jail exec, load-bearing) **and** `jailAider`. Keep `jailPi`; remove `jailAider` only when aider goes. | -| `controlplane-aider-runner.ts` | `controlplane-heartbeat-executor.ts` | **DROP (gated)** | Reachable only via executor branch `CONTROLPLANE_RUNNER === 'aider'`. Replaced by Pi-only. | -| `controlplane-heartbeat-codex.ts` | `controlplane-heartbeat-executor.ts` | **DROP (gated)** | Reachable only via executor branch `CONTROLPLANE_RUNNER === 'codex'`. `controlplane-heartbeat-pi.ts` stays. | -| `tmux-screenshot-command.ts` | `index.ts` (1) | **DROP (gated)** | Terminal-screenshot CLI command; superseded by Herdr (Linux client supervision). | -| bespoke provider-smoke | `.agent/skills/pi-provider-smoke`, `scripts/*smoke*.mjs` | **separate track** | Not a `src/` module. `colibri-deepseek` covers the cache probe; retire/repoint the skill later, on its own. | -| "glass-pane glue" | — | **does not exist** | No agent-supervision module. `nginx-glasspane` (caching) and `glass.sh` are unrelated. | - -## The drop is one contained edit - -All non-Pi backends are gated behind `CONTROLPLANE_RUNNER` and dispatched from a -single hub, `controlplane-heartbeat-executor.ts`: - -```text -controlplane-heartbeat-executor.ts - if CONTROLPLANE_RUNNER === 'aider' -> runAiderTask + jailAider ⛔ remove branch - if CONTROLPLANE_RUNNER === 'codex' -> runCodexTask ⛔ remove branch - else (pi) -> runPiTask + jailPi ✅ keep -``` - -**Retirement steps (gated — execute only after the precondition below):** - -1. In `controlplane-heartbeat-executor.ts`: delete the `=== 'aider'` and - `=== 'codex'` branches and their imports (`runAiderTask`, `runCodexTask`, - `jailAider`, `CONTROLPLANE_AIDER_*`). Keep the Pi path. -2. Now-unreferenced → delete: `controlplane-aider-runner.ts`, - `controlplane-heartbeat-codex.ts` (+ their tests). -3. `jail-exec-runner.ts`: remove the `jailAider` export; keep `jailPi`. -4. Remove `CONTROLPLANE_AIDER_BIN/FLAGS/LOG_DIR/TMUX_SESSION` from config. -5. `index.ts`: unregister the tmux-screenshot command; delete - `tmux-screenshot-command.ts` (+ test). Supervision → Herdr Linux client. - -## Mermaid - -```mermaid -graph LR - idx["index.ts"] --> tmux["tmux-screenshot-command.ts ⛔"] - cfg["config.ts"] --> ar["agent-runner.ts ✅ Pi runner"] - sch["task-scheduler.ts"] --> ar - ipc["ipc.ts"] --> ar - idx --> ar - exec["controlplane-heartbeat-executor.ts (hub)"] --> pi["heartbeat-pi.ts ✅"] - exec --> aider["aider-runner.ts ⛔"] - exec --> codex["heartbeat-codex.ts ⛔"] - exec --> jail["jail-exec-runner.ts: jailPi ✅ / jailAider ⛔"] - tmux -. replaced_by .-> HERDR["Herdr (Linux client)"] - aider -. replaced_by .-> PI["Pi-only + colibri-deepseek"] - codex -. replaced_by .-> PI -``` - -## JSON - -```json -{ - "keep": [ - {"file":"agent-runner.ts","reason":"the Pi host runner","callers":["config","task-scheduler","ipc","index"]}, - {"file":"jail-exec-runner.ts","reason":"jailPi load-bearing","trim":"jailAider"} - ], - "drop_gated": [ - {"file":"controlplane-aider-runner.ts","caller":"heartbeat-executor","gate":"CONTROLPLANE_RUNNER==aider"}, - {"file":"controlplane-heartbeat-codex.ts","caller":"heartbeat-executor","gate":"CONTROLPLANE_RUNNER==codex"}, - {"file":"tmux-screenshot-command.ts","caller":"index.ts","replacement":"herdr"} - ], - "separate_track": ["pi-provider-smoke skill","scripts/*smoke*.mjs"] -} -``` - -## Precondition & guardrails - -- **Replacement must be explicit & live:** production runs `CONTROLPLANE_RUNNER=pi` - (the Pi-only path), with Colibri's DeepSeek slice + Herdr supervision as the - replacements. **Verify the production `CONTROLPLANE_RUNNER` value before any - deletion** — if any deployment still sets `aider`/`codex`, do not drop. -- Untouched: `watchdog`, `hostd`, `doctor`, `pi-profile`, `controlplane-*` - coordination, `task-scheduler`, `provider-capabilities` (contract source), - and `agent-runner`/`jail-exec-runner` (Pi runtime). -- This is the **plan**, not the execution. Retirement is a separate, reviewed PR - after the precondition holds — and it touches one hub + deletes two files, so - it's small and revertible. diff --git a/docs/COLIBRI-CUTOVER-PLAN.md b/docs/COLIBRI-CUTOVER-PLAN.md deleted file mode 100644 index 96211f6..0000000 --- a/docs/COLIBRI-CUTOVER-PLAN.md +++ /dev/null @@ -1,209 +0,0 @@ -# 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 | `ceaeaee` + follow-up | T1.2/T1.3 landed (`colibri-store` + scheduler); 8 crates; verify current counts with `cargo test --workspace`; `clippy -D warnings` clean after follow-up. | -| `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, 8 crates** (`colibri-contracts`, `-deepseek`, `-runtime`, - `-glasspane`, `-daemon`, `-client`, `-glasspane-tui`, `-store` + 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`. - ---- - -## Decisions - -1. **Coordination-core storage — DECIDED (Sam, 27.maj): Colibri owns its own - store.** Phase 1 = **embedded SQLite**. Add a Postgres adapter _only if_ - dual-run parity or integration proves the need — do **not** default to - reusing clawdie-ai's `system_ops` Postgres. Rationale: cleaner cutover - boundary, no hidden coupling to clawdie-ai. (Rejected up front: reuse - `system_ops`; Colibri-owned Postgres.) -2. **Herdr boundary — REAFFIRMED.** Herdr stays Linux/macOS display/remote only. - Putting Herdr in the FreeBSD execution path reopens `MIGRATION-INVENTORY.md` - §3 and needs an explicit reversal. - -### Storage ownership surface (Decision #1 detail) - -_Proposed defaults — adjust at implementation._ - -- **DB file:** FreeBSD service path `/var/db/colibri/colibri.sqlite` (owned by the - Colibri service user, dir `0700`). Linux dev: `$XDG_DATA_HOME/colibri/colibri.sqlite` - (`~/.local/share/colibri/`). Overridable via daemon config / `COLIBRI_DB_PATH`. -- **Mode:** **WAL** (`journal_mode=WAL`, `synchronous=NORMAL`) — concurrent snapshot - readers + single writer daemon. **Local filesystem only** (WAL is unsafe over - network FS). -- **Backup/export:** hot binary backup via `VACUUM INTO` (point-in-time, no stop); - **plus** a JSON export in the existing contract shapes - (`clawdie.glasspane.snapshot.v1`, run-manifest) for portability, human inspection, - and dual-run parity diffs. -- **Authoritative here:** task-board lifecycle, agent lifecycle, scheduling state - (Colibri-owned). **Mirrored / derived — NOT authoritative here:** Pi JSONL events - (source = the agent's stream), watchdog host-status (source = watchdog socket / - `hostd`), runtime inventory. Colibri holds read-only copies of these. - -**Postgres-escalation criterion (one rule, not "maybe later"):** add the Postgres -adapter **only if**, during Lane 4 dual-run state-parity (T4.2), SQLite proves -insufficient for _required shared state_ — i.e. ≥2 hosts must concurrently -read/write the same coordination state and a single-writer local SQLite cannot -satisfy it. A single-host daemon never triggers it. - -**Failure mode (Colibri DB corrupt/unavailable) — fail safe:** Colibri must **not** -take over. It drops to observe-only (or halts its control actions), reports an -unhealthy status, and the cutover gates (T4.3 / T4.4) cannot advance; during -dual-run, clawdie-ai (TS) retains control. **`watchdog` / `hostd` and local FreeBSD -safety remain authoritative and win** regardless of Colibri DB state — no unsafe -takeover. - ---- - -## 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. - **Storage: embedded SQLite (Decision #1); Postgres adapter only if parity needs it.** -- **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. - [Implementation plan →](T1.4-PROMPT-DISCIPLINE-PLAN.md) -- **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. - -**Non-blocking for core:** Lane 2 gates only **IMG deployment**, never Colibri -**core correctness**. Lane 1 must not depend on Herdr compatibility, and Herdr -must not silently become a prerequisite for the Rust core. - -- **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. Lane 1 T1.3 — execution & scheduling landed: scheduler module, - cron/interval/one-shot, leader/delegate matching, intake-task socket command. - Follow-up fixed FreeBSD test isolation and scheduler edge cases. -2. ~~Lane 1 T1.3b — FreeBSD smoke test.~~ **DONE**. OSA /tmp smoke - passed, scheduler deadlock fixed + regression test, rc.d service structurally - correct, CLI renamed `colibri-ctl` → `colibri`, and task operations are now - covered by `colibri create-task`, `colibri list-tasks`, and - `colibri intake-task`. Reports live in `docs/internal/sessions/`, including - `2026-05-27-osa-freebsd-colibri-cli-task-smoke.md`. -3. **Lane 2 T2.2** — Herdr debby→domedog attach (install herdr client on debby). -4. **Lane 1 T1.4** — Phase 5 cache-first prompt discipline (3-region assembler, - cost modes fast/smart/max). diff --git a/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md b/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md index dc3d3b9..0177fad 100644 --- a/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md +++ b/docs/COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md @@ -551,7 +551,6 @@ Unix socket path (`DaemonConfig.socket_path`). | `docs/COLIBRI-GLASSPANE-DESIGN.md` | Glasspane capability design, phase plan, non-goals | | `crates/colibri-client/src/lib.rs` | Phase-4 typed Unix-socket client for display/UI consumers | | `docs/HERDR-VS-COLIBRI-GRAPH.md` | Hybrid boundary: Herdr as Linux display client | -| `docs/CALLER-INVENTORY.md` | Caller-side inventory of Pi/agent invocations | | `crates/colibri-daemon/src/socket.rs` | Socket server implementation | | `crates/colibri-daemon/src/daemon.rs` | Daemon background loop + heartbeat | | `crates/colibri-daemon/src/lib.rs` | Wire types: `HerdrCommand`, `HerdrResponse` | diff --git a/docs/GATE5-MIGRATION-GRAPH.md b/docs/GATE5-MIGRATION-GRAPH.md deleted file mode 100644 index 81ae092..0000000 --- a/docs/GATE5-MIGRATION-GRAPH.md +++ /dev/null @@ -1,142 +0,0 @@ -# Gate #5 Migration Graph — watchdog host-status reader - -Graph-only migration map (no code). Purpose: port the **right contract and -boundaries** for gate #5 ("watchdog status read without breaking -doctor / pi-profile"), and prevent control-plane-rewrite creep. The Rust reader -is a **new, additive, read-only** consumer of the watchdog socket — it replaces -a _contract_, not production logic. - -Grounded in: `clawdie-ai/src/watchdog.ts` (owns the socket), -`src/doctor.ts` (existing reader), `src/colibri-host-status.ts` (additive reader - -- shape), `src/pi-profile.ts` (keep-compatible; **not** a confirmed direct - socket reader), and this repo's `colibri-contracts` / `manifests/`. - -## Mermaid - -```mermaid -graph LR - subgraph TS["clawdie-ai — production TS (PROTECTED)"] - WD["watchdog.ts
runtime governor (owns socket)"] - SOCK(["watchdog Unix socket
${SERVICE_NAME}-watchdog.sock"]) - DOC["doctor.ts
socket reader"] - PIP["pi-profile.ts
keep-compatible"] - CHS["colibri-host-status.ts
additive reader + shape"] - end - subgraph RS["Colibri — target Rust"] - RT["crates/colibri-runtime
watchdog reader (NEW)"] - CT["crates/colibri-contracts
HostStatus (NEW)"] - end - subgraph EV["evidence / gate"] - M1["manifest: linux mock
host-status run"] - M2["manifest: osa live
watchdog read"] - G5{{"gate #5"}} - end - - WD -->|owns/serves| SOCK - WD -->|"IPC: cmd:status / cmd:mode"| SOCK - DOC -->|"reads (cmd:status)"| SOCK - CHS -->|"reads (cmd:status)"| SOCK - CHS -->|defines shape| CT - RT -->|"reads (cmd:status) READ-ONLY"| SOCK - RT -->|replaces_contract_only| CHS - RT -->|produces| CT - RT -.->|must_not_break| DOC - RT -.->|must_not_break / no edits| WD - RT -.->|keep_compatible| PIP - RT -->|produces| M1 - M1 -->|evidence_for_gate| G5 - M2 -->|evidence_for_gate| G5 - SOCK -->|lives_on FreeBSD| OSA[(osa)] - M1 -->|runs_on| DOM[(domedog · mock)] - M2 -->|runs_on| OSA -``` - -## JSON nodes/edges - -```json -{ - "nodes": [ - { "id": "ts:watchdog", "type": "ts_module", "file": "src/watchdog.ts", "role": "owns socket; runtime governor; IPC cmd:status,cmd:mode" }, - { "id": "socket:watchdog", "type": "watchdog_socket", "path": "${SERVICE_NAME}-watchdog.sock", "host": "osa (FreeBSD)" }, - { "id": "ts:doctor", "type": "ts_module", "file": "src/doctor.ts", "role": "confirmed socket reader" }, - { "id": "ts:pi-profile", "type": "ts_module", "file": "src/pi-profile.ts", "role": "keep-compatible; not a confirmed direct socket reader" }, - { "id": "ts:colibri-host-status", "type": "ts_module", "file": "src/colibri-host-status.ts", "role": "additive reader; ColibriHostStatus shape" }, - { "id": "rust:colibri-runtime", "type": "rust_crate", "status": "to_build", "role": "watchdog reader" }, - { "id": "rust:colibri-contracts", "type": "rust_crate", "status": "exists", "role": "contracts" }, - { "id": "contract:HostStatus", "type": "contract", "status": "to_add", "fields": ["source","observed_at","mode","throttled","free_memory_mb","active_jails","queued_groups","controlplane_status"] }, - { "id": "manifest:linux-mock", "type": "manifest", "status": "to_produce", "host": "domedog" }, - { "id": "manifest:osa-live", "type": "manifest", "status": "later", "host": "osa" }, - { "id": "gate:5", "type": "proof_gate" } - ], - "edges": [ - { "from": "ts:watchdog", "to": "socket:watchdog", "rel": "owns" }, - { "from": "ts:doctor", "to": "socket:watchdog", "rel": "reads" }, - { "from": "ts:colibri-host-status", "to": "socket:watchdog", "rel": "reads" }, - { "from": "ts:colibri-host-status", "to": "contract:HostStatus", "rel": "defines_shape" }, - { "from": "rust:colibri-runtime", "to": "socket:watchdog", "rel": "reads_readonly" }, - { "from": "rust:colibri-runtime", "to": "ts:colibri-host-status", "rel": "replaces_contract_only" }, - { "from": "rust:colibri-runtime", "to": "contract:HostStatus", "rel": "produces" }, - { "from": "rust:colibri-contracts", "to": "contract:HostStatus", "rel": "defines" }, - { "from": "rust:colibri-runtime", "to": "ts:doctor", "rel": "must_not_break" }, - { "from": "rust:colibri-runtime", "to": "ts:watchdog", "rel": "must_not_break" }, - { "from": "rust:colibri-runtime", "to": "ts:pi-profile", "rel": "keep_compatible" }, - { "from": "rust:colibri-runtime", "to": "manifest:linux-mock", "rel": "produces" }, - { "from": "manifest:linux-mock", "to": "gate:5", "rel": "evidence_for_gate" }, - { "from": "manifest:osa-live", "to": "gate:5", "rel": "evidence_for_gate" }, - { "from": "socket:watchdog", "to": "osa", "rel": "lives_on" } - ] -} -``` - -## Wire facts (from `watchdog.ts`) - -- Socket path: `path.join(TMP_IPC_DIR, "${SERVICE_NAME}-watchdog.sock")`. -- Request: `{"cmd":"status"}\n` (newline-framed). Reply: `{ok:true, data:{...}}\n`. -- `data` keys (camelCase): `mode`, `throttled`, `freeMemoryMB`, `activeJails`, - `queuedGroups`, `controlplane.overallStatus`. -- Mutating command exists: `{"cmd":"mode","value":...}` — **the reader must - never send this.** - -## Gap list — what Rust must implement for gate #5 - -1. **`colibri-contracts`: `HostStatus`** struct. Mirror `ColibriHostStatus`: - `source:"watchdog-socket"`, `observed_at`, `mode`, `throttled`, - `free_memory_mb`, `active_jails`, `queued_groups`, - `controlplane_status: Option`. **Naming decision:** wire `data` is - camelCase (`freeMemoryMB`); the other Colibri contracts are snake_case - (`prompt_cache_hit_tokens`). Recommend the contract stay **snake_case** and - the reader map wire→contract. Add a golden test fixture. -2. **`crates/colibri-runtime`: watchdog reader.** tokio `UnixStream`; connect → - write `{"cmd":"status"}\n` → read until newline → parse `{ok,data}` → - normalize to `HostStatus`. **Read-only** (only `cmd:status`). Total/lenient - parse (garbled fields → safe defaults), 2s timeout, never panics — every - failure returns `Err`/`{ok:false}` (mirror `readColibriHostStatus`). -3. **Socket path resolution:** `COLIBRI_WATCHDOG_SOCKET` env override, default to - the `${SERVICE_NAME}-watchdog.sock` convention. (Linux has no such socket → - the reader must degrade cleanly to "unavailable".) -4. **Mock Unix-socket test (domedog/Linux):** a tokio `UnixListener` replying - with a sample `{ok,data}` → assert parsed `HostStatus`; plus an - unavailable-socket → graceful error. Mirrors the two TS test cases. -5. **Evidence:** emit a `clawdie.interagent.run-manifest.v1` for the Linux mock - run (gate #5 Linux evidence). Live osa read manifest comes from Codex. - -## Risk list — what must NOT change in production TS - -- **Do not edit `watchdog.ts`** or the socket path/protocol. The reader is purely - additive. -- **Read-only invariant:** the reader sends only `{"cmd":"status"}`. It must - never send `{"cmd":"mode",...}` (that changes the live run mode → production - behavior change). -- **`doctor.ts` keeps working unchanged.** The Rust reader runs _alongside_ it; - it `replaces_contract_only` `colibri-host-status.ts`, and even that TS module - stays in production until gate #6 (no retirement yet). -- **`pi-profile.ts`:** keep-compatible per the plan, but it is **not** a - confirmed direct socket reader — verify before assuming coupling; don't add - edges that don't exist. -- **Connection hygiene:** connect, one request, disconnect, short timeout. Don't - hold the socket or add load that could starve `doctor`/`colibri-host-status`. -- **Mock ≠ live.** A green Linux mock does **not** close gate #5. The socket only - exists on FreeBSD; gate #5 needs the **osa live read manifest** (Codex). -- **Scope:** gate #5 unblocks the operator/control-plane path only; it does not - authorize porting any other watchdog/orchestration logic. diff --git a/docs/MIGRATION-INVENTORY.md b/docs/MIGRATION-INVENTORY.md deleted file mode 100644 index 5e0f9ea..0000000 --- a/docs/MIGRATION-INVENTORY.md +++ /dev/null @@ -1,170 +0,0 @@ -# Colibri Migration Inventory - -**Status:** Phases 1–4 complete; 7 crates; daemon scaffolded; TS legacy files -retired. Workspace gates green as of `b325c38`. Herdr FreeBSD port is **parked** -(not a migration blocker) — Herdr stays a Linux/macOS display/remote plane; -`colibri-glasspane` is the native FreeBSD answer. - -Source plan: `clawdie-ai/doc/COLIBRI-CONTROLPLANE-PLAN.md` and -`clawdie-ai/doc/COLIBRI-PI-CONTROL-PLAN.md`. - -**Date:** 27.maj.2026 - -Principle: **extract contracts, not logic.** Port the stable wire surfaces from -`clawdie-ai` into Rust, use the TS definitions and committed `manifests/` as -golden fixtures, and do not migrate orchestration until the proof gates pass. - ---- - -## 0. Phases — status summary - -| Phase | Description | Status | -| ----- | ------------------------------------------------------------- | ------------------------- | -| 1 | Inventory (caller audit) | ✅ complete | -| 2 | Pi event bridge (contracts crate) | ✅ complete | -| 3 | Host status ingestion (runtime) | ✅ complete | -| 4 | Run manifest ingestion + daemon | ✅ complete | -| 5 | Herdr Linux display client (optional, AGPL, Linux/macOS-only) | ✅ validated (Linux only) | -| 6 | Deprecation PRs (TS retirement) | ✅ complete | - ---- - -## 1. Rust workspace — 7 crates - -All crates compile and test on Linux (debby) and FreeBSD (osa). -`cargo test --workspace`: **all gates green as of `b325c38`** -(`cargo clippy --workspace --all-targets -- -D warnings`: clean). - -| Crate | Role | -| ------------------- | ---------------------------------------------------------------- | -| `colibri-contracts` | JSON schemas + serde structs + golden tests | -| `colibri-deepseek` | DeepSeek client + prefix-cache accounting (probe home) | -| `colibri-runtime` | Watchdog host-status reader + runtime inventory | -| `colibri-glasspane` | FreeBSD-native agent supervision ("the radar") | -| `colibri-daemon` | Always-on service: session manager, agent spawner, socket API | -| `colibri-client` | Typed client for the daemon Unix socket API | -| `colibri` (root) | Binary entrypoints: `colibri-probe`, `colibri-runtime-inventory` | - -Binaries: `colibri-probe` (DeepSeek cache probe) and -`colibri-runtime-inventory` (cross-host version drift report). - -### Daemon scaffold (Phase 4) - -`colibri-daemon` is scaffolded as an always-on Rust service: - -- Session manager: JSONL persistence + context window management -- Agent spawner: subprocess lifecycle + provider routing -- Herdr Unix socket API: newline-delimited JSON commands -- Graceful shutdown on SIGTERM/SIGINT -- Background loop: heartbeat (30s), session rotation (60s), memory handoff (120s) -- Agent stall detection with glasspane integration - -The daemon replaces control-plane loop logic previously scattered across -`agent-runner.ts`, `agent-session.ts`, and `session-compaction.ts` in -clawdie-ai TypeScript. - ---- - -## 2. TS files retired (Phase 6 complete) - -**Commit:** retirement commit on `main` — 3425 deletions, 38 files changed. - -**Post-retirement test validation (debby, Linux, Node v24):** -`npx vitest run` — 19 failed | 2329 passed (2348 total). All 19 failures are -expected Linux exclusions (argon2 FreeBSD-only API, explanation-grounder -snippet drift, nginx config path difference). No regressions. - -### Dropped (non-Pi backends removed) - -| TS file | Reason | -| ---------------------------------------- | ----------------------------------------------------------- | -| `controlplane-aider-runner.ts` | Non-Pi backend — `CONTROLPLANE_RUNNER=aider` branch removed | -| `controlplane-heartbeat-codex.ts` | Non-Pi backend — `CONTROLPLANE_RUNNER=codex` branch removed | -| `tmux-screenshot-command.ts` | Terminal-scrape glue, superseded by Herdr/glasspane | -| `jailAider` (from `jail-exec-runner.ts`) | Aider jail exec path removed | - -### Kept (load-bearing) - -| TS file | Why kept | -| ------------------------------ | --------------------------------------------------------------- | -| `agent-runner.ts` | IS the Pi host runner — mislabeled "multi-backend" in plan | -| `jail-exec-runner.ts` | `jailPi` is load-bearing FreeBSD exec; only `jailAider` removed | -| `colibri-pi-events.ts` | Pi `--mode json` event taxonomy (contract source) | -| `colibri-run-manifest.ts` | `clawdie.interagent.run-manifest.v1` (contract source) | -| `colibri-runtime-inventory.ts` | `clawdie.runtime-version-inventory.v1` + drift-report logic | -| `colibri-host-status.ts` | Additive watchdog socket reader (contract source) | -| `colibri-pi-run.ts` | Pi run summarizer (contract source) | -| `provider-capabilities.ts` | Model capability table (contract source) | -| `watchdog.ts` | FreeBSD runtime governor — NOT a deletion target | -| `hostd` | Privileged host operations — NOT a deletion target | -| `doctor` / `pi-profile` | Existing watchdog-status consumers — NOT deletion targets | - -### Retirement method - -All non-Pi backends were gated behind `CONTROLPLANE_RUNNER` and dispatched from -a single hub (`controlplane-heartbeat-executor.ts`). Retirement was one -contained edit: delete the `aider` and `codex` branches, their imports, and -the now-unreferenced files. The Pi path (`runPiTask` + `jailPi`) stays. - ---- - -## 3. Herdr FreeBSD port — parked, not a migration blocker (27.maj.2026) - -**Verdict:** dropped/parked. Herdr is **not** on the FreeBSD migration path, and -nothing in this plan blocks on porting it. FreeBSD supervision is delivered -natively by `colibri-glasspane`; Herdr stays a Linux/macOS **display/remote -plane** behind Colibri's socket API. Herdr-Linux-remote and Colibri-FreeBSD were -validated **separately**, which is exactly the boundary we want. - -**Boundary (decided):** - -- Herdr is AGPL + Linux/macOS-only — optional display/remote client over the - Colibri socket contract. No Herdr vendoring, no Herdr-on-FreeBSD in the core. -- `colibri-glasspane` is the FreeBSD-native answer (event-derived agent state). - -For the record, an exploratory build confirmed Herdr _can_ compile on FreeBSD 15 -(Zig target `x86_64-freebsd`; `cargo build --release` succeeded; 1450 passed / 3 -expected failures; `sysctl(KERN_PROC)`/`KERN_PROC_ARGS` work, `sizeof(kinfo_proc)=1088`; -no procfs so CWD must fall back to `kern.proc.cwd`/`None`). That experiment is -**not** continued — it is parked, not a pending task. Details: -`clawdie-ai/docs/internal/sessions/2026-05-27-herdr-freebsd-port-codex-results.md`. - ---- - -## 4. Proof gates — all green - -| Gate | Description | Status | -| ---- | --------------------------------------------------------------------- | --------- | -| 1 | `colibri-contracts` round-trips TS fixtures (11 golden tests) | ✅ | -| 2 | DeepSeek live cache manifest exists (domedog, ~98% cache-hit) | ✅ 26.maj | -| 3 | Runtime inventory parity (osa/domedog/debby, all Node 24) | ✅ 26.maj | -| 4 | End-to-end on Linux **and** FreeBSD (both cache-hit at ~98%) | ✅ 26.maj | -| 5 | Watchdog status read from Rust without breaking TS | ✅ 26.maj | -| 6 | TS non-Pi backends retired; caller inventory complete | ✅ 27.maj | -| 7 | Network-throughput coordination test (structured manifests, 2+ hosts) | pending | - ---- - -## 5. Architecture boundary - -```text -Rust daemon = source of truth (scheduling, task ownership, provider logic) -colibri-glasspane = FreeBSD-native agent supervision (derived from Pi events) -Herdr / Zed / web board = display + controls over socket/web -``` - -No scheduling, task ownership, or provider logic in the GUI layer. - ---- - -## 6. Evidence freeze - -`manifests/` is the source of truth. Current evidence set: - -- osa FreeBSD inventory — `manifests/2026-05-26-osa-runtime-inventory.json` -- domedog Linux inventory — `manifests/2026-05-26-domedog-runtime-inventory.json` -- debby inventory — `manifests/2026-05-26-debby-runtime-inventory.json` (Node 24; no Pi) -- domedog DeepSeek cache — `manifests/2026-05-26-domedog-deepseek-cache-result.json` -- osa DeepSeek cache — `manifests/2026-05-26-osa-deepseek-cache-result.json` -- osa watchdog status — `manifests/2026-05-26-osa-watchdog-host-status.json` -- osa FreeBSD gate #4 run manifest — `manifests/2026-05-26-osa-freebsd-gate4-run-manifest.json` diff --git a/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md b/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md index d387575..6028114 100644 --- a/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md +++ b/docs/MULTIAGENT-WORKFLOW-IMPROVEMENTS.md @@ -10,7 +10,7 @@ The Colibri project uses a multiagent development model where different AI agent ## 1. Agent Handoff Protocol -**File**: `.agent-handoff.md` +**File**: `doc/-HANDOFF.md` ### Purpose @@ -248,7 +248,7 @@ When an agent completes work: 1. Run `proof-gate-tracker` and verify all critical gates pass 2. Run `cargo test --workspace` and verify all tests pass -3. Update `.agent-handoff.md` with handoff details +3. Update `doc/-HANDOFF.md` with handoff details 4. Commit and push with clear handoff message --- @@ -266,12 +266,12 @@ When an agent completes work: 1. Add platform to `PlatformMatrix` tests in `tests/platform-matrix.rs` 2. Add validation criteria -3. Update `.agent-handoff.md` platform matrix +3. Update `doc/-HANDOFF.md` platform matrix 4. Commit manifests to `manifests/` directory ### Updating Handoff Protocol -1. Modify `.agent-handoff.md` template +1. Modify `doc/-HANDOFF.md` template 2. Update handoff history format 3. Communicate changes to all agents diff --git a/tools/README.md b/tools/README.md index 487de77..8f6aadb 100644 --- a/tools/README.md +++ b/tools/README.md @@ -67,7 +67,7 @@ cargo test --test platform-matrix all_platforms_validate_core_features -- --noca ### Agent Handoff Protocol -See `.agent-handoff.md` for the standardized handoff protocol used between agents. +See `doc/-HANDOFF.md` for the standardized handoff protocol used between agents. ### Handoff Template @@ -90,4 +90,4 @@ See `.agent-handoff.md` for the standardized handoff protocol used between agent - [ ] Relevant proof gates documented - [ ] Cross-platform validation recorded - [ ] Next agent's entry point marked -- [ ] Handoff entry added to `.agent-handoff.md` +- [ ] Handoff entry added to `doc/-HANDOFF.md`