Add MCP dev mode chat handover doc for cross-chat continuity
This commit is contained in:
parent
0643179d02
commit
c5f4b9ddb5
228
SCRATCH/mcp-dev-mode-chat-handover-apr10-2026.md
Normal file
228
SCRATCH/mcp-dev-mode-chat-handover-apr10-2026.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user