From 234cf34eb09512a7553a8e0d9bcad57faed7e0cb Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Thu, 16 Apr 2026 19:07:51 +0000
Subject: [PATCH] Add Codex repo-specific tracking structure

---
 Codex/API/CURRENT_STATE.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 Codex/API/CURRENT_STATE.md

diff --git a/Codex/API/CURRENT_STATE.md b/Codex/API/CURRENT_STATE.md
new file mode 100644
index 0000000..962ec29
--- /dev/null
+++ b/Codex/API/CURRENT_STATE.md
@@ -0,0 +1,38 @@
+# API — Current State
+
+This file records what is believed to be implemented now.
+
+## Readiness / agent state model
+- API is the heartbeat authority by polling agents.
+- Agent does not push state to API.
+- API consumes:
+  - `/health` for liveness
+  - `/ready` for semantic readiness
+  - `/status` for detailed state snapshot
+- Portal should rely on API-normalized state, not direct agent state.
+
+## Readiness cleanup already done
+- `agentClient.js` centralizes non-streaming agent transport.
+- `getAgentReady()` remains low-level transport.
+- `isAgentReadyResult()` is the shared semantic readiness helper.
+- `assertAgentReady()` uses semantic readiness.
+- Poller only caches `ready: true` when `/ready` returns semantic success.
+- Provisioning requires semantic readiness before success/persist/publish.
+
+## Backup support
+- API forwards game backup operations.
+- Current API route shape:
+  - `GET /api/game/servers/:id/backups`
+  - `POST /api/game/servers/:id/backups`
+  - `POST /api/game/servers/:id/backups/restore?id=<backup_id>`
+  - `DELETE /api/game/servers/:id/backups/:backupId`
+- API preserves useful agent semantics such as `404`, `409`, and readiness-oriented failures where possible.
+
+## Agent contract alignment already done
+- `/start`, `/stop`, `/restart` forwarded as POST.
+- `/console/command` forwarded as POST JSON.
+- `/ready` is part of poller/readiness logic.
+
+## Still true
+- websocket console proxy wiring remains outside `agentClient.js`
+- raw streaming upload proxy behavior remains outside `agentClient.js`