From 7455d966a1405e4d50ea7766667b76e33aa044ac Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Sun, 15 Mar 2026 22:02:04 +0000
Subject: [PATCH] =?UTF-8?q?Update=20DEV=5FCONTAINER=5FSPEC=20=E2=80=94=20c?=
 =?UTF-8?q?ode-server=20operational,=20routing=20model,=20agent=20status?=
 =?UTF-8?q?=20fields,=20actual=20process=20shape?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DEV_CONTAINER_SPEC.md | 94 ++++++++++++++++++++++++++-----------------
 1 file changed, 56 insertions(+), 38 deletions(-)

diff --git a/DEV_CONTAINER_SPEC.md b/DEV_CONTAINER_SPEC.md
index 8e92bde..40266a0 100644
--- a/DEV_CONTAINER_SPEC.md
+++ b/DEV_CONTAINER_SPEC.md
@@ -27,6 +27,7 @@ Provisioning flow:
 5. Agent installs runtime from artifact server
 6. Agent optionally installs addons
 7. Agent marks container ready
+8. API applies dev routing if code-server is enabled
 
 High-level architecture:
 
@@ -40,6 +41,14 @@ zlh-agent
 Artifact Server
 ```
 
+If `enable_code_server=true`, the API additionally performs:
+
+- Cloudflare DNS record creation
+- Technitium DNS record creation
+- Traefik dynamic config write on `zlh-zpack-proxy`
+
+This routing path is additive and does not modify the game publish flow.
+
 ---
 
 ## Dev Provisioning Payload
@@ -254,58 +263,67 @@ Installed to:
 /opt/zlh/services/code-server
 ```
 
-Launched as:
+Launch behavior:
+
+- process runs inside the container
+- binds to `0.0.0.0:6000`
+- workspace root is `/home/dev/workspace`
+- current auth mode observed in runtime is password-based
+
+Observed process shape:
 
 ```bash
-code-server --bind-addr 0.0.0.0:6000 /home/dev/workspace
-```
-
-Port: `6000`
-
-**Current blocker:** artifact currently contains source repository, not a compiled release. Artifact server must provide a runnable release archive with the following layout:
-
-```
-code-server/
-  bin/code-server
-  lib/
-  node_modules/
+/opt/zlh/services/code-server/lib/node /opt/zlh/services/code-server \
+  --bind-addr 0.0.0.0:6000 \
+  --auth password \
+  /home/dev/workspace
 ```
 
 ---
 
-## Code Server Routing
+## Dev Routing
 
-Code-server is exposed via Traefik + Cloudflare. No SRV records needed — this is standard HTTPS routed by hostname.
+When code-server is enabled, the API creates a dev-only routing path.
+
+Current implementation:
+
+- creates Technitium A record for `dev-<vmid>.<domain>`
+- creates Cloudflare A record for `dev-<vmid>.<domain>`
+- writes Traefik dynamic config on the proxy VM via SSH service account `zlh`
+- dynamic file path: `/etc/traefik/dynamic/dev-<vmid>.yml`
+
+Current backend target model:
 
 ```
-browser
-  ↓
-Cloudflare (*.dev.zerolaghub.com wildcard)
-  ↓
-Traefik (zlh-zpack-proxy, routes by hostname)
-  ↓
-container_ip:6000
+Host(`dev-<vmid>.<domain>`)
+  → Traefik (websecure)
+  → http://<container-ip>:6000
 ```
 
-Technitium A record: `dev-<vmid>.dev.zerolaghub.com` → Traefik proxy IP
+Status: routing generation is implemented, but external browser access remains under active validation.
 
-Traefik dynamic file config example:
+---
 
-```yaml
-http:
-  routers:
-    dev-6049-codeserver:
-      rule: "Host(`dev-6049.dev.zerolaghub.com`)"
-      service: dev-6049-codeserver
-      tls: {}
-  services:
-    dev-6049-codeserver:
-      loadBalancer:
-        servers:
-          - url: "http://<container_ip>:6000"
-```
+## Agent Status Model
 
-The API writes this dynamic config file when a dev container with code-server is provisioned and removes it on deletion. No Traefik restart required.
+Status delivery model is unchanged:
+
+- API polls agent `/status`
+- agent does not push state to API
+
+Status content now includes dev/container fields:
+
+- `workspaceRoot`
+- `serverRoot`
+- `runtimeInstallPath`
+- `runtimeInstalled`
+- `devProvisioned`
+- `devReadyAt`
+- `codeServerInstalled`
+- `codeServerRunning`
+- `lastCrashClassification`
+
+The API now exposes this polled state back to the frontend through a server status endpoint so console and host-state UI can update correctly.
 
 ---