Merge pull request #3220 from wheels-dev/release/4.0.4-to-main

Release 4.0.4

Author: bpamiri

.ai/wheels/channels/channels.md

@@ -138,8 +138,12 @@ adapter.publish(channel = "orders", event = "created", data = SerializeJSON(orde
 var events = adapter.poll(channel = "orders", since = DateAdd("n", -5, Now()));
 var events = adapter.poll(channel = "orders", lastEventId = "evt-123");
 
-// Manual cleanup (automatic cleanup runs every 5 minutes)
+// Manual cleanup. A throttled sweep also runs on the publish path: at most
+// once every 5 minutes (every 15s while a backlog drains), bounded to 1000
+// oldest expired rows per pass. Busy multi-server deployments should run a
+// scheduled full sweep instead of relying on it.
 adapter.cleanup(olderThanMinutes = 30);
+adapter.cleanup(olderThanMinutes = 60, maxRows = 10000);  // bounded pass; returns rows deleted
 ```
 
 #### Database Table: `wheels_events`
@@ -158,10 +162,10 @@ Indexes: `(channel, createdAt)`, `(createdAt)`.
 
 ## JavaScript Client
 
-Include `wheels-sse.js` (located at `/wheels/assets/js/wheels-sse.js`) for a zero-dependency EventSource client with auto-reconnect.
+`wheels-sse.js` is a zero-dependency EventSource client with auto-reconnect. It is NOT served at any URL by the framework — copy it from `vendor/wheels/public/assets/js/wheels-sse.js` into your app (e.g. `public/javascripts/wheels-sse.js`) and include it with `javaScriptIncludeTag("wheels-sse")` or a plain script tag.
 
 ```html
-<script src="/wheels/assets/js/wheels-sse.js"></script>
+<script src="/javascripts/wheels-sse.js"></script>
 <script>
 // Basic usage
 const sse = new WheelsSSE('/notifications/stream', {

.ai/wheels/cross-engine-compatibility.md

@@ -170,6 +170,32 @@ createDynamicProxy(consumer, ["java.util.function.Consumer"]);
 
 **Reference example**: [`vendor/wheels/wheelstest/DialogConsumer.cfc`](../../vendor/wheels/wheelstest/DialogConsumer.cfc) shows the CFC-based pattern used by `BrowserClient` to proxy Playwright's `Consumer<Dialog>`. The probe in `$requireDialogSupport` mirrors the real call shape so engine compatibility is verified on the same code path.
 
+### `for` Loops Inside `finally` Blocks Miscompile on Lucee 7
+
+Lucee 7.0.1+100 throws `variable [local] doesn't exist` at runtime when a `for` loop declares or iterates `local`-/`var`-scoped variables inside a `finally` block. Both loop forms are affected — `for (init; cond; step)` and `for (item in collection)`. Isolated with minimal probes: bare assignments and function calls inside `finally` compile and run fine; loops do not. One probe shape even produced a JVM `Expecting a stackmap frame` bytecode-verifier error, pointing at a codegen bug in Lucee's `finally`-block compilation.
+
+```cfm
+// WRONG — crashes at runtime on Lucee 7
+try {
+    doWork();
+} finally {
+    for (local.key in local.savedState) {
+        variables[local.key] = local.savedState[local.key];
+    }
+}
+
+// RIGHT — hoist the loop into a helper; the finally body is just a call
+try {
+    doWork();
+} finally {
+    $restoreState(local.savedState);
+}
+```
+
+**Why**: Lucee 7's bytecode generation for `finally` blocks mishandles the `local` scope frame for loop constructs. Adobe CF and BoxLang are unaffected.
+
+**Reference example**: `$restoreEmailViewVariables()` in [`vendor/wheels/controller/miscellaneous.cfc`](../../vendor/wheels/controller/miscellaneous.cfc) — the `sendEmail` variables-scope restore runs from `finally` via a `public` `$`-prefixed helper (mixin invariant: helpers must be public). Found while addressing review on [#2922](https://github.com/wheels-dev/wheels/pull/2922).
+
 ### `DirectoryCreate()` Second Argument Is Lucee-Only
 
 Lucee accepts `DirectoryCreate(path, createPath, mode)` and recurses parent directories when `createPath=true`. Adobe CF's signature varies by version and at least some Adobe builds reject any second argument with `"The function takes 1 parameter"` (issue #2567).

.ai/wheels/security/https-detection.md

@@ -133,8 +133,8 @@ component extends="Controller" {
 ## Important Notes
 - Returns `false` for HTTP connections (port 80)
 - Returns `true` for HTTPS connections (port 443)
-- Works behind load balancers and reverse proxies
-- Consider proxy headers (X-Forwarded-Proto) in deployment
+- Works behind load balancers and reverse proxies when `set(trustProxyHeaders=true)` is configured
+- `X-Forwarded-Proto` is **not** honored by default; enable with `set(trustProxyHeaders=true)` behind a trusted proxy that overwrites forwarded headers
 - Test both HTTP and HTTPS scenarios during development
 
 ## Common Patterns

.ai/wheels/troubleshooting/common-errors.md

@@ -29,6 +29,20 @@ Wheels failed to initialize. Check the server log for details.
 
 **Note:** Before the #2774 fix, this failure cascaded into a second `[WO] does not exist` exception that hid the real cause. If you see the old cascade on a version that predates this fix (i.e. 4.0.1 or earlier), the underlying cause is always a failed `onApplicationStart` — see above.
 
+### "key [ENGINEADAPTER] doesn't exist" / "Element WHEELS.ENGINEADAPTER is undefined" in dev error page
+**Error (on-page or in server log):**
+```
+key [ENGINEADAPTER] doesn't exist          (Lucee)
+Element WHEELS.ENGINEADAPTER is undefined  (Adobe CF)
+```
+
+**Cause:** An exception during `onApplicationStart` (e.g. `Wheels.Cors.InvalidConfiguration` from an invalid `config/settings.cfm` value) triggered `onError`, which itself crashed because three request-lifecycle helpers — `$getRequestTimeout()`, `$statusCode()`, and `$contentType()` — read `application.wheels.engineAdapter` directly after gating on `$hasEngineAdapter()`. That gate checks both `application.wheels` and the startup-staging struct `application.$wheels`, but the subsequent read assumed the adapter had been promoted to `application.wheels`. When only the `$wheels` branch matched (the failed-startup state), the read threw and replaced the original exception (fixed in [#3108](https://github.com/wheels-dev/wheels/pull/3108)).
+
+**Resolution:**
+The `[ENGINEADAPTER]` crash is a symptom — the real error happened during startup. Check the server log for the original `onApplicationStart` exception; common causes include invalid middleware configuration, a missing CFML mapping, or a syntax error in `config/settings.cfm` or `config/routes.cfm`.
+
+After upgrading past the #3108 fix, `onError` surfaces the original startup exception directly.
+
 ## Common Association Errors
 
 ### "Missing argument name" in hasMany()

.ai/wheels/wheels-bot.md

@@ -1,24 +1,28 @@
 # Wheels Bot
 
-`wheels-bot[bot]` is a custom GitHub App that runs Claude-powered automation on issues and PRs in `wheels-dev/wheels`. Five stages, all opt-out via the `[skip-claude]` label or repo variable `WHEELS_BOT_ENABLED=false`. Slash-command prompts live in `.claude/commands/`; workflows in `.github/workflows/bot-*.yml`. Full user-facing docs: [`docs/contributing/wheels-bot.md`](../../docs/contributing/wheels-bot.md).
+`wheels-bot[bot]` is a custom GitHub App that runs Claude-powered automation on issues and PRs in `wheels-dev/wheels`. All stages are opt-out via the `[skip-claude]` label or repo variable `WHEELS_BOT_ENABLED=false`. Slash-command prompts live in `.claude/commands/`; workflows in `.github/workflows/bot-*.yml`. Full user-facing docs: [`docs/contributing/wheels-bot.md`](../../docs/contributing/wheels-bot.md).
 
 ## Stages
 
 | Stage | Trigger | Model | Output |
 |---|---|---|---|
 | Triage | issue opened/reopened | Opus | Comment classifying as `bug` / `framework-design` / `other` (+ confidence on `bug` path). Reads code with the allowlisted tools to resolve uncertainty before rating. |
 | Research | bot triage emits `framework-design` marker | Opus | Comment comparing Rails / Laravel / Django / Phoenix / Spring Boot / +1 and recommending a Wheels-idiomatic path (+ confidence). |
-| Propose Fix | bot triage emits `triage-confidence:high\|medium` OR research emits `research-confidence:high\|medium` (or `workflow_dispatch`) | Opus | TDD-mandatory draft PR on branch `fix/bot-<issue>-<slug>`. Spec-then-implementation, both required by `bot-tdd-gate.yml`. |
-| Reviewer A | PR opened / synchronized / ready_for_review | Sonnet | Single PR review with line comments, verdict, and `wheels-bot:review-a:<pr>:<sha>` marker. |
-| Reviewer B | Reviewer A submits a review | Sonnet | PR comment critiquing A for sycophancy, false positives, and missed issues. Loop cap = 3 rounds. |
+| Propose Fix | bot triage emits `triage-confidence:high\|medium` OR research emits `research-confidence:high\|medium` (or `workflow_dispatch`). A pre-gate skips the run when a `peter/issue-<N>-*` branch or an open non-bot PR already targets the issue (campaign guard). | Opus | TDD-mandatory draft PR on branch `fix/bot-<issue>-<slug>`. Spec-then-implementation, both required by `bot-tdd-gate.yml`. |
+| Reviewer | PR opened / synchronized / ready_for_review (`bot-review.yml`; fork PRs via maintainer-labeled `bot-review-fork.yml`) | Opus | Single PR review with line comments, verdict, and `wheels-bot:review-a:<pr>:<sha>` marker (legacy marker name retained). The prompt includes a self-adversarial pass — refute each finding against the actual code before posting — replacing the retired Reviewer B critique loop. Supersession (#3048): when a still-active wheels-bot `CHANGES_REQUESTED` exists and the re-review has zero blocking findings, the verdict is submitted as APPROVE (nits in the body) so the stale block clears without manual dismissal; fork PRs stay comment-only — the bot never approves a fork PR. |
+| Address Review | **opt-in**: maintainer applies the `bot-address-review` label or dispatches `bot-address-review.yml` | Opus | Applies the most recent wheels-bot review's findings on the current head SHA, pushes to the PR branch, comments with `wheels-bot:address-review:<pr>:<sha>:<round>`. |
+
+**Model policy:** judging gate = opus, coding stages = opus, janitorial = sonnet (Fable 5 was the judging gate until its 2026-06 deactivation; the reviewer moved to Opus 4.8) (auto-close, write-docs, update-docs stay on Sonnet).
+
+**Retired (2026-06-11):** the Reviewer A / Reviewer B convergence loop (`bot-review-b.yml`, `/review-the-review`, `/respond-to-critique`) and the `converged-*` auto-fire chain into address-review. The loop was expensive and flaky, B's marginal catch rate no longer justified a second model pass, and the auto-fire push chain landed a broken spec on a PR (#3005). `bot-advisor.yml` (the loop's deadlock-breaker) is retained but inert — its trigger marker is no longer produced.
 
 ## Marker conventions (HTML comments, used for idempotency)
 
 - `<!-- wheels-bot:triage:<issue> -->` + `<!-- wheels-bot:triage-class:<bug|framework-design|other> -->` (+ optional `<!-- wheels-bot:triage-confidence:high|medium -->` — either fires propose-fix; low omitted)
 - `<!-- wheels-bot:research:<issue> -->` (+ optional `<!-- wheels-bot:research-confidence:high|medium -->` — either fires propose-fix; low omitted)
 - `<!-- wheels-bot:fix:<issue> -->` / `<!-- wheels-bot:fix-held:<issue> -->`
-- `<!-- wheels-bot:review-a:<pr>:<sha> -->`
-- `<!-- wheels-bot:review-b:<pr>:<sha>:<round> -->`
+- `<!-- wheels-bot:review-a:<pr>:<sha> -->` — the Reviewer's review marker (legacy name kept for continuity across the single-reviewer consolidation)
+- `<!-- wheels-bot:address-review:<pr>:<sha>:<round> -->` / `<!-- wheels-bot:address-held:<pr>:<sha> -->`
 - `<!-- wheels-bot:auto-close:<issue> -->`
 
 ## Allow-listed scopes per stage
@@ -31,7 +35,7 @@ Flip the repo variable `WHEELS_BOT_ENABLED` to `false` to halt every bot workflo
 
 ## Auto-fire safety net
 
-The bot is permitted to chain stages (triage → research → propose-fix), and handoff fires on `*-confidence:high` OR `*-confidence:medium`. Low stays manual. Sensitive areas (security, middleware, migrations, deploy, DI, cross-engine) are caught by the propose-fix prompt's own step-4 safety net, which posts a `fix-held` marker instead of opening a PR. Reviewer A and B then critique whatever propose-fix produces, escalating to the Senior Advisor on deadlock. All bot PRs land as `--draft` and require a human approving review on `develop`.
+The bot is permitted to chain stages (triage → research → propose-fix), and handoff fires on `*-confidence:high` OR `*-confidence:medium`. Low stays manual. Sensitive areas (security, middleware, migrations, deploy, DI, cross-engine) are caught by the propose-fix prompt's own step-4 safety net, which posts a `fix-held` marker instead of opening a PR. The Reviewer then reviews whatever propose-fix produces. Address-review never auto-fires — a human opts the PR in via the `bot-address-review` label. All bot PRs land as `--draft` and require a human approving review on `develop`.
 
 ## PR-prep automation (release unblocking)
 

.claude/commands/_shared-rails.md

@@ -53,9 +53,12 @@ they are honored. Violating them is a bug — fix the prompt, not the rails.
   matching the configured git author identity. Use `git commit -s` (the
   caller workflow's `git config` for `user.name` / `user.email` makes this
   the right value automatically) or append the trailer manually before the
-  `Co-authored-by:` lines. The [DCO GitHub App](https://github.com/apps/dco)
-  is a required status check on every PR and will block merges if any
-  commit is missing the trailer. See
+  `Co-authored-by:` lines. Note: sign-off is project policy verified during
+  code review — there is NO DCO status check on this repo, and no check will
+  fail for a missing trailer. When reviewing someone else's PR, treat a
+  missing sign-off as a fix-before-merge review request (suggest
+  `git rebase --signoff develop`), never as a failing or required CI check.
+  See
   [`CONTRIBUTING.md` § DCO](../../CONTRIBUTING.md#developer-certificate-of-origin-dco)
   for the contributor-facing explanation.
 - **Branch naming** for bot-authored work: `fix/bot-<issue>-<slug>` or
@@ -75,8 +78,7 @@ existing comments for the marker that matches your stage and key. If found,
 ## Output format
 
 - Start every comment / review with a clear H2 header naming the stage:
-  `## Wheels Bot — Triage`, `## Wheels Bot — Reviewer A`,
-  `## Wheels Bot — Reviewer B (round N)`,
+  `## Wheels Bot — Triage`, `## Wheels Bot — Reviewer`,
   `## Wheels Bot — Cross-Framework Research`.
 - End with the appropriate marker on its own line.
 - No emoji unless the team's existing style uses them (CFML repo norms — minimal).