fix: #681

genomes/burn-fleet-GENOME.md

@@ -0,0 +1,476 @@
+# GENOME.md: burn-fleet
+
+**Generated:** 2026-04-15
+**Repo:** Timmy_Foundation/burn-fleet
+**Purpose:** Laned tmux dispatcher for sovereign burn operations across Mac and Allegro
+**Analyzed commit:** `2d4d9ab`
+**Size:** 5 top-level source/config files + README | 985 total lines (`fleet-dispatch.py` 320, `fleet-christen.py` 205, `fleet-status.py` 143, `fleet-launch.sh` 126, `fleet-spec.json` 98, `README.md` 93)
+
+---
+
+## Project Overview
+
+`burn-fleet` is a compact control-plane repo for the Hundred-Pane Fleet.
+Its job is not model inference itself. Its job is to shape where inference runs, which panes wake up, which repos route to which windows, and how work is fanned out across Mac and VPS workers.
+
+The repo turns a narrative naming scheme into executable infrastructure:
+- Mac runs the local session (`BURN`) with windows like `CRUCIBLE`, `GNOMES`, `LOOM`, `FOUNDRY`, `WARD`, `COUNCIL`
+- Allegro runs a remote session (`BURN`) with windows like `FORGE`, `ANVIL`, `CRUCIBLE-2`, `SENTINEL`
+- `fleet-spec.json` is the single source of truth for pane counts, lanes, sublanes, glyphs, and names
+- `fleet-launch.sh` materializes the tmux topology
+- `fleet-christen.py` boots `hermes chat --yolo` in each pane and pushes identity prompts
+- `fleet-dispatch.py` consumes Gitea issues, maps repos to windows through `MAC_ROUTE` and `ALLEGRO_ROUTE`, and sends `/queue` work into the right panes
+- `fleet-status.py` inspects pane output and reports fleet health
+
+The repo is small, but it sits on a high-blast-radius operational seam:
+- it controls 100+ panes
+- it writes to live tmux sessions
+- it comments on live Gitea issues
+- it depends on SSH reachability to the VPS
+- it is effectively a narrative infrastructure orchestrator
+
+This means the right way to read it is as a dispatch kernel, not just a set of scripts.
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    A[fleet-spec.json] --> B[fleet-launch.sh]
+    A --> C[fleet-christen.py]
+    A --> D[fleet-dispatch.py]
+    A --> E[fleet-status.py]
+
+    B --> F[tmux session BURN on Mac]
+    B --> G[tmux session BURN on Allegro over SSH]
+
+    C --> F
+    C --> G
+    C --> H[hermes chat --yolo in every pane]
+    H --> I[identity + lane prompt]
+
+    J[Gitea issues on forge.alexanderwhitestone.com] --> D
+    D --> K[MAC_ROUTE]
+    D --> L[ALLEGRO_ROUTE]
+    D --> M[/queue prompt generation]
+    M --> F
+    M --> G
+    D --> N[comment_on_issue]
+    N --> J
+    D --> O[dispatch-state.json]
+
+    E --> F
+    E --> G
+    E --> P[get_pane_status]
+    P --> Q[fleet health summary]
+```
+
+### Structural reading
+
+The repo has one real architecture pattern:
+1. declarative topology in `fleet-spec.json`
+2. imperative realization scripts that consume that topology
+3. runtime state in `dispatch-state.json`
+4. external side effects in tmux, SSH, and Gitea
+
+That makes `fleet-spec.json` the nucleus and the four scripts adapters around it.
+
+---
+
+## Entry Points
+
+| Entry point | Type | Role |
+|-------------|------|------|
+| `fleet-launch.sh [mac|allegro|both]` | Shell CLI | Creates tmux sessions and pane layouts from `fleet-spec.json` |
+| `python3 fleet-christen.py [mac|allegro|both]` | Python CLI | Starts Hermes workers and injects identity/lane prompts |
+| `python3 fleet-dispatch.py [--cycles N] [--interval S] [--machine mac|allegro|both]` | Python CLI | Pulls open Gitea issues, routes them, comments on issues, persists `dispatch-state.json` |
+| `python3 fleet-status.py [--machine mac|allegro|both]` | Python CLI | Samples pane output and reports working/idle/error/dead state |
+| `README.md` quick start | Human runbook | Documents the intended operator flow from launch to christening to dispatch to status |
+
+### Hidden operational entry points
+
+These are not CLI entry points, but they matter for behavior:
+- `MAC_ROUTE` in `fleet-dispatch.py`
+- `ALLEGRO_ROUTE` in `fleet-dispatch.py`
+- `SKIP_LABELS` and `INACTIVE` filtering in `fleet-dispatch.py`
+- `send_to_pane()` as the effectful dispatch primitive
+- `comment_on_issue()` as the visible acknowledgement primitive
+- `get_pane_status()` in `fleet-status.py` as the fleet health classifier
+
+---
+
+## Data Flow
+
+### 1. Topology creation
+
+`fleet-launch.sh` reads `fleet-spec.json`, parses each window's pane count, and creates the tmux layout.
+
+Flow:
+- load spec file path from `SCRIPT_DIR/fleet-spec.json`
+- parse `machines.mac.windows` or `machines.allegro.windows`
+- create `BURN` session locally or remotely
+- create first window, then split panes, then create remaining windows
+- continuously tile after splits
+
+This script is layout-only. It does not launch Hermes.
+
+### 2. Agent wake-up / identity seeding
+
+`fleet-christen.py` reads the same `fleet-spec.json` and sends `hermes chat --yolo` into each pane.
+After a fixed wait window, it sends a second `/queue` identity message containing:
+- glyph
+- pane name
+- machine name
+- window name
+- pane number
+- sublane
+- sovereign operating instructions
+
+That identity message is the bridge from infrastructure to narrative.
+The worker is not just launched; it is assigned a mythic/operator identity with a lane.
+
+### 3. Issue harvest and lane dispatch
+
+`fleet-dispatch.py` is the center of the runtime.
+
+Flow:
+- load `fleet-spec.json`
+- load `dispatch-state.json`
+- load Gitea token
+- fetch open issues per repo with `requests`
+- filter PRs, meta labels, and previously dispatched issues
+- build a candidate pool per machine/window
+- assign issues pane-by-pane
+- call `send_to_pane()` to inject `/queue ...`
+- call `comment_on_issue()` to leave a visible burn dispatch comment
+- persist the issue assignment into `dispatch-state.json`
+
+Important: the data flow is not issue -> worker directly.
+It is:
+issue -> repo route table -> window -> pane -> `/queue` prompt -> worker.
+
+### 4. Health sampling
+
+`fleet-status.py` runs the inverse direction.
+It samples pane output through `tmux capture-pane` locally or over SSH and classifies the last visible signal as:
+- `working`
+- `idle`
+- `error`
+- `dead`
+
+It then summarizes by window, machine, and global fleet totals.
+
+### 5. Runtime state persistence
+
+`dispatch-state.json` is not checked in, but it is the only persistent memory of what the dispatcher already assigned.
+That means the runtime depends on a local mutable file rather than a centralized dispatch ledger.
+
+---
+
+## Key Abstractions
+
+### 1. `fleet-spec.json`
+
+This is the primary abstraction in the repo.
+It encodes:
+- machine identity (`mac`, `allegro`)
+- host / SSH details
+- hardware metadata (`cores`, `ram_gb`)
+- tmux session names
+- default model/provider metadata
+- windows with `panes`, `lane`, `sublanes`, `glyphs`, `names`
+
+Everything else in the repo interprets this document.
+If the spec drifts from the route tables or runtime assumptions, the fleet silently degrades.
+
+### 2. Route tables: `MAC_ROUTE` and `ALLEGRO_ROUTE`
+
+These tables are the repo's second control nucleus.
+They map repo names to windows.
+This is how `timmy-home`, `the-nexus`, `the-door`, `fleet-ops`, and `the-beacon` land in different operational lanes.
+
+This split means routing logic is duplicated:
+- once in the topology spec
+- once in Python route dictionaries
+
+That duplication is one of the most important maintainability risks in the repo.
+
+### 3. Pane effect primitive: `send_to_pane()`
+
+`send_to_pane()` is the real actuator.
+It turns a dispatch decision into a tmux `send-keys` side effect.
+It handles both:
+- local tmux injection
+- remote SSH + tmux injection
+
+Everything operationally dangerous funnels through this function.
+It is therefore a critical path even though the repo has no tests around it.
+
+### 4. Issue acknowledgement primitive: `comment_on_issue()`
+
+This is the repo's social trace primitive.
+It posts a burn dispatch comment back to the issue so humans can see that the fleet claimed it.
+This is the visible heartbeat of autonomous dispatch.
+
+### 5. Runtime memory: `dispatch-state.json`
+
+This file is the anti-duplication ledger for dispatch cycles.
+Without it, the dispatcher would keep recycling the same issues every pass.
+Because it is local-file state instead of centralized state, machine locality matters.
+
+### 6. Health classifier: `get_pane_status()`
+
+`fleet-status.py` does not know the true worker state.
+It infers state from captured pane output using string heuristics.
+So `get_pane_status()` is effectively a lightweight log classifier.
+Its correctness depends on fragile output pattern matching.
+
+---
+
+## API Surface
+
+The repo exposes CLI-level APIs rather than import-oriented libraries.
+
+### Shell API
+
+`fleet-launch.sh`
+- `./fleet-launch.sh mac`
+- `./fleet-launch.sh allegro`
+- `./fleet-launch.sh both`
+
+### Python CLIs
+
+`fleet-christen.py`
+- `python3 fleet-christen.py mac`
+- `python3 fleet-christen.py allegro`
+- `python3 fleet-christen.py both`
+
+`fleet-dispatch.py`
+- `python3 fleet-dispatch.py`
+- `python3 fleet-dispatch.py --cycles 10 --interval 60`
+- `python3 fleet-dispatch.py --machine mac`
+
+`fleet-status.py`
+- `python3 fleet-status.py`
+- `python3 fleet-status.py --machine allegro`
+
+### Internal function surface worth naming explicitly
+
+`fleet-launch.sh`
+- `parse_spec()`
+- `launch_local()`
+- `launch_remote()`
+
+`fleet-christen.py`
+- `send_keys()`
+- `christen_window()`
+- `christen_machine()`
+- `christen_remote()`
+
+`fleet-dispatch.py`
+- `load_token()`
+- `load_spec()`
+- `load_state()`
+- `save_state()`
+- `get_issues()`
+- `send_to_pane()`
+- `comment_on_issue()`
+- `build_prompt()`
+- `dispatch_cycle()`
+- `dispatch_council()`
+
+`fleet-status.py`
+- `get_pane_status()`
+- `check_machine()`
+
+These are the true API surface for future hardening and testing.
+
+---
+
+## Test Coverage Gaps
+
+### Current state
+
+Grounded from the pipeline dry run on `/tmp/burn-fleet-genome`:
+- 0% estimated coverage
+- untested modules called out by pipeline: `fleet-christen`, `fleet-dispatch`, `fleet-status`
+- no checked-in automated test suite
+
+### Critical paths with no tests
+
+1. `send_to_pane()`
+   - local tmux command construction
+   - remote SSH command construction
+   - escaping of issue titles and prompts
+   - failure handling when tmux or SSH fails
+
+2. `comment_on_issue()`
+   - verifies Gitea comment formatting
+   - verifies non-200 responses do not silently disappear
+
+3. `get_issues()`
+   - PR filtering
+   - `SKIP_LABELS` filtering
+   - title-based meta filtering
+   - robustness when Gitea returns malformed or partial issue objects
+
+4. `dispatch_cycle()`
+   - correct pooling by window
+   - deduplication via `dispatch-state.json`
+   - pane recycling behavior
+   - correctness when one repo has zero issues and another has many
+
+5. `get_pane_status()`
+   - classification heuristics for working/idle/error/dead
+   - false positives from incidental strings like `error` in normal output
+
+6. `fleet-launch.sh`
+   - parse correctness for pane counts
+   - layout creation behavior across first vs later windows
+   - remote script generation for Allegro
+
+### Missing tests to generate next in the real target repo
+
+If the goal is to harden `burn-fleet` itself, the first tests to add should be:
+- `test_route_tables_cover_spec_windows`
+- `test_send_to_pane_escapes_single_quotes_and_special_chars`
+- `test_comment_on_issue_formats_machine_window_pane_body`
+- `test_get_issues_skips_prs_and_meta_labels`
+- `test_dispatch_cycle_persists_dispatch_state_once`
+- `test_get_pane_status_classifies_spinner_vs_traceback_vs_empty`
+
+These are the minimum critical-path tests.
+
+---
+
+## Security Considerations
+
+### 1. Command injection surface
+
+`send_to_pane()` and the remote tmux/SSH command assembly are the biggest security surface.
+Even though single quotes are escaped in prompts, this remains a command injection boundary because untrusted issue titles and repo metadata cross into shell commands.
+
+This is why `command injection` is the right risk label for the repo.
+The risk is not hypothetical; the repo is literally translating issue text into shell transport.
+
+### 2. Credential handling
+
+The dispatcher uses a local token file for Gitea authentication.
+That is a credential handling concern because:
+- token locality is assumed
+- file path and host assumptions are embedded into runtime code
+- there is no retry / fallback / explicit missing-token UX beyond failure
+
+### 3. SSH trust boundary
+
+Remote pane control over `root@167.99.126.228` means the repo assumes a trusted SSH path to a root shell.
+That is operationally powerful and dangerous.
+A malformed remote command, stale known_hosts state, or wrong host mapping has fleet-wide consequences.
+
+### 4. Runtime state tampering
+
+`dispatch-state.json` is a local mutable state file with no locking, signing, or cross-machine reconciliation.
+If it is corrupted or lost, deduplication semantics fail.
+That can cause repeated dispatches or misleading status.
+
+### 5. Live-forge mutation
+
+`comment_on_issue()` mutates live issue threads on every dispatch cycle.
+That means any bug in deduplication or routing will create visible comment spam on the forge.
+
+### 6. Dependency risk
+
+The repo depends on `requests` for Gitea API access but has no pinned dependency metadata or environment contract in-repo.
+This is a small operational repo, but reproducibility is weak.
+
+---
+
+## Dependency Picture
+
+### Runtime dependencies
+- Python 3
+- `requests`
+- tmux
+- SSH client
+- ssh trust boundary to `root@167.99.126.228`
+- access to a Gitea token file
+
+### Implied environment dependencies
+- active tmux sessions on Mac and Allegro
+- SSH trust / connectivity to the VPS
+- hermes available in pane environments
+- Gitea reachable at `https://forge.alexanderwhitestone.com`
+
+### Notably missing
+- no `requirements.txt`
+- no `pyproject.toml`
+- no explicit test harness
+- no schema validation for `fleet-spec.json`
+
+---
+
+## Performance Characteristics
+
+For such a small repo, the performance question is not CPU time inside Python.
+It is orchestration fan-out latency.
+
+The main scaling costs are:
+- repeated Gitea issue fetches across repos
+- SSH round-trips to Allegro
+- tmux pane fan-out across 100+ panes
+- serialized `time.sleep(0.2)` dispatch staggering
+
+This means the bottleneck is control-plane coordination, not computation.
+The repo will scale until SSH / tmux / Gitea latency become dominant.
+
+---
+
+## Dead Code / Drift Risks
+
+### 1. Spec vs route duplication
+
+`fleet-spec.json` defines windows and lanes, while `fleet-dispatch.py` separately defines `MAC_ROUTE` and `ALLEGRO_ROUTE`.
+That is the biggest drift risk.
+A window can exist in the spec and be missing from a route table, or vice versa.
+
+### 2. Runtime-generated files absent from repo contracts
+
+`dispatch-state.json` is operationally critical but not described as a first-class contract in code.
+The repo assumes it exists or can be created, but does not validate structure.
+
+### 3. README drift risk
+
+The README says "use fleet-christen.sh" in one place while the actual file is `fleet-christen.py`.
+That is a small but real operator-footgun and a sign the human runbook can drift from the executable surface.
+
+---
+
+## Suggested Follow-up Work
+
+1. Move repo-to-window routing into `fleet-spec.json` and derive `MAC_ROUTE` / `ALLEGRO_ROUTE` programmatically.
+2. Add automated tests for `send_to_pane`, `get_issues`, `dispatch_cycle`, and `get_pane_status`.
+3. Add a schema validator for `fleet-spec.json`.
+4. Add explicit dependency metadata (`requirements.txt` or `pyproject.toml`).
+5. Add dry-run / no-side-effect mode for dispatch and christening.
+6. Add retry/backoff and error reporting around Gitea comments and SSH execution.
+
+---
+
+## Bottom Line
+
+`burn-fleet` is a small repo with outsized operational leverage.
+Its genome is simple:
+- one declarative topology file
+- four operational adapters
+- one local runtime ledger
+- many side effects across tmux, SSH, and Gitea
+
+It already expresses the philosophy of narrative-driven infrastructure well.
+What it lacks is not architecture.
+What it lacks is hardening:
+- tests around the dangerous paths
+- centralization of duplicated routing truth
+- stronger command / credential / runtime-state safeguards
+
+That makes it a strong control-plane prototype and a weakly tested production surface.

tests/test_burn_fleet_genome.py

@@ -0,0 +1,70 @@
+from pathlib import Path
+
+GENOME = Path('genomes/burn-fleet-GENOME.md')
+
+
+def read_genome() -> str:
+    assert GENOME.exists(), 'burn-fleet genome must exist at genomes/burn-fleet-GENOME.md'
+    return GENOME.read_text(encoding='utf-8')
+
+
+def test_genome_exists():
+    assert GENOME.exists(), 'burn-fleet genome must exist at genomes/burn-fleet-GENOME.md'
+
+
+def test_genome_has_required_sections():
+    text = read_genome()
+    for heading in [
+        '# GENOME.md: burn-fleet',
+        '## Project Overview',
+        '## Architecture',
+        '## Entry Points',
+        '## Data Flow',
+        '## Key Abstractions',
+        '## API Surface',
+        '## Test Coverage Gaps',
+        '## Security Considerations',
+    ]:
+        assert heading in text
+
+
+def test_genome_contains_mermaid_diagram():
+    text = read_genome()
+    assert '```mermaid' in text
+    assert 'graph TD' in text or 'flowchart TD' in text
+
+
+def test_genome_mentions_core_files_and_runtime_state():
+    text = read_genome()
+    for token in [
+        'fleet-spec.json',
+        'fleet-launch.sh',
+        'fleet-christen.py',
+        'fleet-dispatch.py',
+        'fleet-status.py',
+        'dispatch-state.json',
+        'tmux',
+        'ssh',
+        'MAC_ROUTE',
+        'ALLEGRO_ROUTE',
+    ]:
+        assert token in text
+
+
+def test_genome_mentions_test_gap_and_risk_findings():
+    text = read_genome()
+    for token in [
+        '0% estimated coverage',
+        'send_to_pane',
+        'comment_on_issue',
+        'get_pane_status',
+        'requests',
+        'command injection',
+        'credential handling',
+    ]:
+        assert token in text
+
+
+def test_genome_is_substantial():
+    text = read_genome()
+    assert len(text) >= 6000