chore(docs): delete legacy migration/cutover artifacts; repoint handoff refs (Sam & Claude)
Remove the transition-era docs that no longer guide anyone and just pollute context: MIGRATION-INVENTORY, CALLER-INVENTORY, GATE5-MIGRATION-GRAPH, COLIBRI-CUTOVER-PLAN, and the rolling .agent-handoff.md. (History stays in git.) Fix references in kept docs: drop the cutover/caller pointers (README, COLIBRI-DAEMON-GLASSPANE-INTEGRATION), and repoint handoff mentions (AGENTS, tools/README, MULTIAGENT-WORKFLOW-IMPROVEMENTS) to the ephemeral per-task `doc/<FEATURE>-HANDOFF.md` convention. Dated session logs left as historical record. Markdown gate green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Sam & Claude
parent
b5a781f6e4
commit
ae5da0e94b
10 changed files with 7 additions and 892 deletions
|
|
@ -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`
|
||||
|
|
@ -92,7 +92,7 @@ It is intentionally separate from:
|
|||
|
||||
## Multiagent Workflow
|
||||
|
||||
- **Handoff doc:** `.agent-handoff.md` — always update before handing off
|
||||
- **Handoff doc:** `doc/<FEATURE>-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`
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
@ -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` |
|
||||
|
|
|
|||
|
|
@ -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<br/>runtime governor (owns socket)"]
|
||||
SOCK(["watchdog Unix socket<br/>${SERVICE_NAME}-watchdog.sock"])
|
||||
DOC["doctor.ts<br/>socket reader"]
|
||||
PIP["pi-profile.ts<br/>keep-compatible"]
|
||||
CHS["colibri-host-status.ts<br/>additive reader + shape"]
|
||||
end
|
||||
subgraph RS["Colibri — target Rust"]
|
||||
RT["crates/colibri-runtime<br/>watchdog reader (NEW)"]
|
||||
CT["crates/colibri-contracts<br/>HostStatus (NEW)"]
|
||||
end
|
||||
subgraph EV["evidence / gate"]
|
||||
M1["manifest: linux mock<br/>host-status run"]
|
||||
M2["manifest: osa live<br/>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<String>`. **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.
|
||||
|
|
@ -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`
|
||||
|
|
@ -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/<FEATURE>-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/<FEATURE>-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/<FEATURE>-HANDOFF.md` platform matrix
|
||||
4. Commit manifests to `manifests/` directory
|
||||
|
||||
### Updating Handoff Protocol
|
||||
|
||||
1. Modify `.agent-handoff.md` template
|
||||
1. Modify `doc/<FEATURE>-HANDOFF.md` template
|
||||
2. Update handoff history format
|
||||
3. Communicate changes to all agents
|
||||
|
||||
|
|
|
|||
|
|
@ -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/<FEATURE>-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/<FEATURE>-HANDOFF.md`
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue