fix: promote-flow dev version rebase and e2e entry-setup gate (#2040)

* fix: base reset dev version on the next stable patch

reset_version computed new_base = max(stable_base, dev_base), so after
every normal promote the dev base equaled stable's — and PEP 440 sorts
X.Y.Z.devN BEHIND X.Y.Z, so the dev channel advertised a version reading
older than the stable carrying the same code. AGENTS.md has always
documented the next-stable-patch rule; nothing enforced it, so the drift
was silent (Patch76's review finding on #2037). The base is now
max(next_patch(stable), dev_base) with the counter restarting on a base
jump, and the test suite pins the sorts-ahead-of-stable invariant.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* fix: gate e2e bring-up on all config entries finishing setup

The unloaded-entry diagnostic named the recurring
test_include_options_flag failure: the seeded HACS entry is still
not_loaded when CoreState.RUNNING trips (RUNNING only means setup was
dispatched), so the OptionsFlow probe sees all-empty options while a
sibling test probing the same entry seconds later passes. Add the
follow-up gate the drift warning has been calling justified: a bounded
wait for entries_loaded == entries_total, entered only when the
trip-time snapshot caught a straggler, logging loudly on timeout.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* feat: auto-dispatch the dev reset when a promote PR merges

The promotion flow ended at the draft promote PR; rebasing the dev
version line onto the new stable was an undocumented manual dispatch.
A post-promote workflow now fires Reset Dev from Stable on promote-PR
merge (human-merged, so the event triggers; workflow_dispatch is
GITHUB_TOKEN-permitted), and the promotion doc gains the missing step.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* fix: rebase the dev version line inside the promote PR itself

Replace the just-added post-promote dispatcher: instead of spawning a
reset PR after every promote merge, the promote transform now rewrites
the dev flavor's two version files (rebase_dev_version — next stable
patch + .dev1) in the same PR, the workflow stages them, and the doc's
step 6 describes it. Reset Dev from Stable remains a manual tool for
the stable-hotfix backport case.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* chore(addon-dev): rebase dev version line onto stable 2.1.0 (2.1.1.dev1)

The 2.1.0 promotion (#2037) predates the in-PR rebase this branch adds,
so dev still advertised 2.0.5.dev3 — sorting behind the stable carrying
the same code. One-time application of rebase_dev_version; future
promotions carry this inside the promote PR itself.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

* fix: enter the entries_loaded gate when the trip snapshot is unavailable

A failed trip-time snapshot (snapshot_ok=False) returns an empty
unloaded string, which skipped the follow-up gate while entries could
still be loading — preserving the race behind a transient HTTP/JSON
hiccup. The skip now requires positive all-loaded confirmation; the
gate's loop polls through snapshot failures and stays bounded.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017iTWsCSMPqSHm7Po8yGzfk

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

.github/workflows/webhook-proxy-promote.yml

@@ -59,7 +59,9 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git checkout -b "$BRANCH"
-          git add homeassistant-addon-webhook-proxy/
+          git add homeassistant-addon-webhook-proxy/ \
+            homeassistant-addon-webhook-proxy-dev/config.yaml \
+            homeassistant-addon-webhook-proxy-dev/mcp_proxy_dev/manifest.json
           git commit -m "chore(addon): promote webhook-proxy dev -> stable $NEW_VERSION"
           git push -u origin "$BRANCH"
           cat > "$RUNNER_TEMP/pr-body.md" <<EOF
@@ -68,6 +70,9 @@ jobs:
           It copied the dev add-on onto the stable add-on, reverse-renamed the
           \`mcp_proxy_dev\` identity back to \`mcp_proxy\`, restored the stable
           mutual-exclusion constants, and set the stable version to \`$NEW_VERSION\`.
+          It also rebased the dev flavor's version line onto the new stable
+          (next stable patch + \`.dev1\`), so no follow-up reset PR is needed
+          for the version alone.
 
           The transform syncs code + identity + version + \`DOCS.md\` (component
           token rename plus the flavor-banner swap; canonical banners live in

homeassistant-addon-webhook-proxy-dev/CHANGELOG.md

@@ -9,6 +9,13 @@ history from before the fork.
 -->
 
 
+## v2.1.1.dev1 (2026-07-26)
+
+Version line rebased onto the 2.1.0 stable base (no code changes — dev and
+stable are identical as of the 2.1.0 promotion). Future promotions carry this
+rebase inside the promote PR itself (`rebase_dev_version`).
+
+
 ## v2.0.5.dev3 (2026-07-26)
 
 ### Bug Fixes

homeassistant-addon-webhook-proxy-dev/config.yaml

@@ -1,6 +1,6 @@
 name: "Nabu Casa - Webhook Proxy for HA MCP (Dev)"
 description: "DEV CHANNEL (unstable) — remote access proxy via Nabu Casa or any reverse proxy. Cannot run alongside the stable Webhook Proxy add-on."
-version: "2.0.5.dev3"
+version: "2.1.1.dev1"
 slug: "ha_mcp_webhook_proxy_dev"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 stage: experimental

homeassistant-addon-webhook-proxy-dev/mcp_proxy_dev/manifest.json

@@ -7,5 +7,5 @@
   "dependencies": ["webhook"],
   "documentation": "https://github.com/homeassistant-ai/ha-mcp",
   "iot_class": "local_push",
-  "version": "2.0.5.dev3"
+  "version": "2.1.1.dev1"
 }

homeassistant-addon-webhook-proxy/AGENTS.md

@@ -85,6 +85,12 @@ manual fallback):
 4. Set `boot: auto`, drop `stage: experimental`, remove the `(Dev)` display-name
    suffixes.
 5. Bump stable's own `config.yaml` + `manifest.json` version (its independent line).
+6. Rebase the dev flavor's version line onto the new stable in the SAME promote PR
+   (next stable patch + `.dev1`, per the Versioning rule above — the transform's
+   `rebase_dev_version` does this; only dev `config.yaml` + `manifest.json` change).
+   Right after a promote the trees are code-identical, so no separate reset PR is
+   needed; `Reset Dev from Stable` remains a manual tool for the stable-hotfix
+   backport case.
 
 ## Testing
 `tests/addon/test_webhook_proxy.py` is parametrized over BOTH flavors — an autouse

scripts/webhook_proxy_sync.py

@@ -156,17 +156,24 @@ def promote_version(current_stable: str, bump: str) -> str:
 
 
 def reset_version(current_dev: str, current_stable: str) -> str:
-    """Next dev version, guaranteed to strictly increase.
-
-    ``new_base = max(stable_base, dev_base)`` and the ``devN`` counter always
-    advances by one. Because the base never decreases and the counter always
-    rises, the result strictly increases even when stable's base is *behind*
-    the current dev base (the code goes backward; the version still climbs).
+    """Next dev version, strictly increasing AND sorting ahead of stable.
+
+    ``new_base = max(next_stable_patch, dev_base)``: AGENTS.md's rule is that
+    the dev base is the NEXT stable patch (stable ``2.0.2`` → ``2.0.3.devN``)
+    so dev always sorts ahead of the stable it will promote into — under
+    PEP 440 a ``X.Y.Z.devN`` pre-release sorts BEHIND ``X.Y.Z``, so basing
+    dev on stable's own base advertised the dev channel as older than the
+    stable carrying the same code. A dev base already further ahead (an
+    escalated line in progress) is kept. The ``devN`` counter restarts at 1
+    on a base jump and advances by one otherwise, so the result strictly
+    increases either way.
     """
     dev_base, dev_n = parse_dev_version(current_dev)
     stable_base = parse_stable_version(current_stable)
-    new_base = max(stable_base, dev_base)
-    return "{}.{}.{}.dev{}".format(*new_base, dev_n + 1)
+    next_patch = (stable_base[0], stable_base[1], stable_base[2] + 1)
+    new_base = max(next_patch, dev_base)
+    new_n = dev_n + 1 if new_base == dev_base else 1
+    return "{}.{}.{}.dev{}".format(*new_base, new_n)
 
 
 # ---------------------------------------------------------------------------
@@ -408,6 +415,31 @@ def _ruff_format(paths: list[Path], root: Path) -> None:
     )
 
 
+def rebase_dev_version(new_stable: str, root: Path = REPO_ROOT) -> str:
+    """Rewrite the dev flavor's version files onto ``new_stable``'s line.
+
+    Called by the promote transform so the promote PR itself carries the dev
+    version rebase (next stable patch + ``.dev1`` — see ``reset_version``)
+    instead of a follow-up reset PR existing only for the version line. Only
+    the two version-bearing files are touched; the dev code is left alone
+    (right after a promote it is identical to stable anyway). Reuses the
+    identity writers, which are idempotent on the dev tree's own identity.
+    """
+    dev_dir = root / DEV.addon_dir
+    new_dev = reset_version(_read_config_version(dev_dir / "config.yaml"), new_stable)
+    config_yaml = dev_dir / "config.yaml"
+    config_yaml.write_text(
+        transform_config_yaml(config_yaml.read_text(encoding="utf-8"), DEV, new_dev),
+        encoding="utf-8",
+    )
+    manifest = dev_dir / DEV.component / "manifest.json"
+    manifest.write_text(
+        apply_manifest(manifest.read_text(encoding="utf-8"), DEV, new_dev),
+        encoding="utf-8",
+    )
+    return new_dev
+
+
 def sync(direction: str, bump: str | None = None, root: Path = REPO_ROOT) -> str:
     """Apply the promote/reset transform in place. Returns the new version."""
     if direction == "promote":
@@ -508,6 +540,13 @@ def sync(direction: str, bump: str | None = None, root: Path = REPO_ROOT) -> str
 
     # Re-wrap .py lines whose length crossed 88 cols due to the token swap.
     _ruff_format([start_py, *sorted(dst_comp.rglob("*.py"))], root)
+
+    if direction == "promote":
+        # The promote PR itself carries the dev version-line rebase — see
+        # rebase_dev_version. Stdout stays the stable version (the promote
+        # workflow captures it); the dev version is visible in the diff.
+        rebase_dev_version(version, root)
+
     return version
 
 

tests/src/e2e/conftest.py

@@ -415,7 +415,8 @@ def pytest_terminal_summary(terminalreporter, exitstatus, config):
             f"⚠️ [READINESS_GATE_DRIFT] {len(drift_samples)} core_state sample(s) "
             f"with entries_loaded < entries_total — a slow integration "
             f"finished async_setup_entry after CoreState.RUNNING; "
-            f"follow-up gate justified."
+            f"the entries_loaded follow-up gate absorbed the wait (see its "
+            f"timing line; a timed_out=True line there means it did not)."
             + (f" Not loaded: {'; '.join(culprits)}" if culprits else "")
         )
 
@@ -1236,6 +1237,66 @@ def _snapshot_config_entries(
         return 0, 0, False, ""
 
 
+# Bounded budget for the entries_loaded follow-up gate. HACS (the only entry
+# observed lagging — it fetches remote data during setup) typically finishes
+# seconds after CoreState.RUNNING; 60s is generous without stalling a genuinely
+# broken container for long.
+_ENTRIES_LOADED_TIMEOUT = 60
+
+
+def _wait_for_entries_loaded(
+    base_url: str,
+    headers: dict[str, str],
+    timeout: int = _ENTRIES_LOADED_TIMEOUT,
+) -> None:
+    """Follow-up readiness gate: wait for every config entry to reach ``loaded``.
+
+    ``CoreState.RUNNING`` only means every ``async_setup_entry`` was
+    DISPATCHED; a slow one can still be running. The drift telemetry
+    repeatedly caught the seeded HACS entry ``not_loaded`` at trip time
+    (#2033's arm lanes, #2040's x86 lane), which the OptionsFlow probe tests
+    then observe as all-empty options — the #1245 regression signature —
+    while a sibling test probing the same entry seconds later passes. This
+    gate closes exactly that window.
+
+    Bounded and non-fatal: on timeout the unloaded entries are logged loudly
+    and the session proceeds — a genuinely broken entry should fail its own
+    tests with the timing line as the named cause, not abort the whole run.
+    """
+    start = time.monotonic()
+    while True:
+        loaded, total, ok, unloaded = _snapshot_config_entries(base_url, headers)
+        elapsed = time.monotonic() - start
+        if ok and total > 0 and loaded >= total:
+            _log_readiness_timing(
+                "entries_loaded",
+                elapsed,
+                entries_loaded=loaded,
+                entries_total=total,
+                snapshot_ok=ok,
+            )
+            return
+        if elapsed >= timeout:
+            logger.warning(
+                "entries_loaded gate timed out after %.0fs: %d/%d loaded%s",
+                elapsed,
+                loaded,
+                total,
+                f" (not loaded: {unloaded})" if unloaded else "",
+            )
+            _log_readiness_timing(
+                "entries_loaded",
+                elapsed,
+                entries_loaded=loaded,
+                entries_total=total,
+                snapshot_ok=ok,
+                timed_out=True,
+                **({"unloaded": unloaded} if unloaded else {}),
+            )
+            return
+        time.sleep(1)
+
+
 def _wait_for_core_state_running(
     base_url: str,
     headers: dict[str, str],
@@ -2384,6 +2445,16 @@ def _wait_for_testcontainer_ready(
         **({"unloaded": entries_unloaded} if entries_unloaded else {}),
     )
 
+    # Follow-up gate: RUNNING does not imply every async_setup_entry finished
+    # (see _wait_for_entries_loaded). Skipped only when the trip-time snapshot
+    # POSITIVELY confirmed all-loaded — a failed snapshot (snapshot_ok=False)
+    # says nothing about entry state, so it enters the gate too rather than
+    # preserving the race behind a transient HTTP/JSON hiccup (Codex review
+    # finding on #2040); the gate's own loop keeps polling through snapshot
+    # failures and stays bounded by its timeout.
+    if entries_unloaded or not snapshot_ok:
+        _wait_for_entries_loaded(base_url, headers)
+
     _wait_for_testcontainer_sun(base_url, headers, container, SUN_WAIT)
 
     # Embedded backend: HA core is up, but the in-process MCP server

tests/src/unit/test_webhook_proxy_sync.py

@@ -86,13 +86,21 @@ def test_bump_stable_tuple_math():
 # ---------------------------------------------------------------------------
 # Reset: dev version must ALWAYS strictly increase
 # ---------------------------------------------------------------------------
-def test_reset_bumps_dev_counter_when_bases_equal():
-    assert sync.reset_version("1.2.3.dev1", "1.2.3") == "1.2.3.dev2"
+def test_reset_moves_to_next_stable_patch_with_fresh_counter():
+    # AGENTS.md's rule: dev base = the NEXT stable patch, so the dev channel
+    # sorts AHEAD of the stable it will promote into (PEP 440 puts
+    # 1.2.3.devN BEHIND 1.2.3). Counter restarts on the base jump.
+    assert sync.reset_version("1.2.3.dev1", "1.2.3") == "1.2.4.dev1"
 
 
-def test_reset_takes_stable_base_when_stable_is_ahead():
-    # stable ahead of dev's base -> base climbs, counter still advances
-    assert sync.reset_version("1.0.0.dev3", "1.5.0") == "1.5.0.dev4"
+def test_reset_takes_next_patch_above_stable_when_stable_is_ahead():
+    # stable ahead of dev's base -> base climbs past it, counter restarts
+    assert sync.reset_version("1.0.0.dev3", "1.5.0") == "1.5.1.dev1"
+
+
+def test_reset_advances_counter_when_dev_base_already_next_patch():
+    # dev already sits on the next stable patch -> same base, counter advances
+    assert sync.reset_version("1.2.4.dev2", "1.2.3") == "1.2.4.dev3"
 
 
 def test_reset_still_increases_when_stable_base_is_behind_dev():
@@ -119,6 +127,43 @@ def test_reset_monotonic_across_a_range_of_pairs():
         assert _version_key(new) > _version_key(current_dev), (
             f"reset({current_dev}, {current_stable}) = {new} did not increase"
         )
+        # The doc invariant the old max-base rule silently violated: the new
+        # dev version must sort AHEAD of the stable it will promote into
+        # (_version_key models PEP 440's devN-before-release ordering).
+        assert _version_key(new) > _version_key(current_stable), (
+            f"reset({current_dev}, {current_stable}) = {new} sorts behind stable"
+        )
+
+
+def test_rebase_dev_version_writes_both_files_in_place(tmp_path):
+    """The promote transform's in-PR dev version rebase: only the two
+    version-bearing dev files change, onto the next-stable-patch line."""
+    stable_cfg = (
+        'name: "x"\ndescription: "y"\nversion: "2.1.0"\n'
+        'slug: "s"\nurl: "u"\narch:\n  - amd64\nboot: auto\n'
+    )
+    dev_dir = tmp_path / sync.DEV.addon_dir
+    (dev_dir / sync.DEV.component).mkdir(parents=True)
+    (dev_dir / "config.yaml").write_text(
+        sync.transform_config_yaml(stable_cfg, sync.DEV, "2.0.5.dev3"),
+        encoding="utf-8",
+    )
+    manifest = dev_dir / sync.DEV.component / "manifest.json"
+    manifest.write_text(
+        '{\n  "domain": "mcp_proxy_dev",\n  "name": "n",\n'
+        '  "version": "2.0.5.dev3"\n}\n',
+        encoding="utf-8",
+    )
+
+    new_dev = sync.rebase_dev_version("2.1.0", root=tmp_path)
+
+    assert new_dev == "2.1.1.dev1"
+    cfg_text = (dev_dir / "config.yaml").read_text(encoding="utf-8")
+    assert 'version: "2.1.1.dev1"' in cfg_text
+    # Idempotent identity rewrite: still exactly one stage line, dev-shaped.
+    assert cfg_text.split("\n").count("stage: experimental") == 1
+    assert '"version": "2.1.1.dev1"' in manifest.read_text(encoding="utf-8")
+    assert _version_key(new_dev) > _version_key("2.1.0")
 
 
 # ---------------------------------------------------------------------------