jester/zlh-grind
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
c5f4b9ddb5
zlh-grind/SCRATCH/mcp-dev-mode-chat-handover-apr10-2026.md

7.5 KiB
Raw Blame History

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