Hot-reload contract is misdocumented: ?reload=true DOES re-fire onApplicationStart (and re-runs PackageLoader) — CLI messages and tutorial Parts 6/8 claim the opposite

[bpamiri]

What the code actually does

The generated app's reload path (cli/lucli/templates/app/public/Application.cfc, identical in the v4.0.3 tag and the repo demo app) handles an authorized ?reload=true&password=... by calling $handleRestartAppRequest() → applicationStop(). The next request starts a fresh application, so onApplicationStart re-fires in full: app/events/onapplicationstart.cfm, config/services.cfm, and $loadPackages() (vendor/wheels/events/onapplicationstart.cfc:415) all re-run.

Live proof (Lucee 7 docker, develop framework):

1. A counter probe appended to app/events/onapplicationstart.cfm incremented on every ?reload=true&password=... (1 → 2 → 3 across three reloads).
2. A wheels-fakepkg dropped into vendor/ on the running app was discovered and load-attempted by PackageLoader after a plain reload (its failedPackages entry updated across successive reloads as the manifest was edited) — no wheels stop && wheels start involved.

What claims the opposite

Code-emitted messages (need source edits):

• cli/lucli/Module.cfc:846 — wheels reload prints: Note: onApplicationStart does NOT re-fire. For init-code edits, run \wheels stop && wheels start`.` (comment cites fresh-VM finding adding better description for hasManyCheckBox #8, 2026-04-29; live-verified still emitted on released 4.0.3 — p2-2 claim devserver-01)
• cli/lucli/services/packages/PackagesMainCli.cfc:211-217 — comment asserts "PackageLoader runs in onApplicationStart and wheels reload doesn't re-fire that hook"; install output says Run \wheels stop && wheels start` to activate it.`

Docs (guides):

• web/sites/guides/src/content/docs/v4-0-0/start-here/tutorial/06-authentication.mdx:560 — "Plain wheels reload does not re-run onApplicationStart"
• 06-authentication.mdx:747 — "wheels reload does not re-fire onApplicationStart, so it doesn't re-run config/services.cfm"
• 08-bonus-basecoat.mdx:86 — "wheels reload alone won't do — the package loader runs from onApplicationStart, which only fires on a full server boot."
• 08-bonus-basecoat.mdx:297 — "Most common cause: you ran wheels reload instead of wheels stop && wheels start."

Root CLAUDE.md already says the correct thing ("Restart or wheels reload after install").

Likely origin of the false belief

The historical observations (fresh-VM #8, onboarding F14) most plausibly came from reloads that never actually restarted the app:

• A missing/wrong reload password makes the Application.cfc gate silently skip the restart and serve the request normally — looks exactly like "onApplicationStart didn't re-fire". (Related: wheels reload reports "Application reloaded successfully." when the HTTP reload request fails (4xx/5xx) #3059 — wheels reload reports success even when the HTTP request fails.)
• A bare dev-mode ?reload=true without password only soft-reloads app/global/*.cfm (vendor/wheels/events/EventMethods.cfc:189-202).
• Lucee inspectTemplate=once could serve a stale compiled events file when editing init code (the CLI now purges cfclasses first — Module.cfc:835 — which removes even that case for wheels reload).

Suggested fix

1. Decide the supported contract. The code's actual behavior (full restart on authorized reload) is the better one — recommend documenting it rather than changing code behavior.
2. Update/remove the Module.cfc:846 note and the PackagesMainCli.cfc activation line (e.g. Run \wheels reload` (or restart) to activate it.), and fix the four tutorial passages (plus the 06:747` services.cfm variant).
3. Keep a caveat: a reload only restarts the app when the reload password resolves — a failed password is silent (wheels reload reports "Application reloaded successfully." when the HTTP reload request fails (4xx/5xx) #3059 / Reload-password contract drift: empty password leaves ?reload=true open to anonymous restarts, warm-app wrong-password attempts are never logged or rate-limited, and the boot warning misstates behavior #3062 territory), which is worth surfacing separately.

Dedupe: distinct from #3059 (false-success reporting), #3062 (empty-password contract), and #3030 (param stripping, closed); none of PRs #3100–#3108 touches this. Found by guide-behavioral-audit P2 (p2-1-starthere, claims t06-08 + t08-03).

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The CLI emits guidance that directly contradicts the code's actual behavior. An authorized ?reload=true&password=... calls $handleRestartAppRequest() then applicationStop(), so the next request re-fires onApplicationStart in full (including $loadPackages()). Yet cli/lucli/Module.cfc:846 prints "onApplicationStart does NOT re-fire" and cli/lucli/services/packages/PackagesMainCli.cfc:211-217 tells users to run wheels stop && wheels start to activate a package. The report includes live Lucee 7 reproduction (counter probe + fake-package discovery across reloads), so this is observable wrong output, not a design question.

Suspected layer

cli — the incorrect messages are emitted by the Wheels CLI (cli/lucli/). (No .ai/wheels/cli/ doc; ground reasoning in the verified source lines above and root CLAUDE.md, CLI/Package System section, which already states the correct contract: "Restart or wheels reload after install".)

Fix sketch

Correct the two CLI strings — Module.cfc:846 (drop/rewrite the "does NOT re-fire" note) and PackagesMainCli.cfc $doInstall (change the activation line to something like "Run wheels reload (or restart) to activate it.") — and fix the four tutorial passages in web/sites/guides/src/content/docs/v4-0-0/start-here/tutorial/06-authentication.mdx (lines ~560, ~747) and 08-bonus-basecoat.mdx (lines ~86, ~297). The code's actual full-restart-on-authorized-reload behavior is the better contract, so the fix is to document it, not change behavior. Worth preserving as a caveat: a reload only restarts when the password resolves — a missing/wrong password silently serves the request normally (related #3059 / #3062), which is the likely origin of the false belief.

Confidence: medium

Report is clear and live-reproduced, but the fix spans multiple files across the cli + docs layers and requires deciding/affirming the supported reload contract plus how to surface the password-resolution caveat — not a single-file mechanical change.

<!-- wheels-bot:triage:3110 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3126

Spec: cli/lucli/tests/specs/commands/ReloadCommandSpec.cfc + cli/lucli/tests/specs/packages/PackagesMainCliSpec.cfc — failing → passing
Implementation: cli/lucli/Module.cfc (reload() note) + cli/lucli/services/packages/PackagesMainCli.cfc ($doInstall activation line)

The two CLI strings that claimed ?reload=true does NOT re-fire onApplicationStart are corrected to describe the real full-restart behavior, and the reload note now surfaces the password-resolution caveat (a missing/wrong password silently skips the restart — the likely origin of the false belief, related #3059 / #3062). The package-install line now points to wheels reload instead of wheels stop && wheels start.

Note: the CLI test suite (tools/test-cli-local.sh, which boots a server via lucli) could not be executed in the bot sandbox; both assertions are deterministic source-scan / return-string checks verified against the exact source each spec reads. CI runs the suite.

A human review is required before merge. The Reviewer will weigh in shortly. Doc updates (the tutorial passages in 06-authentication.mdx / 08-bonus-basecoat.mdx, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.