homeassistant-ai
diff --git a/‎src/ha_mcp/__main__.py‎
Lines changed: 36 additions & 33 deletions b/‎src/ha_mcp/__main__.py‎
Lines changed: 36 additions & 33 deletions
diff --git a/‎src/ha_mcp/config.py‎
Lines changed: 9 additions & 8 deletions b/‎src/ha_mcp/config.py‎
Lines changed: 9 additions & 8 deletions
diff --git a/‎src/ha_mcp/settings_ui/AGENTS.md‎
Lines changed: 1 addition & 1 deletion b/‎src/ha_mcp/settings_ui/AGENTS.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎src/ha_mcp/settings_ui/__init__.py‎
Lines changed: 3 additions & 1 deletion b/‎src/ha_mcp/settings_ui/__init__.py‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎src/ha_mcp/settings_ui/_persistence.py‎
Lines changed: 10 additions & 3 deletions b/‎src/ha_mcp/settings_ui/_persistence.py‎
Lines changed: 10 additions & 3 deletions
diff --git a/‎src/ha_mcp/settings_ui/_theme.py‎
Lines changed: 9 additions & 6 deletions b/‎src/ha_mcp/settings_ui/_theme.py‎
Lines changed: 9 additions & 6 deletions
diff --git a/‎src/ha_mcp/settings_ui/locales/en.json‎
Lines changed: 2 additions & 2 deletions b/‎src/ha_mcp/settings_ui/locales/en.json‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎src/ha_mcp/settings_ui/settings.html‎
Lines changed: 12 additions & 10 deletions b/‎src/ha_mcp/settings_ui/settings.html‎
Lines changed: 12 additions & 10 deletions
diff --git a/‎src/ha_mcp/settings_ui/settings.js‎
Lines changed: 5 additions & 3 deletions b/‎src/ha_mcp/settings_ui/settings.js‎
Lines changed: 5 additions & 3 deletions
@@ -901,27 +901,27 @@ def _maybe_spawn_settings_sidecar() -> None:
     is async; this happens before the main stdio loop so there's no
     nested-loop conflict with ``_run_entrypoint``'s own ``asyncio.run``.
 
-    Performance: the dump constructs the full FastMCP server, which is
-    heavy. Skip it (and the server build) when there's nothing to spawn
-    for — sidecar disabled or already alive. Warm restarts that already
-    have a sidecar pay zero cold-start tax from this path.
+    Performance: the dump constructs the full FastMCP server via the
+    cached ``_get_server()`` singleton the stdio session builds anyway,
+    so this only front-loads that cost. The dump runs as maybe_spawn's
+    ``prepare`` hook — winner-only, inside the spawn lock — because the
+    replacement sidecar must read a cache dumped by the SAME parent that
+    spawned it: a spawn-lock loser with a different environment could
+    otherwise overwrite the winner's cache (issue #2131 review), and the
+    sidecar reloads that shared file per request.
     """
     from ha_mcp.settings_ui import (
         _get_tool_metadata,
         dump_tool_metadata_cache,
     )
     from ha_mcp.stdio_settings_sidecar import (
-        _existing_sidecar_alive,
         _is_disabled,
         maybe_spawn,
     )
 
-    # Cheap gates first; skip the heavy metadata dump when the sidecar
-    # would be a no-op anyway. Any condition that makes maybe_spawn()
-    # short-circuit also makes the dump pointless (the running sidecar
-    # already has a cache from a prior parent startup; a disabled
-    # sidecar never reads one).
-    if _is_disabled() or _existing_sidecar_alive():
+    # Disabled is the only dump-skipping gate; maybe_spawn() logs the
+    # skip reason (a disabled sidecar never reads the cache).
+    if _is_disabled():
         try:
             maybe_spawn()
         except Exception as e:
@@ -932,32 +932,35 @@ def _maybe_spawn_settings_sidecar() -> None:
             )
         return
 
-    try:
-        metadata = asyncio.run(_get_tool_metadata(_get_server()))
-        dumped = dump_tool_metadata_cache(metadata)
-        # Log a deliberate one-liner so users debugging an empty
-        # settings page can see whether the parent's dump succeeded
-        # by grepping the stdio process output (which Claude Desktop
-        # surfaces in its MCP server log panel).
-        logger.info(
-            "Tool metadata cache: %d tools dumped, write %s",
-            len(metadata),
-            "succeeded" if dumped else "FAILED",
-        )
-    except Exception as e:
-        # Cache dump is best-effort — the sidecar falls back to an empty
-        # tools list rather than blocking stdio startup. Include the
-        # exception class in the warning so ops can distinguish
+    def _dump_metadata_cache() -> None:
+        # One-off asyncio.run is safe here: this runs before the main
+        # stdio loop, so there's no nested-loop conflict with
+        # _run_entrypoint's own asyncio.run. Best-effort — the sidecar
+        # falls back to an empty tools list rather than blocking stdio
+        # startup. The exception class in the warning distinguishes
         # server-init failures (Pydantic ValidationError) from cache I/O
         # (OSError) from event-loop issues (RuntimeError).
-        logger.warning(
-            "Failed to dump tool metadata cache (%s)",
-            type(e).__name__,
-            exc_info=True,
-        )
+        try:
+            metadata = asyncio.run(_get_tool_metadata(_get_server()))
+            dumped = dump_tool_metadata_cache(metadata)
+            # Deliberate one-liner so users debugging an empty settings
+            # page can see whether the parent's dump succeeded by
+            # grepping the stdio process output (which Claude Desktop
+            # surfaces in its MCP server log panel).
+            logger.info(
+                "Tool metadata cache: %d tools dumped, write %s",
+                len(metadata),
+                "succeeded" if dumped else "FAILED",
+            )
+        except Exception as e:
+            logger.warning(
+                "Failed to dump tool metadata cache (%s)",
+                type(e).__name__,
+                exc_info=True,
+            )
 
     try:
-        maybe_spawn()
+        maybe_spawn(prepare=_dump_metadata_cache)
     except Exception as e:
         # Spawn failures already log inside maybe_spawn(); the bare
         # except here is a defense-in-depth guard for any unexpected
 
@@ -102,11 +102,12 @@ class Settings(BaseSettings):
     # WebSocket configuration (essential for async operations)
     enable_websocket: bool = Field(True, alias="ENABLE_WEBSOCKET")
 
-    # Settings UI sidecar (stdio mode only, #1587). 0 = pick a free
-    # ephemeral port at every spawn (default); 1024-65535 pins the sidecar
-    # to a fixed port so the settings URL/origin stays stable across
-    # restarts (bookmarks, browser localStorage). Read by run_main() in
-    # stdio_settings_sidecar.py.
+    # Settings UI sidecar (stdio mode only, #1587). 0 (default) = pick a
+    # free ephemeral port on the first spawn and reuse it afterwards
+    # (persisted in ui.state, #2131) so the settings URL/origin stays
+    # stable across restarts; 1024-65535 pins a preferred fixed port
+    # instead (best-effort: falls back to an ephemeral one if taken).
+    # Read by run_main() in stdio_settings_sidecar.py.
     sidecar_pin_port: int = Field(0, alias="HA_MCP_SIDECAR_PORT")
 
     # Development/Debug configuration
@@ -859,9 +860,9 @@ class AdvancedField(NamedTuple):
     AdvancedField("environment", "ENVIRONMENT", str, "diagnostics", True),
     AdvancedField("log_level", "LOG_LEVEL", str, "diagnostics", True),
     AdvancedField("debug", "DEBUG", bool, "diagnostics", True),
-    # Settings UI sidecar (stdio-only). Pin the sidecar's port so the
-    # settings URL/origin is stable across restarts; 0 = ephemeral
-    # (default). #1587.
+    # Settings UI sidecar (stdio-only). 0 (default) = first spawn picks a
+    # free port and later spawns reuse it via ui.state (#2131); a value
+    # pins a preferred fixed port instead (best-effort, #1587).
     AdvancedField("sidecar_pin_port", "HA_MCP_SIDECAR_PORT", int, "sidecar", True),
     # NOTE: ``auto_backup_dir`` and ``auto_backup_calendar_lookahead_days``
     # are NOT in this tuple. They are in ``BACKUP_OVERRIDE_FIELDS`` (defined
 
@@ -46,7 +46,7 @@ Any reachable HA instance works for `HOMEASSISTANT_URL` / `HOMEASSISTANT_TOKEN`.
 - **Relative imports are double-dot.** This is a subpackage of `ha_mcp`, so siblings are `from ..config import ...`, `from ..tools.X import ...`, etc. A single dot resolves inside `settings_ui/` and will `ModuleNotFoundError`.
 - **Python ↔ JS sentinel sync.** `__init__.py` substitutes `__HA_MCP_DEFAULT_PINNED__` and `__HA_MCP_MANDATORY__` into `settings.js` at load. The presence of both sentinels is asserted at import — a rename in one place that isn't mirrored in the other fails fast (not silently).
 - **Anti-FOUC parity with the docs site (JS logic only, NOT visual design).** The theme/accessibility resolver core in `settings.js` (PREFS / PRESETS / apply functions / custom-color layering) must stay logically identical to `site/src/layouts/Layout.astro`. Enforced by `tests/src/unit/test_anti_fouc_parity.py`. Mirror any change in both, or that test fails. This is about *how a saved theme preference is applied before paint*, not about what the page looks like — the visual target is HA (see "Design goal").
-- **Theme prefs persist server-side** (`theme_prefs.json`) because the stdio sidecar respawns on a random port (a fresh origin with empty `localStorage`). The page seeds only *missing* `localStorage` keys from the server payload; the browser's own latest choice wins.
+- **Theme prefs persist server-side** (`theme_prefs.json`) because the stdio sidecar's port — the browser origin — can change (stable by default since #2131, but fresh on first spawn, a lost `ui.state`, a pin change, or a taken remembered port), and a new origin starts with empty `localStorage`. The page seeds only *missing* `localStorage` keys from the server payload; the browser's own latest choice wins.
 - **Locale selection order is explicit cookie → Home Assistant `ha_lang` hint → `Accept-Language` → English.** Keep the selector cookie name synchronized with `_i18n.py`, and preserve English fallback for incomplete community translations.
 - **Callouts use the `ha-alert` style.** Notice bars (`.ha-alert`, `.readonly-notice`, `.pin-notice`, `.restart-notice`) replicate HA's `ha-alert`: full type-tint background, rounded, leading mdi icon (`--icon-info` / `--icon-warning` masks), icon in an absolute left gutter so text flows full-width. Use this for new callouts, not a left-border bar.
 
 
@@ -626,7 +626,9 @@ def register_settings_routes(
         ("/api/settings/features", ["GET"], "get_feature_flags"),
         ("/api/settings/features", ["POST"], "save_feature_flags"),
         # Theme / accessibility prefs (#1574 review) — server-side copy so
-        # they survive the stdio sidecar's per-spawn origin change
+        # they survive a stdio sidecar origin change (stable by default
+        # since #2131, but fresh on first spawn / lost ui.state / pin
+        # change / taken remembered port)
         ("/api/settings/theme", ["GET"], "get_theme_prefs"),
         ("/api/settings/theme", ["POST"], "save_theme_prefs"),
         # Advanced settings endpoints
 
@@ -67,7 +67,11 @@ def dump_tool_metadata_cache(metadata: list[dict[str, Any]]) -> bool:
     """
     path = _get_tool_metadata_cache_path()
     try:
-        path.write_text(json.dumps(metadata))
+        # Atomic (tmp-then-rename): since the dump moved ahead of the
+        # sidecar retire it overlaps the OLD still-serving sidecar on
+        # every startup, and a truncate-write would hand a concurrent
+        # /api/tools request an empty tool list from the torn file.
+        _atomic_write_json(path, metadata)
     except OSError:
         logger.warning("Failed to dump tool metadata cache to %s", path, exc_info=True)
         return False
@@ -203,10 +207,13 @@ def effective_tool_config(settings: Settings | None = None) -> dict[str, Any]:
     return {**cfg, "tools": tools}
 
 
-def _atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
+def _atomic_write_json(
+    path: Path, payload: dict[str, Any] | list[dict[str, Any]]
+) -> None:
     """Write ``payload`` to ``path`` atomically.
 
-    Writes to ``<path>.tmp`` first and ``os.replace``s into place so a
+    Writes to a unique same-directory temp file (``mkstemp``, since
+    #1993) first and ``os.replace``s into place so a
     crash or out-of-space mid-write cannot leave a partial/empty file —
     callers that read the file back (``load_tool_config`` /
     ``_load_backup_settings_override``) would otherwise treat a
 
@@ -1,12 +1,15 @@
 """Theme / accessibility preference persistence for the settings UI.
 
 The browser keeps these in localStorage for synchronous pre-paint reads,
-but localStorage is origin-scoped and the stdio settings sidecar binds a
-random free port per spawn — every session is a fresh origin that starts
-empty. The server-side copy here survives that: POSTs land in
-``theme_prefs.json`` next to the other settings files, and the page
-handler seeds them back into the served HTML (``server-prefs`` head
-script) so a fresh origin paints with the user's saved choices.
+but localStorage is origin-scoped and the stdio settings sidecar's port
+can change — historically on every spawn, now (#2131) only on the first
+spawn, a lost ``ui.state``, a pin change, or a remembered port another
+process took — and each port change is a fresh origin that starts
+empty. The
+server-side copy here survives that: POSTs land in ``theme_prefs.json``
+next to the other settings files, and the page handler seeds them back
+into the served HTML (``server-prefs`` head script) so a fresh origin
+paints with the user's saved choices.
 
 Kept as a leaf module (no imports from the settings_ui package) so the
 handler families and ``__init__`` can depend on it without cycles.
 
@@ -63,7 +63,7 @@
     "policies.pending.empty": "No pending approvals.",
     "policies.rules.title": "Gated tools",
     "policies.rules.empty": "No tools currently security-gated. Enable per-tool gating from the <a href=\"#\" data-panel-link=\"tools\">Tools</a> tab.",
-    "accessibility.intro": "These settings apply immediately and are saved in this browser and on the server, so they survive restarts in every mode (including stdio, where the settings page moves to a fresh port each session). The docs site offers the same controls in its navigation bar; it has no server and saves per browser.",
+    "accessibility.intro": "These settings apply immediately and are saved in this browser and on the server, so they survive restarts in every mode (including stdio, where the settings page can occasionally move to a new port). The docs site offers the same controls in its navigation bar; it has no server and saves per browser.",
     "accessibility.storage_blocked": "Your browser is blocking site storage; choices apply for this session only.",
     "accessibility.theme.title": "Theme",
     "accessibility.theme.help": "One-click color schemes. Auto, the default, follows your OS preference and flips live when it changes.",
@@ -420,7 +420,7 @@
     "advanced.extra_yaml_write_keys.label": "Extra YAML write keys",
     "advanced.extra_yaml_write_keys.help": "Comma-separated top-level keys ha_config_set_yaml may write in addition to the built-in ones, for YAML-first integrations on this install (e.g. alert2). Keys that redefine Home Assistant's own trust boundary can never be added and are ignored. Requires custom component 1.2.4 or newer.",
     "advanced.sidecar_pin_port.label": "Settings UI sidecar port",
-    "advanced.sidecar_pin_port.help": "0 chooses a free port each restart; 1024–65535 pins a preferred port. Restart required.",
+    "advanced.sidecar_pin_port.help": "0 picks a free port on first start and keeps it for later restarts; 1024–65535 pins a preferred port (falls back to a free one if taken). Restart required.",
     "advanced.enable_dev_mode.label": "Developer mode",
     "advanced.enable_dev_mode.help": "⚠ Registers hidden tools that can change settings and replace the running server. Development and testing only. Restart required.",
     "addon.backup_hint.name": "Full-HA snapshot suggestion level (LLM-facing)",
 
@@ -15,12 +15,14 @@
      system sans-serif. -->
 <script data-purpose="server-prefs" data-prefs="__HA_MCP_THEME_PREFS__">
   // #1574 review: theme/accessibility prefs also persist server-side
-  // (theme_prefs.json) because stdio respawns its settings sidecar on a
-  // random port — a fresh origin whose localStorage starts empty. The page
-  // handler substitutes the data-prefs attribute at request time; this
-  // seeds only MISSING localStorage keys (the browser's own latest choice
-  // wins) before the anti-FOUC resolver below reads them. The docs site is
-  // a static build and stays localStorage-only.
+  // (theme_prefs.json) because the stdio sidecar's port — stable by
+  // default since #2131, but fresh on first spawn, a lost ui.state, a
+  // pin change, or a taken remembered port — is the browser origin, and
+  // a new origin's localStorage starts empty. The page handler
+  // substitutes the data-prefs attribute at request time; this seeds
+  // only MISSING localStorage keys (the browser's own latest choice
+  // wins) before the anti-FOUC resolver below reads them. The docs site
+  // is a static build and stays localStorage-only.
   (function () {
     var el = document.currentScript;
     var raw = el ? el.getAttribute("data-prefs") : "";
@@ -366,10 +368,10 @@ <h3 style="font-size:1rem;margin-bottom:8px" data-i18n="policies.rules.title">Ga
 <div class="panel" id="panel-accessibility" role="tabpanel" aria-labelledby="tab-accessibility" tabindex="0">
   <p class="tool-desc" style="margin-bottom:16px" data-i18n="accessibility.intro">
     These settings apply immediately and are saved in this browser and on the
-    server, so they survive restarts in every mode (including stdio, where the
-    settings page moves to a fresh port each session). The docs site offers
-    the same controls in its navigation bar; it has no server and saves per
-    browser.
+    server, so they survive restarts in every mode (including stdio, where
+    the settings page can occasionally move to a new port). The docs site
+    offers the same controls in its navigation bar; it has no server and
+    saves per browser.
   </p>
   <p class="a11y-contrast-warning" id="a11y-storage-note" hidden data-i18n="accessibility.storage_blocked">
     Your browser is blocking site storage; choices apply for this session
 
@@ -3534,7 +3534,7 @@ const ADVANCED_FIELD_META = {
   code_mode_max_invocations: { label: "Code-mode max invocations",    help: "API/tool-call cap per sandbox run. Restart required." },
   code_mode_saved_tools_path:{ label: "Saved-tools path",              help: "JSON file where ha_manage_custom_tool persists saved tools across restarts. Restart required." },
   extra_yaml_write_keys:     { label: "Extra YAML write keys",        help: "Comma-separated top-level keys ha_config_set_yaml may write in addition to the built-in ones, for YAML-first integrations on this install (e.g. alert2). Keys that redefine Home Assistant's own trust boundary can never be added and are ignored. Requires custom component 1.2.4 or newer." },
-  sidecar_pin_port:    { label: "Settings UI sidecar port",    help: "0 = a new free port each restart (default); set 1024–65535 to pin a fixed port so the settings URL stays stable across restarts. Falls back to a free port if the pinned one is busy. Restart required." },
+  sidecar_pin_port:    { label: "Settings UI sidecar port",    help: "0 picks a free port on first start and keeps it for later restarts; 1024–65535 pins a preferred port (falls back to a free one if taken). Restart required." },
   enable_dev_mode:     { label: "Developer mode",               help: "⚠ DANGER: registers hidden developer tools (ha_dev_manage_server, ha_dev_manage_settings) that let AI agents change server settings and replace the running server version (e.g. install a PR build). For development and testing only. Restart required." },
 };
 
@@ -4020,8 +4020,10 @@ loadFsCustomPaths();
 
   // #1574 review: localStorage is the synchronous store the anti-FOUC
   // script reads at paint time, but it is origin-scoped and the stdio
-  // sidecar binds a fresh random port (= fresh empty origin) per session.
-  // This hook therefore (a) mirrors every change to the server
+  // sidecar's port (= the origin) can still change: stable by default
+  // since #2131, yet fresh on first spawn, a lost ui.state, a pin
+  // change, or a taken remembered port. This hook therefore (a) mirrors
+  // every change to the server
   // (./api/settings/theme -> theme_prefs.json), which seeds the next
   // fresh origin via the server-prefs head script, and (b) surfaces a
   // blocked localStorage (private mode) once instead of silently losing