# zlh-grind

Execution workspace for **ZeroLagHub (ZLH)**.

This repository is intentionally lightweight and is used for:
- project handovers / "where we left off" notes
- architecture decisions and rationale
- system constraints and guardrails
- scratch investigations that shouldn't live in code repos

---

## Latest handover (2026-02-22)

### System state (high confidence)
- **PTY-backed consoles are stable** (dev + game) and no longer depend on log tailing.
- **Customer isolation is enforced** end-to-end (API auth → ownership checks → per-customer data).
- **Agent update system is operational** (versioned, SHA-verified) with periodic checks.
- **Game telemetry is now separated** behind a dedicated API router (`/api/game/*`).

### What shipped since the prior handover

#### API (control plane)
- Added `src/routes/game.js` and mounted at `/api/game`.
- Added `GET /api/game/servers/:id/players` (reads Redis `agent:<vmid>`; returns normalized `{ vmid, playerCount, players, max, timestamp }`).
- Extended `src/utils/agentPoller.js`:
  - polls agent `GET /game/players` for **game** containers and caches in Redis.
  - polls agent `GET /version` and `GET /agent/update/status`; derives `updateAvailable`.
- Added `GET /api/game/servers/:id/update-status` (returns agent version + update state).
- Provisioning persists engine metadata:
  - `engineType = "minecraft"` for game containers
  - `engineVersion` from payload
  - dev containers set both to `null`
- Rolled back API-triggered update during provisioning (back to direct `/config` provisioning flow).

#### Frontend (portal)
- Game console now polls:
  - `GET /api/game/servers/:id/players`
  - `GET /api/game/servers/:id/update-status`
- Player presence shows count + optional name list.
- Version context displayed as `Version: X` or `Version: X -> Y`.
- Auth behavior unchanged (all calls through `apiClient` with JWT Bearer).

#### Agent (runtime)
- `GET /game/players` hardened for reliability (port/protocol fallbacks).
- Added periodic update checks:
  - `ZLH_AGENT_UPDATE_MODE=notify|auto|off`
  - `ZLH_AGENT_UPDATE_INTERVAL` (default `30m`; first check ~10s after boot)
- Added Phase 1 mod management endpoints:
  - `GET /game/mods`
  - `POST /game/mods/install`
  - `PATCH /game/mods/:mod_id`
  - `DELETE /game/mods/:mod_id`
- Added `GET /metrics/process` (PID + memory via `/proc/<pid>/status`, restart_count mapped to crash count).
- Added Minecraft readiness probe after start/restart + stop-wait-before-restart sync to reduce restart races.
- Logging improved with `lifecycle.log` alongside `agent.log`.

#### Artifacts
- Artifact tree expanded to include **NeoForge** under `.../minecraft/neoforge/<mc_version>/`.
- Phase 1 contract: NeoForge installer filename is normalized to `neoforge-installer.jar` within the version directory.

---

## Primary focus moving forward

1. **API proxy endpoints for mods + process metrics** (to mirror agent capabilities behind auth/ownership).
2. **Artifact catalog + ingestion workflow** (Modrinth/NeoForge local-first, approval-gated).
3. **Frontend Mods UI** (installed mods list + enable/disable/remove + curated install; upload likely Phase 2).
4. **Concurrent provisioning validation** (multi-user parallel create + port allocation + isolation).

See:
- `OPEN_THREADS.md` for remaining work
- `CONSTRAINTS.md` + `ANTI_DRIFT*.md` for guardrails
- `SESSION_LOG.md` for a chronological ledger