feat: add fleet dispatch planning scaffold (#552)

scripts/dynamic_dispatch_optimizer.py

@@ -1,31 +1,169 @@
 #!/usr/bin/env python3
-import json
-import os
-import yaml
-from pathlib import Path
+"""Dynamic dispatch optimizer for fleet-wide coordination.
 
-# Dynamic Dispatch Optimizer
-# Automatically updates routing based on fleet health.
+Refs: timmy-home #552
+
+Takes a fleet dispatch spec plus optional failover status and produces a
+capacity-aware assignment plan. Safe by default: it prints the plan and only
+writes an output file when explicitly requested.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
 
 STATUS_FILE = Path.home() / ".timmy" / "failover_status.json"
-CONFIG_FILE = Path.home() / "timmy" / "config.yaml"
+SPEC_FILE = Path.home() / ".timmy" / "fleet_dispatch.json"
+OUTPUT_FILE = Path.home() / ".timmy" / "dispatch_plan.json"
+
+
+def load_json(path: Path, default: Any):
+    if not path.exists():
+        return default
+    return json.loads(path.read_text())
+
+
+def _host_status(host: dict[str, Any], failover_status: dict[str, Any]) -> str:
+    if host.get("always_available"):
+        return "ONLINE"
+    fleet = failover_status.get("fleet") or {}
+    return str(fleet.get(host["name"], "ONLINE")).upper()
+
+
+def _lane_matches(host: dict[str, Any], lane: str) -> bool:
+    host_lanes = set(host.get("lanes") or ["general"])
+    if host.get("always_available", False):
+        return True
+    if lane == "general":
+        return "general" in host_lanes
+    return lane in host_lanes
+
+
+def _choose_candidate(task: dict[str, Any], hosts: list[dict[str, Any]]):
+    lane = task.get("lane", "general")
+    preferred = task.get("preferred_hosts") or []
+
+    preferred_map = {host["name"]: host for host in hosts}
+    for host_name in preferred:
+        host = preferred_map.get(host_name)
+        if not host:
+            continue
+        if host["remaining_capacity"] <= 0:
+            continue
+        if _lane_matches(host, lane):
+            return host
+
+    matching = [host for host in hosts if host["remaining_capacity"] > 0 and _lane_matches(host, lane)]
+    if matching:
+        matching.sort(key=lambda host: (host["assigned_count"], -host["remaining_capacity"], host["name"]))
+        return matching[0]
+
+    fallbacks = [host for host in hosts if host["remaining_capacity"] > 0 and host.get("always_available")]
+    if fallbacks:
+        fallbacks.sort(key=lambda host: (host["assigned_count"], -host["remaining_capacity"], host["name"]))
+        return fallbacks[0]
+
+    return None
+
+
+def generate_plan(spec: dict[str, Any], failover_status: dict[str, Any] | None = None) -> dict[str, Any]:
+    failover_status = failover_status or {}
+    raw_hosts = spec.get("hosts") or []
+    tasks = list(spec.get("tasks") or [])
+
+    online_hosts = []
+    offline_hosts = []
+    for host in raw_hosts:
+        normalized = {
+            "name": host["name"],
+            "capacity": int(host.get("capacity", 1)),
+            "remaining_capacity": int(host.get("capacity", 1)),
+            "assigned_count": 0,
+            "lanes": list(host.get("lanes") or ["general"]),
+            "always_available": bool(host.get("always_available", False)),
+            "status": _host_status(host, failover_status),
+        }
+        if normalized["status"] == "ONLINE":
+            online_hosts.append(normalized)
+        else:
+            offline_hosts.append(normalized["name"])
+
+    ordered_tasks = sorted(
+        tasks,
+        key=lambda item: (-int(item.get("priority", 0)), str(item.get("id", ""))),
+    )
+
+    assignments = []
+    unassigned = []
+    for task in ordered_tasks:
+        candidate = _choose_candidate(task, online_hosts)
+        if candidate is None:
+            unassigned.append({
+                "task_id": task.get("id"),
+                "reason": f"no_online_host_for_lane:{task.get('lane', 'general')}",
+            })
+            continue
+
+        candidate["remaining_capacity"] -= 1
+        candidate["assigned_count"] += 1
+        assignments.append({
+            "task_id": task.get("id"),
+            "host": candidate["name"],
+            "lane": task.get("lane", "general"),
+            "priority": int(task.get("priority", 0)),
+        })
+
+    return {
+        "assignments": assignments,
+        "offline_hosts": sorted(offline_hosts),
+        "unassigned": unassigned,
+    }
+
+
+def write_plan(plan: dict[str, Any], output_path: Path):
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(plan, indent=2))
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Generate a fleet dispatch plan from host health and task demand.")
+    parser.add_argument("--spec-file", type=Path, default=SPEC_FILE, help="JSON fleet spec with hosts[] and tasks[]")
+    parser.add_argument("--status-file", type=Path, default=STATUS_FILE, help="Failover monitor JSON payload")
+    parser.add_argument("--output", type=Path, default=OUTPUT_FILE, help="Output path for the generated plan")
+    parser.add_argument("--write-output", action="store_true", help="Persist the generated plan to --output")
+    parser.add_argument("--json", action="store_true", help="Print JSON only")
+    return parser.parse_args()
+
 
 def main():
-    print("--- Allegro's Dynamic Dispatch Optimizer ---")
-    if not STATUS_FILE.exists():
-        print("No failover status found.")
+    args = parse_args()
+    spec = load_json(args.spec_file, {"hosts": [], "tasks": []})
+    failover_status = load_json(args.status_file, {})
+    plan = generate_plan(spec, failover_status)
+
+    if args.write_output:
+        write_plan(plan, args.output)
+
+    if args.json:
+        print(json.dumps(plan, indent=2))
         return
 
-    status = json.loads(STATUS_FILE.read_text())
-    fleet = status.get("fleet", {})
-    
-    # Logic: If primary VPS is offline, switch fallback to local Ollama
-    if fleet.get("ezra") == "OFFLINE":
-        print("Ezra (Primary) is OFFLINE. Optimizing for local-only fallback...")
-        # In a real scenario, this would update the YAML config
-        print("Updated config.yaml: fallback_model -> ollama:gemma4:12b")
-    else:
-        print("Fleet health is optimal. Maintaining high-performance routing.")
+    print("--- Dynamic Dispatch Optimizer ---")
+    print(f"Assignments: {len(plan['assignments'])}")
+    if plan["offline_hosts"]:
+        print("Offline hosts: " + ", ".join(plan["offline_hosts"]))
+    for assignment in plan["assignments"]:
+        print(f"- {assignment['task_id']} -> {assignment['host']} ({assignment['lane']}, p={assignment['priority']})")
+    if plan["unassigned"]:
+        print("Unassigned:")
+        for item in plan["unassigned"]:
+            print(f"- {item['task_id']}: {item['reason']}")
+    if args.write_output:
+        print(f"Wrote plan to {args.output}")
+
 
 if __name__ == "__main__":
     main()

tests/test_dynamic_dispatch_optimizer.py

@@ -0,0 +1,79 @@
+import json
+
+from scripts.dynamic_dispatch_optimizer import generate_plan, write_plan
+
+
+def test_generate_plan_rebalances_offline_host_tasks_to_online_capacity():
+    spec = {
+        "hosts": [
+            {"name": "ezra", "capacity": 2, "lanes": ["research", "general"]},
+            {"name": "bezalel", "capacity": 2, "lanes": ["build", "general"]},
+            {"name": "local", "capacity": 1, "lanes": ["general"], "always_available": True},
+        ],
+        "tasks": [
+            {"id": "ISSUE-1", "lane": "build", "priority": 100},
+            {"id": "ISSUE-2", "lane": "general", "priority": 80},
+            {"id": "ISSUE-3", "lane": "research", "priority": 60},
+        ],
+    }
+    failover_status = {"fleet": {"ezra": "ONLINE", "bezalel": "OFFLINE"}}
+
+    plan = generate_plan(spec, failover_status)
+
+    assignments = {item["task_id"]: item["host"] for item in plan["assignments"]}
+    assert assignments == {
+        "ISSUE-1": "local",
+        "ISSUE-2": "ezra",
+        "ISSUE-3": "ezra",
+    }
+    assert plan["offline_hosts"] == ["bezalel"]
+    assert plan["unassigned"] == []
+
+
+def test_generate_plan_prefers_preferred_host_when_online():
+    spec = {
+        "hosts": [
+            {"name": "ezra", "capacity": 2, "lanes": ["general"]},
+            {"name": "bezalel", "capacity": 2, "lanes": ["general"]},
+        ],
+        "tasks": [
+            {"id": "ISSUE-9", "lane": "general", "priority": 100, "preferred_hosts": ["bezalel", "ezra"]},
+        ],
+    }
+
+    plan = generate_plan(spec, {"fleet": {"ezra": "ONLINE", "bezalel": "ONLINE"}})
+
+    assert plan["assignments"] == [
+        {"task_id": "ISSUE-9", "host": "bezalel", "lane": "general", "priority": 100}
+    ]
+
+
+def test_generate_plan_reports_unassigned_when_no_host_matches_lane():
+    spec = {
+        "hosts": [
+            {"name": "ezra", "capacity": 1, "lanes": ["research"]},
+        ],
+        "tasks": [
+            {"id": "ISSUE-5", "lane": "build", "priority": 50},
+        ],
+    }
+
+    plan = generate_plan(spec, {"fleet": {"ezra": "ONLINE"}})
+
+    assert plan["assignments"] == []
+    assert plan["unassigned"] == [
+        {"task_id": "ISSUE-5", "reason": "no_online_host_for_lane:build"}
+    ]
+
+
+def test_write_plan_persists_json(tmp_path):
+    plan = {
+        "assignments": [{"task_id": "ISSUE-1", "host": "ezra", "lane": "general", "priority": 10}],
+        "offline_hosts": [],
+        "unassigned": [],
+    }
+    output_path = tmp_path / "dispatch-plan.json"
+
+    write_plan(plan, output_path)
+
+    assert json.loads(output_path.read_text()) == plan

the-nexus-GENOME.md

@@ -1,319 +0,0 @@
-# GENOME.md — the-nexus
-
-**Generated:** 2026-04-14  
-**Repo:** Timmy_Foundation/the-nexus  
-**Analysis:** Codebase Genome #672
-
----
-
-## Project Overview
-
-The Nexus is Timmy's canonical 3D home-world — a browser-based Three.js application that serves as:
-1. **Local-first training ground** for Timmy (the sovereign AI)
-2. **Wizardly visualization surface** for the fleet system
-3. **Portal architecture** connecting to other worlds and services
-
-The app is a real-time 3D environment with spatial memory, GOFAI reasoning, agent presence, and portal-based navigation.
-
----
-
-## Architecture
-
-```mermaid
-graph TB
-    subgraph Browser["BROWSER LAYER"]
-        HTML[index.html]
-        APP[app.js - 4082 lines]
-        CSS[style.css]
-        Worker[gofai_worker.js]
-    end
-    
-    subgraph ThreeJS["THREE.JS RENDERING"]
-        Scene[Scene Management]
-        Camera[Camera System]
-        Renderer[WebGL Renderer]
-        Post[Post-processing<br/>Bloom, SMAA]
-        Physics[Physics/Player]
-    end
-    
-    subgraph Nexus["NEXUS COMPONENTS"]
-        SM[SpatialMemory]
-        SA[SpatialAudio]
-        MB[MemoryBirth]
-        MO[MemoryOptimizer]
-        MI[MemoryInspect]
-        MP[MemoryPulse]
-        RT[ReasoningTrace]
-        RV[ResonanceVisualizer]
-    end
-    
-    subgraph GOFAI["GOFAI REASONING"]
-        Worker2[Web Worker]
-        Rules[Rule Engine]
-        Facts[Fact Store]
-        Inference[Inference Loop]
-    end
-    
-    subgraph Backend["BACKEND SERVICES"]
-        Server[server.py<br/>WebSocket Bridge]
-        L402[L402 Cost API]
-        Portal[Portal Registry]
-    end
-    
-    subgraph Data["DATA/PERSISTENCE"]
-        Local[localStorage]
-        IDB[IndexedDB]
-        JSON[portals.json]
-        Vision[vision.json]
-    end
-    
-    HTML --> APP
-    APP --> ThreeJS
-    APP --> Nexus
-    APP --> GOFAI
-    APP --> Backend
-    APP --> Data
-    
-    Worker2 --> APP
-    Server --> APP
-```
-
----
-
-## Entry Points
-
-### Primary Entry
-- **`index.html`** — Main HTML shell, loads app.js
-- **`app.js`** — Main application (4082 lines), Three.js scene setup
-
-### Secondary Entry Points
-- **`boot.js`** — Bootstrap sequence
-- **`bootstrap.mjs`** — ES module bootstrap
-- **`server.py`** — WebSocket bridge server
-
-### Configuration Entry Points
-- **`portals.json`** — Portal definitions and destinations
-- **`vision.json`** — Vision/agent configuration
-- **`config/fleet_agents.json`** — Fleet agent definitions
-
----
-
-## Data Flow
-
-```
-User Input
-    ↓
-app.js (Event Loop)
-    ↓
-┌─────────────────────────────────────┐
-│ Three.js Scene                      │
-│ - Player movement                   │
-│ - Camera controls                   │
-│ - Physics simulation                │
-│ - Portal detection                  │
-└─────────────────────────────────────┘
-    ↓
-┌─────────────────────────────────────┐
-│ Nexus Components                    │
-│ - SpatialMemory (room/context)      │
-│ - MemoryBirth (new memories)        │
-│ - MemoryPulse (heartbeat)           │
-│ - ReasoningTrace (GOFAI output)     │
-└─────────────────────────────────────┘
-    ↓
-┌─────────────────────────────────────┐
-│ GOFAI Worker (off-thread)           │
-│ - Rule evaluation                   │
-│ - Fact inference                    │
-│ - Decision making                   │
-└─────────────────────────────────────┘
-    ↓
-┌─────────────────────────────────────┐
-│ Backend Services                    │
-│ - WebSocket (server.py)             │
-│ - L402 cost API                     │
-│ - Portal registry                   │
-└─────────────────────────────────────┘
-    ↓
-Persistence (localStorage/IndexedDB)
-```
-
----
-
-## Key Abstractions
-
-### 1. Nexus Object (`NEXUS`)
-Central configuration and state object containing:
-- Color palette
-- Room definitions
-- Portal configurations
-- Agent settings
-
-### 2. SpatialMemory
-Manages room-based context for the AI agent:
-- Room transitions trigger context switches
-- Facts are stored per-room
-- NPCs have location awareness
-
-### 3. Portal System
-Connects the 3D world to external services:
-- Portals defined in `portals.json`
-- Each portal links to a service/endpoint
-- Visual indicators in 3D space
-
-### 4. GOFAI Worker
-Off-thread reasoning engine:
-- Rule-based inference
-- Fact store with persistence
-- Decision making for agent behavior
-
-### 5. Memory Components
-- **MemoryBirth**: Creates new memories from interactions
-- **MemoryOptimizer**: Compresses and deduplicates memories
-- **MemoryPulse**: Heartbeat system for memory health
-- **MemoryInspect**: Debug/inspection interface
-
----
-
-## API Surface
-
-### Internal APIs (JavaScript)
-
-| Module | Export | Purpose |
-|--------|--------|---------|
-| `app.js` | `NEXUS` | Main config/state object |
-| `SpatialMemory` | class | Room-based context management |
-| `SpatialAudio` | class | 3D positional audio |
-| `MemoryBirth` | class | Memory creation |
-| `MemoryOptimizer` | class | Memory compression |
-| `ReasoningTrace` | class | GOFAI reasoning visualization |
-
-### External APIs (HTTP/WebSocket)
-
-| Endpoint | Protocol | Purpose |
-|----------|----------|---------|
-| `ws://localhost:PORT` | WebSocket | Real-time bridge to backend |
-| `http://localhost:8080/api/cost-estimate` | HTTP | L402 cost estimation |
-| Portal endpoints | Various | External service connections |
-
----
-
-## Dependencies
-
-### Runtime Dependencies
-- **Three.js** — 3D rendering engine
-- **Three.js Addons** — Post-processing (Bloom, SMAA)
-
-### Build Dependencies
-- **ES Modules** — Native browser modules
-- **No bundler** — Direct script loading
-
-### Backend Dependencies
-- **Python 3.x** — server.py
-- **WebSocket** — Real-time communication
-
----
-
-## Test Coverage
-
-### Existing Tests
-- `tests/boot.test.js` — Bootstrap sequence tests
-
-### Test Gaps
-1. **Three.js scene initialization** — No tests
-2. **Portal system** — No tests
-3. **Memory components** — No tests
-4. **GOFAI worker** — No tests
-5. **WebSocket communication** — No tests
-6. **Spatial memory transitions** — No tests
-7. **Physics/player movement** — No tests
-
-### Recommended Test Priorities
-1. Portal detection and activation
-2. Spatial memory room transitions
-3. GOFAI worker message passing
-4. WebSocket connection handling
-5. Memory persistence (localStorage/IndexedDB)
-
----
-
-## Security Considerations
-
-### Current Risks
-1. **WebSocket without auth** — server.py has no authentication
-2. **localStorage sensitive data** — Memories stored unencrypted
-3. **CORS open** — No origin restrictions on WebSocket
-4. **L402 endpoint** — Cost API may expose internal state
-
-### Mitigations
-1. Add WebSocket authentication
-2. Encrypt sensitive memories
-3. Restrict CORS origins
-4. Rate limit L402 endpoint
-
----
-
-## File Structure
-
-```
-the-nexus/
-├── app.js                    # Main app (4082 lines)
-├── index.html                # HTML shell
-├── style.css                 # Styles
-├── server.py                 # WebSocket bridge
-├── boot.js                   # Bootstrap
-├── bootstrap.mjs             # ES module bootstrap
-├── gofai_worker.js           # GOFAI web worker
-├── portals.json              # Portal definitions
-├── vision.json               # Vision config
-├── nexus/                    # Nexus components
-│   └── components/
-│       ├── spatial-memory.js
-│       ├── spatial-audio.js
-│       ├── memory-birth.js
-│       ├── memory-optimizer.js
-│       ├── memory-inspect.js
-│       ├── memory-pulse.js
-│       ├── reasoning-trace.js
-│       └── resonance-visualizer.js
-├── config/                   # Configuration
-├── docs/                     # Documentation
-├── tests/                    # Tests
-├── agent/                    # Agent components
-├── bin/                      # Scripts
-└── assets/                   # Static assets
-```
-
----
-
-## Technical Debt
-
-1. **Large app.js** (4082 lines) — Should be split into modules
-2. **No TypeScript** — Pure JavaScript, no type safety
-3. **Manual DOM manipulation** — Could use a framework
-4. **No build system** — Direct ES modules, no optimization
-5. **Limited error handling** — Minimal try/catch coverage
-
----
-
-## Migration Notes
-
-From CLAUDE.md:
-- Current `main` does NOT ship the old root frontend files
-- A clean checkout serves a directory listing
-- The live browser shell exists in legacy form at `/Users/apayne/the-matrix`
-- Migration priorities: #684 (docs), #685 (legacy audit), #686 (smoke tests), #687 (restore shell)
-
----
-
-## Next Steps
-
-1. **Restore browser shell** — Bring frontend back to main
-2. **Add tests** — Cover critical paths (portals, memory, GOFAI)
-3. **Split app.js** — Modularize the 4082-line file
-4. **Add authentication** — Secure WebSocket and APIs
-5. **TypeScript migration** — Add type safety
-
----
-
-*Generated by Codebase Genome pipeline — Issue #672*