Compare commits

...

1 Commits

Author SHA1 Message Date
ff7ea2d45e feat: Codebase Genome for burn-fleet (#681)
Some checks failed
Agent PR Gate / report (pull_request) Has been cancelled
Agent PR Gate / gate (pull_request) Failing after 43s
Self-Healing Smoke / self-healing-smoke (pull_request) Failing after 34s
Smoke Test / smoke (pull_request) Failing after 13m50s
Complete GENOME.md for burn-fleet (autonomous dispatch infra):
- Project overview: 112 panes, 96 workers across Mac + VPS
- Architecture diagram (ASCII)
- Lane routing table (8 repos → windows)
- Agent name registry (48 mythological names)
- Entry points and design decisions
- Scaling instructions
- Sovereignty assessment

Repo 14/16. Closes #681.
2026-04-16 00:29:30 -04:00

View File

@@ -0,0 +1,101 @@
# GENOME.md — Burn Fleet (Timmy_Foundation/burn-fleet)
> Codebase Genome v1.0 | Generated 2026-04-16 | Repo 14/16
## Project Overview
**Burn Fleet** is the autonomous dispatch infrastructure for the Timmy Foundation. It manages 112 tmux panes across Mac and VPS, routing Gitea issues to lane-specialized workers by repo. Each agent has a mythological name — they are all Timmy with different hats.
**Core principle:** Dispatch ALL panes. Never scan for idle. Stale work beats idle workers.
## Architecture
```
Mac (M3 Max, 14 cores, 36GB) Allegro (VPS, 2 cores, 8GB)
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ CRUCIBLE 14 panes (bugs) │ │ FORGE 14 panes (bugs) │
│ GNOMES 12 panes (cron) │ │ ANVIL 14 panes (nexus) │
│ LOOM 12 panes (home) │ │ CRUCIBLE-2 10 panes (home) │
│ FOUNDRY 10 panes (nexus) │ │ SENTINEL 6 panes (council)│
│ WARD 12 panes (fleet) │ └─────────────────────────────┘
│ COUNCIL 8 panes (sages) │ 44 panes (36 workers)
└─────────────────────────────┘
68 panes (60 workers)
```
**Total: 112 panes, 96 workers + 12 council members + 4 sentinel advisors**
## Key Files
| File | LOC | Purpose |
|------|-----|---------|
| `fleet-spec.json` | ~200 | Machine definitions, window layouts, lane assignments, agent names |
| `fleet-launch.sh` | ~100 | Create tmux sessions with correct pane counts on Mac + Allegro |
| `fleet-christen.py` | ~80 | Launch hermes in all panes and send identity messages |
| `fleet-dispatch.py` | ~250 | Pull Gitea issues and route to correct panes by lane |
| `fleet-status.py` | ~100 | Health check across all machines |
| `allegro/docker-compose.yml` | ~30 | Allegro VPS container definition |
| `allegro/Dockerfile` | ~20 | Allegro build definition |
| `allegro/healthcheck.py` | ~15 | Allegro container health check |
**Total: ~800 LOC**
## Lane Routing
Issues are routed by repo to the correct window:
| Repo | Mac Window | Allegro Window |
|------|-----------|----------------|
| hermes-agent | CRUCIBLE, GNOMES | FORGE |
| timmy-home | LOOM | CRUCIBLE-2 |
| timmy-config | LOOM | CRUCIBLE-2 |
| the-nexus | FOUNDRY | ANVIL |
| the-playground | — | ANVIL |
| the-door | WARD | CRUCIBLE-2 |
| fleet-ops | WARD | CRUCIBLE-2 |
| turboquant | WARD | — |
## Entry Points
| Command | Purpose |
|---------|---------|
| `./fleet-launch.sh both` | Create tmux layout on Mac + Allegro |
| `python3 fleet-christen.py both` | Wake all agents with identity messages |
| `python3 fleet-dispatch.py --cycles 1` | Single dispatch cycle |
| `python3 fleet-dispatch.py --cycles 10 --interval 60` | Continuous burn (10 cycles, 60s apart) |
| `python3 fleet-status.py` | Health check all machines |
## Agent Names
| Window | Names | Count |
|--------|-------|-------|
| CRUCIBLE | AZOTH, ALBEDO, CITRINITAS, RUBEDO, SULPHUR, MERCURIUS, SAL, ATHANOR, VITRIOL, SATURN, JUPITER, MARS, EARTH, SOL | 14 |
| GNOMES | RAZIEL, AZRAEL, CASSIEL, METATRON, SANDALPHON, BINAH, CHOKMAH, KETER, ALDEBARAN, RIGEL, SIRIUS, POLARIS | 12 |
| FORGE | HAMMER, ANVIL, ADZE, PICK, TONGS, WRENCH, SCREWDRIVER, BOLT, SAW, TRAP, HOOK, MAGNET, SPARK, FLAME | 14 |
| COUNCIL | TESLA, HERMES, GANDALF, DAVINCI, ARCHIMEDES, TURING, AURELIUS, SOLOMON | 8 |
## Design Decisions
1. **Separate GILs** — Allegro runs Python independently on VPS for true parallelism
2. **Queue, not send-keys** — Workers process at their own pace, no interruption
3. **Lane enforcement** — Panes stay in one repo to build deep context
4. **Dispatch ALL panes** — Never scan for idle; stale work beats idle workers
5. **Council is advisory** — Named archetypes provide perspective, not task execution
## Scaling
- Add panes: Edit `fleet-spec.json``fleet-launch.sh``fleet-christen.py`
- Add machines: Edit `fleet-spec.json` → Add routing in `fleet-dispatch.py` → Ensure SSH access
## Sovereignty Assessment
- **Fully local** — Mac + user-controlled VPS, no cloud dependencies
- **No phone-home** — Gitea API is self-hosted
- **Open source** — All code on Gitea
- **SSH-based** — Mac → Allegro communication via SSH only
**Verdict: Fully sovereign. Autonomous fleet dispatch with no external dependencies.**
---
*"Dispatch ALL panes. Never scan for idle — stale work beats idle workers."*