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