Session Log – zlh-grind

Append-only execution log for GPT work.

2025-12-13

Goal: Establish zlh-grind as the execution ledger and drift firewall.
Scope: Repo scaffolding + constraints + session templates.
Explicit non-goals: Any architecture or canonical docs changes.
Canonical refs used: jester/knowledge-base (Drift card, tracker, GPT handover).

Work completed:

Verified Gitea MCP connectivity (server version 0.5.0+2-g8b06d71).
Confirmed jester/zlh-grind exists.
Added repo-level drift controls:
- CONSTRAINTS.md
- SESSION_START.md
- OPEN_THREADS.md
- SESSION_LOG.md
Added explicit guardrail doc: ANTI_DRIFT.md.
Stabilized MCP routing and validated the Knowledge tool is working reliably.
Tagged jester/zlh-agent with annotated tag v0.1.0-dev.
Added UPSTREAMS.md to register canonical + execution repos and the Go agent repo.
Registered the API repo jester/zlh-api in UPSTREAMS.md.
Verified zlh-api contents are present and created annotated tag v0.1.0-dev for shared visibility (no more copy/paste).

Notes:

Goal: Stabilize zlh-agent dev containers + addons without regressing game provisioning.
Scope: Agent routing (ctype=dev), local artifacts strategy, addon skeleton, initial end-to-end tests.

Work completed:

Confirmed game server provisioning remains intact:
- Minecraft vanilla provision + connect verified.
- Minecraft forge provision verified (client connect pending).
zlh-agent builds cleanly after resolving import cycles introduced by devcontainer/addons packages.
Adopted single base template approach (zlh-base) for both game + dev; agent performs runtime installs.
Standardized devcontainer workspace defaults:
- user: devuser
- workspace: /home/devuser/Workspace
- workspace.sh will own user/workspace creation (shared, not per-runtime).
Addons are cross-cutting (not dev-only). code-server added as first addon skeleton (install/verify + scripts pathing).
Local/offline artifacts strategy locked in (no external downloads during provisioning).
Artifacts staged on artifacts host under /opt/zlh:
- devcontainer/node: 20, 22, 24 (LTS default = latest LTS)
- devcontainer/python: 3.10, 3.11, 3.12, 3.13
- devcontainer/java: 17, 19, 21
- devcontainer/go: 1.22, 1.25
- addons/code-server: code-server.zip
Frontend policy decided: show latest LTS as default; allow older versions with "buyer beware" warning.

Issues found:

API (zpack-api) still assumes game containers; dev payload fails validation with "game required".
Config schema mismatch spotted: node verify referenced cfg.RuntimeVersion, but state.Config currently lacks RuntimeVersion.
- Decision pending: add RuntimeVersion to Config vs reuse existing version field for dev runtimes.
code-server will require systemd + Traefik reverse proxy integration (tracked as TODO).

Next steps:

Update zpack-api to be ctype-aware (dev containers must not require game/variant/world).
Finalize runtime version field strategy (version vs runtimeVersion) across API + agent + DB payload.
Complete node install.sh to use local artifacts and validate verify.go; then repeat for python/java/go.
Define addon dispatch + payload schema for addons (cross-cutting) and later store customer addon selections.

Session “auto-proceed” rule (next session): Proceed without asking when changes are localized/low-risk (internal refactors, helpers, file organization) and do not alter public API contracts, DB schemas, or game provisioning paths. Pause and ask for anything cross-repo, persistent, user-facing, or that could regress game provisioning.
zpack-api refactor direction: Split provisionAgent into an orchestration entrypoint plus provisionGame and provisionDev handlers selected by ctype. Keep shared infra (Proxmox calls, VMID/ports allocation, agent HTTP) centralized; only split validation + payload shaping per ctype.