# Open Threads – zlh-grind

This file tracks active but unfinished work.

Keep it short.

---

## Agent (zlh-agent)

### Dev Runtime System

Completed:

- catalog validation implemented
- runtime installs artifact-backed
- install guard implemented

Outstanding:

- runtime install verification improvements
- catalog hash validation
- runtime removal / upgrade handling

---

### Dev Environment

Completed:

- dev user creation
- workspace root `/home/dev/workspace`
- console runs as dev user

Outstanding:

- PATH normalization
- shell profile consistency
- runtime PATH injection

---

## Code Server Addon

Status: ✅ Installed and running inside dev containers

Confirmed:

- compiled release artifact fixed on `zlh-artifacts`
- install confirmed working
- process confirmed running inside container
- binds to `0.0.0.0:6000`
- launched from `/opt/zlh/services/code-server`

Port: `6000`

**Next session — agent change required:**

code-server must be relaunched with:

```
--auth none
--base-path /api/dev/<vmid>/ide
```

Reason: API token is now the sole auth mechanism. Password prompt must be removed. Base path required for correct asset loading through proxy.

---

## Dev IDE Access

### Browser IDE (Implemented ✅)

```
Browser
  ↓
Portal
  ↓
API (/api/dev/:id/ide)
  ↓
container:6000
```

Implemented in API:

- `src/routes/devProxy.js` — proxy route mounted in `src/app.js`
- `GET /api/dev/:id/ide` and `GET /api/dev/:id/ide/*`
- ownership verification before proxying
- `ctype === "dev"` required
- WebSocket support via `http-proxy-middleware` (`ws: true`)
- `server.on('upgrade')` handler wired

IDE token system implemented:

- `POST /api/dev/:id/ide-token` — returns signed short-lived token
- token payload: `sub`, `vmid`, `type: "dev-ide"`
- default TTL: 300 seconds
- env overrides: `API_AUTH_IDE_TTL_SECONDS`, `API_AUTH_IDE_SECRET`
- proxy accepts `Authorization: Bearer` or `?token=<ide-token>`
- WebSocket upgrades validate same token

### Local Dev Access (Headscale/Tailscale — Future)

Outstanding:

- confirm `zlh-ctl` Headscale server status
- implement Tailscale addon install in agent
- API auth key generation
- portal setup instructions

Constraints:

- `magic_dns: false`
- no exit nodes
- no DNS takeover

---

## Agent Future Work (priority order)

1. Update code-server launch args (`--auth none`, `--base-path /api/dev/<vmid>/ide`)
2. Structured logging (slog) for Loki
3. Dev container provisioningComplete state
4. Crash recovery backoff
5. Graceful shutdown verification
6. Process reattachment on agent restart

---

## API (zpack-api)

Completed:

- dev provisioning payload
- runtime/version fields
- enable_code_server flag
- `GET /api/servers/:id/status` — server status endpoint
- `POST /api/dev/:id/ide-token` — IDE token generation
- `GET /api/dev/:id/ide` — IDE proxy route with WebSocket support
- dev routing experiment removed (`devRouting.js`, `devDePublisher.js` deleted)

Outstanding:

- dev runtime catalog endpoint for portal
- Headscale auth key generation

---

## Portal (zpack-portal)

Completed:

- dev runtime dropdown
- dotnet runtime support
- enable code-server checkbox
- dev file browser support

Outstanding:

- "Open IDE" button — calls `POST /api/dev/:id/ide-token`, opens returned URL in new tab
- Headscale setup instructions

---

## Platform

Future work:

- Tailscale dev access
- artifact version promotion
- runtime rollback support

---

## Closed Threads

- ✅ PTY console (dev + game)
- ✅ Mod lifecycle
- ✅ Upload pipeline
- ✅ Runtime artifact installs
- ✅ Dev container filesystem model
- ✅ Code-server artifact fix
- ✅ API status endpoint for frontend agent-state consumption
- ✅ Dev IDE proxy implementation (API proxy + token system)
- ✅ Dev DNS/Traefik routing experiment — removed