From c5f4b9ddb5187eacaab1a99deff4750edf92ea9c Mon Sep 17 00:00:00 2001 From: jester Date: Fri, 10 Apr 2026 19:00:33 +0000 Subject: [PATCH] Add MCP dev mode chat handover doc for cross-chat continuity --- .../mcp-dev-mode-chat-handover-apr10-2026.md | 228 ++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 SCRATCH/mcp-dev-mode-chat-handover-apr10-2026.md diff --git a/SCRATCH/mcp-dev-mode-chat-handover-apr10-2026.md b/SCRATCH/mcp-dev-mode-chat-handover-apr10-2026.md new file mode 100644 index 0000000..12e1dc0 --- /dev/null +++ b/SCRATCH/mcp-dev-mode-chat-handover-apr10-2026.md @@ -0,0 +1,228 @@ +# MCP Dev Mode Chat Handover — Apr 10, 2026 + +## Why this exists + +This doc captures important context from the current GPT session because MCP/Gitea access in dev mode does **not** carry memory across chats. + +Use this file as a fast resume point for future sessions. + +--- + +## What was reviewed across repos + +### Repos reviewed +- `zlh-grind` +- `knowledge-base` +- `zlh-agent` +- `zpack-api` +- `zpack-portal` +- `ZpackVelocityBridge` + +### Trust order established +1. `knowledge-base` for canonical architecture +2. `zlh-grind` for current execution state / handover +3. source repos for implementation truth +4. older docs/logs only when needed + +Important nuance: +- `INFRASTRUCTURE.md` had been overwritten/truncated and was restored during this session. + +--- + +## Infrastructure doc recovery completed + +### What happened +- `zlh-grind/INFRASTRUCTURE.md` had been overwritten down to a single PBS row. +- History was checked and the earlier full infrastructure version was recovered from Git history. +- The current surviving PBS row data was preserved and merged into the restored file. + +### Recovery actions completed +- Restored full infra doc structure +- Preserved `9017 zlh-back` current data: + - `10.60.0.24` + - `172.60.0.30` +- Corrected router WAN IPs: + - `9001 zlh-router` → `66.163.115.221` + - `9002 zpack-router` → `66.163.115.115` +- Removed obsolete `internal.zlh` inventory section +- Replaced that with a note that `internal.zlh` is not used for current hot-path service discovery + +### Current status +- `INFRASTRUCTURE.md` is usable again as a working infra reference +- It should still get a quick sanity pass if any other VM/IP rows changed after Apr 2, 2026 + +--- + +## Cross-repo architecture understanding established + +### Confirmed architecture +- Portal → API → Agent +- Hosted IDE access is API-mediated +- Console access is API websocket bridge mediated +- Agent owns runtime/filesystem execution +- Velocity consumes platform state sourced through the API / plugin path + +### Repo-specific conclusions + +#### `zpack-api` +Confirmed in source: +- hosted IDE flow is implemented in `src/routes/devProxy.js` +- console proxy is implemented in `src/routes/consoleProxy.js` +- internal Velocity server-list endpoint is implemented in `src/routes/internalVelocity.js` +- game/server lifecycle orchestration is handled through API routes like `servers.js` + +#### `zpack-portal` +Confirmed in source: +- Open IDE uses the newer API-mediated flow (`POST /api/dev/:vmid/ide-token`) +- Console uses the API websocket bridge path +- Portal still has some migration debt via `src/lib/api/legacy.ts` +- `testdameon`/`testdaemon` style cleanup debt had been noted earlier in review + +#### `zlh-agent` +Confirmed in source: +- real Minecraft readiness probing exists in `internal/minecraft/readiness.go` +- agent has Fabric-specific provisioning support +- likely unresolved issue is sequencing/use of readiness, not total lack of Fabric support + +--- + +## Important correction on Velocity / registration model + +Earlier working assumption was that the API might directly push registration into Velocity. + +After code review, the more accurate model is: +- API exposes server inventory/state +- Velocity plugin consumes that information and performs actual server registration inside Velocity + +So the plugin is a key part of the registration/readiness path. + +--- + +## `ZpackVelocityBridge` review summary + +### Repo hygiene +- Repo was initially pushed with generated Gradle junk (`.gradle/`, `build/`) +- User deleted and recreated repo +- Cleaner push landed afterward +- Current repo is clean of generated build junk +- Remaining mild annoyance: extra top-level folder `ZpackVelocityBridge/` still exists +- This nesting is not a blocker, just mildly inconvenient + +### Key plugin findings + +#### 1. The plugin does actual Velocity registration +`ServerRegistry.java` performs: +- `proxy.registerServer(...)` +- `proxy.unregisterServer(...)` + +So plugin code is the component actually adding/removing backends in Velocity. + +#### 2. The plugin startup flow pulls from API +In `ZpackVelocityBridge.java`, startup rehydrate pulls backend inventory from the API. + +Important detail found during review: +- the default endpoint still points to `zpack-api.internal.zlh` +- that default is stale relative to the current architecture unless overridden externally + +#### 3. The plugin likely ignores readiness during startup rehydrate +Most important finding from plugin review: +- plugin startup rehydrate appears to register servers returned by the API +- it does **not** appear to require `ready == true` before registration + +This is likely the core explanation for Fabric being surfaced too early. + +Better phrasing of the bug: +- API/plugin path is exposing/registering a backend while the Minecraft/Fabric server is `running` but not actually `ready` + +#### 4. Plugin also exposes webhook-style HTTP endpoints +From `ZpackHttpHandlers.java`: +- `POST /zpack/register` +- `POST /zpack/unregister` +- `GET /zpack/status` + +So plugin supports both: +- startup/API rehydrate +- webhook-style live register/unregister + +Needs future verification: +- is anything actually calling these webhook endpoints in production now? +- or is plugin state mostly startup snapshot + manual restarts? + +#### 5. Routing layer is simple and not the bug +`RoutingHandler.java` does: +- hostname exact match first +- single-server fallback when only one backend exists +- otherwise deny + +Routing is consuming registry state, not deciding readiness. + +--- + +## Most likely active technical issue now + +### Best current diagnosis +The most likely active Minecraft/Fabric issue is: + +> The API/plugin path is allowing a backend to be registered in Velocity when the server is `running` but not actually `ready`. + +This is more precise than the earlier broader theory about generic Fabric artifact mismatch. + +### Highest-value next code change +Patch `ZpackVelocityBridge` so startup rehydrate only registers servers where: +- `ready == true` + +Not merely: +- valid name/address/port +- `status=running` + +### Second plugin follow-up +Replace or remove stale default reliance on: +- `zpack-api.internal.zlh` + +Use current configured API address / env-configured endpoint instead. + +--- + +## Current repo / session state at end of this chat + +### Completed +- multi-repo review completed +- trust order established +- `INFRASTRUCTURE.md` restored and corrected +- plugin repo reviewed +- plugin repo cleaned of generated junk after recreate/re-push + +### Still open +- patch plugin startup rehydrate to honor `ready` +- confirm whether plugin webhook endpoints are actively used +- optionally flatten `ZpackVelocityBridge` repo so project files live at repo root +- optionally reduce Portal dependency on `legacy.ts` +- validate remaining infra rows for any post-Apr-2 changes + +--- + +## Recommended next move for future chat + +### First recommended task +Patch `ZpackVelocityBridge`: +1. inspect startup rehydrate logic in `ZpackVelocityBridge.java` +2. require `ready == true` before `registerIfAbsent(...)` +3. review stale default API endpoint behavior (`internal.zlh` default) +4. decide whether webhook mode, polling, or startup-only rehydrate is the intended long-term model + +### Secondary follow-up +After patching plugin: +- retest Fabric readiness / Velocity exposure sequence +- verify Fabric backend is not routable until actually accepting connections + +--- + +## Notes for future GPT session + +Do not restart broad repo discovery from scratch. + +Resume from these assumptions unless newer code disproves them: +- architecture understanding is already established +- infra doc recovery is complete +- plugin is the registration actor inside Velocity +- plugin readiness handling is the most likely near-term bug