Session Log

2026-03-10

Closed: Upload transport timeout tuning — upload route now logs explicit error categories distinguishing client abort, upstream timeout, and socket reset.
Research: Investigated external agent standards applicable to zlh-agent. No formal standard maps cleanly — agent is purpose-built (embedded process manager + filesystem authority inside LXC, internal-only caller). Key findings: health probe split (/healthz liveness vs /readyz readiness) is a common convention but not required given single-caller architecture; graceful shutdown (SIGINT/SIGTERM, 10s timeout) is correct; structured lifecycle logging already solid; Go 1.21 slog exists if log unification is ever wanted. No open threads opened from this — no gaps requiring action.
Grind repo updated to reflect current platform state. Misplaced architecture docs later removed — canonical docs belong in knowledge-base not zlh-grind.

Goal: Stabilize dev container provisioning across agent, portal, and artifact server.

Work completed:

Agent:

catalog-driven runtime validation via devcontainer/_catalog.json (ValidateRuntimeSelection in common.go)
EnsureDevUserEnvironment — dev user, /home/dev/workspace, correct ownership
dotnet runtime provisioning added
optional code-server addon provisioning added
WriteReadyMarker after successful provision
RuntimeInstalled() filesystem-based install guard in common.go

Portal:

API:

Blocker:

code-server artifact on zlh-artifacts contains source repository, not compiled release
install.sh expects bin/code-server, lib/, node_modules/ — compiled release required
fix: replace artifact with official code-server release tarball (e.g. code-server-4.x.x-linux-amd64.tar.gz)

Architecture review session. Key decisions and findings:

Dev container model:

1 server / 1 container / 1 world confirmed as correct model
Dev containers: full R/W access under /home/dev/workspace, no allowlist
Multiverse/multi-world via plugins is customer-managed, not a platform concern
Port exposure (dev-.zerolaghub.com) identified as next major dev feature — future work
dotnet SDK covers all C# game modding (Valheim, Core Keeper, Vintage Story, Rust/Oxide)
Code Server confirmed as correct browser IDE approach given single public IP constraint
Traefik dynamic file provider confirmed as correct routing approach — no plugin needed, no SRV records needed

Agent review (zlh-agent commit 6019d0bc — 2026-03-15):

Catalog transition confirmed correct — ValidateRuntimeSelection gates all dev provisions
Scripts unchanged — embedded script execution via bash stdin pipe, no 126 risk from runtime installs
devcontainer/common.go is clean and complete
node/verify.go has hardcoded /opt/zlh/runtime/node/bin/node — wrong path, pre-existing issue
node/python/go/java install packages still use old version-unaware marker pattern — pre-existing, not a regression

Agent future work (priority order):

Unified structured logging (slog) — Promtail/Loki integration needs structured fields
Dev container /status — provisioningComplete + provisioningError fields
Crash recovery with backoff — 30s/60s/120s, max 3 attempts, then error state
Graceful shutdown verification — SIGTERM + wait before SIGKILL for Minecraft world save safety
Agent restart/process reattachment — detect existing process on restart

Code-server routing:

Artifact fix confirmed working 2026-03-15
Binary confirmed present at /opt/zlh/services/code-server/bin/code-server
Root cause of ERR_CONNECTION_CLOSED identified: code-server is installed but never launched
Port conflict: Node runtime is binding 6000, code-server cannot share the port
Two fixes needed:
1. Assign code-server a port that won't conflict with Node (6000 taken)
2. Add launch step to addon install script — install != start, binary must be daemonized after provisioning
Suggested launch: nohup /opt/zlh/services/code-server/bin/code-server --bind-addr 0.0.0.0: --auth none /home/dev/workspace > /opt/zlh-agent/logs/code-server.log 2>&1 &