fix(di): Wheels.DI.CircularDependency on very first request to fresh app #2331

Summary

The very first HTTP request to a freshly-created Wheels app renders a 1MB error page with Wheels.DI.CircularDependency instead of the welcome page. Issuing wheels reload and refreshing makes the error disappear and the welcome page loads normally; the error never reappears.

Repro

$ wheels new blog --no-open-browser && cd blog && wheels start
$ curl -s -o /tmp/body.html -w "%{http_code}\n" http://localhost:8080/
200
$ grep -m1 'DI.CircularDependency\|Resolution chain' /tmp/body.html
Wheels.DI.CircularDependency
Circular dependency detected while resolving 'app.controllers.Main'.
Resolution chain: app.controllers.Main -> app.controllers.Main

Stack trace originates in vendor/wheels/Global.cfc:769 and vendor/wheels/Controller.cfc:24.

Expected

The first request to a fresh app renders the welcome page directly — no wheels reload required.

Likely cause

Something in the dispatch path appears to register app.controllers.Main as "in resolution" before the cache is consulted, producing a self-edge in the resolution chain on the very first dispatch. After wheels reload clears the cache, the next request resolves cleanly and the bad state never recurs.

Worth checking:

• vendor/wheels/Global.cfc around line 769 — confirm the resolution-stack push happens AFTER the cache-hit check.
• vendor/wheels/Controller.cfc:24 — the constructor/dispatch path that triggered the trace on the first request.
• Whether the DI container's "in-progress" set is being seeded with the controller name before the actual resolution begins.

Severity

Blocker. The very first request to every freshly-created app shows what looks like a broken install, with no hint in the error page that "just run wheels reload" is the workaround.

Workaround

wheels reload, then refresh.

Source

Fresh-VM onboarding journal, 2026-04-27, finding #1.