ha-mcp-dev 7.12.3.dev1859__tar.gz → 7.12.3.dev1863__tar.gz

{ha_mcp_dev-7.12.3.dev1859/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.12.3.dev1863}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.12.3.dev1859
+Version: 7.12.3.dev1863
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.12.3.dev1859 → ha_mcp_dev-7.12.3.dev1863}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.12.3.dev1859"
+version = "7.12.3.dev1863"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.12.3.dev1859 → ha_mcp_dev-7.12.3.dev1863}/src/ha_mcp/config.py

@@ -83,6 +83,22 @@ class Settings(BaseSettings):
         20.0, alias="HAMCP_SCENE_CONFIG_TIME_BUDGET"
     )
 
+    # Per-request timeout and concurrency of the smart-search per-id
+    # config-fetch fallback (Attempt C). On HA servers that serve
+    # /config/<domain>/config/<id> serially, a full batch of concurrent
+    # requests queues behind one another and the tail of each batch can
+    # exceed the per-request timeout even though every request would
+    # succeed — lowering the batch size (toward 1) and/or raising the
+    # timeout lets such instances scan exhaustively (issue #1784). Same
+    # consumption model as the budgets above: import-time constants in
+    # tools/smart_search/_config.py, restart required.
+    individual_config_timeout: float = Field(
+        5.0, alias="HAMCP_INDIVIDUAL_CONFIG_TIMEOUT"
+    )
+    individual_fetch_batch_size: int = Field(
+        10, alias="HAMCP_INDIVIDUAL_FETCH_BATCH_SIZE"
+    )
+
     # Backup tool configuration
     backup_hint: str = Field("normal", alias="BACKUP_HINT")
 
@@ -350,21 +366,26 @@ class Settings(BaseSettings):
         "automation_config_time_budget",
         "script_config_time_budget",
         "scene_config_time_budget",
+        "individual_config_timeout",
+        "individual_fetch_batch_size",
         mode="before",
     )
     @classmethod
     def _lenient_time_budget(cls, v: object, info: ValidationInfo) -> object:
-        """Coerce the three smart-search time budgets, falling back to the
-        field default (with a warning) instead of crashing startup.
+        """Coerce the smart-search Attempt-C knobs (the three time budgets,
+        the per-request timeout, and the fetch batch size), falling back to
+        the field default (with a warning) instead of crashing startup.
 
         Preserves the parse-tolerance of the removed ``_env_float`` helper
         (empty / unparseable -> default) and additionally enforces the same
         ``_ADVANCED_SETTINGS_BOUNDS`` range as the override-file / UI-POST
         path, so the env-var path can't smuggle in an out-of-range or
-        non-finite budget. A ``<= 0`` budget would silently disable the
-        per-id config-fetch scan, and ``inf`` / ``nan`` would uncap it; the
-        ``lo <= val <= hi`` test rejects all three (NaN comparisons are
-        False), keeping the env and override-file paths consistent."""
+        non-finite value. A ``<= 0`` budget or timeout would silently
+        disable the per-id config-fetch scan, and ``inf`` / ``nan`` would
+        uncap it; the ``lo <= val <= hi`` test rejects all three (NaN
+        comparisons are False), keeping the env and override-file paths
+        consistent. Int fields (batch size) additionally reject fractional
+        values rather than truncating them."""
         field_name = info.field_name
         if field_name is None:  # always set for field_validator; defensive
             return v
@@ -389,6 +410,17 @@ class Settings(BaseSettings):
                 default,
             )
             return default
+        if isinstance(default, int) and not isinstance(default, bool):
+            if val != int(val):
+                logger.warning(
+                    "Invalid value for %s=%r (must be a whole number); "
+                    "using default %s",
+                    field_name,
+                    v,
+                    default,
+                )
+                return default
+            return int(val)
         return val
 
     @property
@@ -759,6 +791,22 @@ ADVANCED_SETTINGS_FIELDS: tuple[AdvancedField, ...] = (
         "search",
         True,
     ),
+    # Attempt-C per-request timeout + batch size (#1784). Restart-required
+    # (same import-time consumption as the budgets above).
+    AdvancedField(
+        "individual_config_timeout",
+        "HAMCP_INDIVIDUAL_CONFIG_TIMEOUT",
+        float,
+        "search",
+        True,
+    ),
+    AdvancedField(
+        "individual_fetch_batch_size",
+        "HAMCP_INDIVIDUAL_FETCH_BATCH_SIZE",
+        int,
+        "search",
+        True,
+    ),
     # Operations.
     AdvancedField("backup_hint", "BACKUP_HINT", str, "operations", True),
     AdvancedField("enable_websocket", "ENABLE_WEBSOCKET", bool, "operations", True),
@@ -846,6 +894,8 @@ _ADVANCED_SETTINGS_BOUNDS: dict[str, tuple[float, float]] = {
     "automation_config_time_budget": (1.0, 600.0),
     "script_config_time_budget": (1.0, 600.0),
     "scene_config_time_budget": (1.0, 600.0),
+    "individual_config_timeout": (1.0, 600.0),
+    "individual_fetch_batch_size": (1, 100),
     "code_mode_max_duration": (1.0, 300.0),
     "code_mode_max_memory": (1_048_576, 268_435_456),
     "code_mode_max_recursion": (1, 10_000),

{ha_mcp_dev-7.12.3.dev1859 → ha_mcp_dev-7.12.3.dev1863}/src/ha_mcp/settings_ui/settings.js

@@ -1553,7 +1553,7 @@ const FEATURE_META = {
   },
   enable_code_mode: {
     label: "Enable code-mode sandbox (beta)",
-    help: "Beta feature, disabled by default. Enables ha_manage_custom_tool, a sandboxed Python interpreter (pydantic-monty) that lets AI assistants write/run/save/delete custom tools when no built-in tool covers the request. Sandbox cannot touch the filesystem or arbitrary network, but CAN call any registered MCP tool, hit the HA REST API, or send HA WebSocket commands, effectively 'do whatever existing tools allow you to do, in any combination'. See docs/beta.md for known limitations. Requires restart to take effect.",
+    help: "Beta feature, disabled by default. Enables ha_manage_custom_tool, a sandboxed Python interpreter (pydantic-monty) that lets AI assistants write/run/save/delete custom tools when no built-in tool covers the request. Sandbox cannot touch the filesystem or arbitrary network, but CAN call any registered MCP tool, hit the HA REST API, or send HA WebSocket commands, effectively 'do whatever existing tools allow you to do, in any combination'. Saved tools persist and are visible to any client that can connect to ha-mcp. See docs/beta.md for known limitations. Requires restart to take effect.",
   },
   enable_lite_docstrings: {
     label: "Enable lite tool docstrings (beta)",
@@ -2946,6 +2946,8 @@ const ADVANCED_FIELD_META = {
   automation_config_time_budget: { label: "Automation config time budget (s)", help: "Max seconds ha_search/ha_deep_search spends fetching automation configs before returning a partial result. Raise on instances with many automations. Range 1–600. Restart required." },
   script_config_time_budget:     { label: "Script config time budget (s)",     help: "Max seconds ha_search/ha_deep_search spends fetching script configs before returning a partial result. Range 1–600. Restart required." },
   scene_config_time_budget:      { label: "Scene config time budget (s)",      help: "Max seconds ha_search/ha_deep_search spends fetching scene configs before returning a partial result. Range 1–600. Restart required." },
+  individual_config_timeout:     { label: "Per-request config fetch timeout (s)", help: "Timeout for each individual automation/script/scene config fetch during deep search. On HA servers that serve config reads serially, raise this and/or lower the batch size so queued requests don't time out. Values above the HA request timeout (HA_TIMEOUT, default 30) have no extra effect — the HTTP client gives up first. Range 1–600. Restart required." },
+  individual_fetch_batch_size:   { label: "Config fetch batch size",          help: "How many per-id config fetches deep search issues concurrently. Lower toward 1 on HA servers that serve config reads serially (symptom: 'timed out' partial-result warnings). Range 1–100. Restart required." },
   backup_hint:         { label: "Backup-hint level",           help: "Tunes how strongly the LLM is prompted to take a full-HA snapshot before risky writes." },
   dashboard_screenshot_engine_url: { label: "Dashboard screenshot engine URL", help: "Base URL of the screenshot engine (e.g. http://puppet:10000). Leave blank to auto-discover the Puppet App (add-on) via the Supervisor (HA OS / Supervised). Only used when the Dashboard Screenshot beta feature is enabled. Takes effect without a restart." },
   enable_websocket:    { label: "Enable WebSocket",            help: "WebSocket-based state monitoring. Disabling falls back to polling; many tools degrade. Restart required." },
@@ -2985,6 +2987,9 @@ const ADVANCED_RESTART_REQUIRED = new Set([
   // it is resolved live per capture, so it takes effect immediately.
   "automation_config_time_budget", "script_config_time_budget",
   "scene_config_time_budget",
+  // The Attempt-C per-request timeout and batch size (#1784) share the
+  // budgets' import-time consumption, so they need a restart too.
+  "individual_config_timeout", "individual_fetch_batch_size",
   "code_mode_max_duration", "code_mode_max_memory",
   "code_mode_max_recursion", "code_mode_max_invocations",
   "code_mode_saved_tools_path",

{ha_mcp_dev-7.12.3.dev1859 → ha_mcp_dev-7.12.3.dev1863}/src/ha_mcp/tools/smart_search/_config.py

@@ -13,23 +13,29 @@ DEFAULT_CONCURRENCY_LIMIT = 20
 # Bulk fetch timeouts (in seconds)
 BULK_REST_TIMEOUT = 5.0  # Timeout for bulk REST endpoint calls
 BULK_WEBSOCKET_TIMEOUT = 3.0  # Timeout for bulk WebSocket calls
-INDIVIDUAL_CONFIG_TIMEOUT = 5.0  # Timeout for individual config fetches
 
 
-# Time budgets for fallback individual fetching (in seconds). Sourced from
-# the resolved Settings (issue #1538) so the env var, the web Settings UI
+# Attempt-C (per-id fallback) tuning knobs. Sourced from the resolved
+# Settings (issues #1538 / #1784) so the env var, the web Settings UI
 # override file, and the field defaults all flow through one precedence path
 # — and so add-on users (who cannot set raw env vars) can tune them from the
 # Advanced panel. Read once at import as module-level constants; a change
 # takes effect on the next MCP-host restart (advanced settings already
 # carry a restart-required notice in the UI).
 _settings = get_global_settings()
+
+# Time budgets for fallback individual fetching (in seconds).
 AUTOMATION_CONFIG_TIME_BUDGET = _settings.automation_config_time_budget
 SCRIPT_CONFIG_TIME_BUDGET = _settings.script_config_time_budget
 SCENE_CONFIG_TIME_BUDGET = _settings.scene_config_time_budget
 
-# Batch size for parallel individual config fetches (Attempt C fallback)
-INDIVIDUAL_FETCH_BATCH_SIZE = 10
+# Per-request timeout (seconds) and batch size for the parallel individual
+# config fetches. On HA servers that serve the per-id config endpoint
+# serially, a batch's tail requests queue behind its head and can exceed
+# the per-request timeout despite being perfectly healthy — tune batch
+# size toward 1 and/or raise the timeout on such instances (issue #1784).
+INDIVIDUAL_CONFIG_TIMEOUT = _settings.individual_config_timeout
+INDIVIDUAL_FETCH_BATCH_SIZE = _settings.individual_fetch_batch_size
 
 
 def _simplify_states_summary(

{ha_mcp_dev-7.12.3.dev1859 → ha_mcp_dev-7.12.3.dev1863}/src/ha_mcp/tools/smart_search/_deep.py

@@ -18,8 +18,10 @@ from ._config import (
     BULK_REST_TIMEOUT,
     DEFAULT_CONCURRENCY_LIMIT,
     INDIVIDUAL_CONFIG_TIMEOUT,
+    INDIVIDUAL_FETCH_BATCH_SIZE,
     SCRIPT_CONFIG_TIME_BUDGET,
 )
+from ._fetch import is_timeout_error
 from ._scenes import SceneSearchMixin
 
 logger = logging.getLogger(__name__)
@@ -111,6 +113,7 @@ class DeepSearchMixin(SceneSearchMixin):
             scene_stats: dict[str, Any] = {
                 "failed": 0,
                 "skipped": 0,
+                "timeout": 0,
                 "integration_skipped": 0,
                 "registry_failed": False,
             }
@@ -120,13 +123,16 @@ class DeepSearchMixin(SceneSearchMixin):
             # surface as ``partial: True`` so callers can detect "incomplete
             # zero" / "incomplete partial" results vs a true complete answer.
             # ``_skipped`` = budget exhausted before fetch; ``_failed`` =
-            # fetch attempted but raised (caught at ``debug``-level).
+            # fetch attempted but raised (caught at ``debug``-level);
+            # ``_timeout`` = fetch exceeded the per-request timeout (#1784).
             automation_skipped = 0
             automation_failed = 0
             automation_yaml_skipped = 0
+            automation_timeout = 0
             script_skipped = 0
             script_failed = 0
             script_yaml_skipped = 0
+            script_timeout = 0
             helper_failed = 0
             dashboard_failed = 0
 
@@ -136,6 +142,7 @@ class DeepSearchMixin(SceneSearchMixin):
                     automation_skipped,
                     automation_failed,
                     automation_yaml_skipped,
+                    automation_timeout,
                 ) = await self._deep_search_automations(
                     all_entities,
                     automation_unique_id_map,
@@ -157,6 +164,7 @@ class DeepSearchMixin(SceneSearchMixin):
                     script_skipped,
                     script_failed,
                     script_yaml_skipped,
+                    script_timeout,
                 ) = await self._deep_search_scripts(
                     all_entities,
                     query_lower,
@@ -178,6 +186,7 @@ class DeepSearchMixin(SceneSearchMixin):
                     scene_stats["skipped"],
                     scene_stats["integration_skipped"],
                     scene_stats["registry_failed"],
+                    scene_stats["timeout"],
                 ) = await self._deep_search_scenes(
                     all_entities,
                     query_lower,
@@ -233,9 +242,11 @@ class DeepSearchMixin(SceneSearchMixin):
                 automation_skipped=automation_skipped,
                 automation_failed=automation_failed,
                 automation_yaml_skipped=automation_yaml_skipped,
+                automation_timeout=automation_timeout,
                 script_skipped=script_skipped,
                 script_failed=script_failed,
                 script_yaml_skipped=script_yaml_skipped,
+                script_timeout=script_timeout,
                 helper_failed=helper_failed,
                 dashboard_failed=dashboard_failed,
             )
@@ -282,22 +293,26 @@ class DeepSearchMixin(SceneSearchMixin):
         exact_match: bool,
         *,
         config_time_budget: float | None = None,
-    ) -> tuple[list[dict[str, Any]], int, int, int]:
+    ) -> tuple[list[dict[str, Any]], int, int, int, int]:
         """Deep-search automations: 3-tier config fetch (REST bulk -> WS bulk -> individual).
 
-        Returns ``(matches, skipped_count, failed_count, yaml_skipped_count)``.
-        ``skipped_count`` is non-zero only when bulk fetch fell back to the
-        per-id Attempt-C path AND its wall-clock budget exhausted before all
-        configs were fetched; ``failed_count`` is non-zero when individual
-        config fetches raised a non-404 exception (caught at ``debug``-level);
-        ``yaml_skipped_count`` is non-zero when individual config fetches
-        returned 404, which is the documented HA behaviour for YAML-defined
-        automations (the ``/config/automation/config/<id>`` REST endpoint
-        only exposes UI-storage automations). All three surface as
-        ``partial: True`` in the response so callers can distinguish a
-        complete zero-result from an incomplete one — skipped/failed ids
-        carry their score-without-config through the merge and fall below
-        the match threshold silently otherwise.
+        Returns ``(matches, skipped_count, failed_count, yaml_skipped_count,
+        timeout_count)``. ``skipped_count`` is non-zero only when bulk fetch
+        fell back to the per-id Attempt-C path AND its wall-clock budget
+        exhausted before all configs were fetched; ``failed_count`` is
+        non-zero when individual config fetches raised a non-404, non-timeout
+        exception (caught at ``debug``-level); ``yaml_skipped_count`` is
+        non-zero when individual config fetches returned 404, which is the
+        documented HA behaviour for YAML-defined automations (the
+        ``/config/automation/config/<id>`` REST endpoint only exposes
+        UI-storage automations); ``timeout_count`` is non-zero when fetches
+        exceeded the per-request ``INDIVIDUAL_CONFIG_TIMEOUT`` — usually a
+        sign the HA server serves config reads serially and the concurrent
+        batch queued past the timeout, not that anything is broken (#1784).
+        All four surface as ``partial: True`` in the response so callers can
+        distinguish a complete zero-result from an incomplete one —
+        skipped/failed ids carry their score-without-config through the
+        merge and fall below the match threshold silently otherwise.
         """
         automation_entities = [
             e for e in all_entities if e.get("entity_id", "").startswith("automation.")
@@ -334,6 +349,9 @@ class DeepSearchMixin(SceneSearchMixin):
 
         # Attempt C: parallel individual REST calls with time budget (LAST RESORT)
         skipped_count = 0
+        failed_count = 0
+        yaml_skipped_count = 0
+        timeout_count = 0
         if not bulk_fetched:
             uids_to_fetch = [
                 uid for _, _, uid, _ in scored if uid and uid not in configs
@@ -364,7 +382,27 @@ class DeepSearchMixin(SceneSearchMixin):
                         f"Automation individual config fetch ({uid}) failed: {e}"
                     )
                     return (uid, None, "failed")
+                except TimeoutError:
+                    # asyncio.wait_for hit INDIVIDUAL_CONFIG_TIMEOUT. Classify
+                    # distinctly from "failed": on servers that serialize
+                    # config reads, a batch's tail requests queue past the
+                    # timeout while still perfectly healthy (#1784).
+                    logger.debug(
+                        f"Automation individual config fetch ({uid}) timed "
+                        f"out after {INDIVIDUAL_CONFIG_TIMEOUT}s."
+                    )
+                    return (uid, None, "timeout")
                 except Exception as e:
+                    if is_timeout_error(e):
+                        # The REST client's own httpx timeout (HA_TIMEOUT)
+                        # fired first and arrived wrapped in a
+                        # HomeAssistantConnectionError — still a timeout,
+                        # not a failure. See is_timeout_error.
+                        logger.debug(
+                            f"Automation individual config fetch ({uid}) "
+                            f"timed out (client-side HTTP timeout): {e}"
+                        )
+                        return (uid, None, "timeout")
                     logger.debug(
                         f"Automation individual config fetch ({uid}) failed: {e}"
                     )
@@ -375,6 +413,7 @@ class DeepSearchMixin(SceneSearchMixin):
                 failed_count,
                 skipped_count,
                 yaml_skipped_count,
+                timeout_count,
             ) = await self._individual_fetch_budgeted(
                 uids_to_fetch,
                 _fetch_automation_config,
@@ -385,9 +424,6 @@ class DeepSearchMixin(SceneSearchMixin):
                 "automations",
             )
             configs.update(fetched_configs)
-        else:
-            failed_count = 0
-            yaml_skipped_count = 0
 
         # Phase 3: Score with whatever configs we have
         matches = [
@@ -403,7 +439,7 @@ class DeepSearchMixin(SceneSearchMixin):
                 scored, configs, query_lower, exact_match
             )
         ]
-        return matches, skipped_count, failed_count, yaml_skipped_count
+        return matches, skipped_count, failed_count, yaml_skipped_count, timeout_count
 
     async def _deep_search_scripts(
         self,
@@ -412,13 +448,14 @@ class DeepSearchMixin(SceneSearchMixin):
         exact_match: bool,
         *,
         config_time_budget: float | None = None,
-    ) -> tuple[list[dict[str, Any]], int, int, int]:
+    ) -> tuple[list[dict[str, Any]], int, int, int, int]:
         """Deep-search scripts: same 3-tier strategy as automations.
 
-        Returns ``(matches, skipped_count, failed_count, yaml_skipped_count)``;
-        semantics identical to ``_deep_search_automations`` — the 404 path
-        catches YAML-defined scripts (which ``client.get_script_config``
-        re-raises as ``HomeAssistantAPIError(status_code=404)``).
+        Returns ``(matches, skipped_count, failed_count, yaml_skipped_count,
+        timeout_count)``; semantics identical to ``_deep_search_automations``
+        — the 404 path catches YAML-defined scripts (which
+        ``client.get_script_config`` re-raises as
+        ``HomeAssistantAPIError(status_code=404)``).
         """
         script_entities = [
             e for e in all_entities if e.get("entity_id", "").startswith("script.")
@@ -451,6 +488,9 @@ class DeepSearchMixin(SceneSearchMixin):
 
         # Attempt C: parallel individual fetch with budget (see #879)
         skipped_count = 0
+        failed_count = 0
+        yaml_skipped_count = 0
+        timeout_count = 0
         if not bulk_fetched:
             sids_to_fetch = [
                 sid for _, _, sid, _ in scored if sid and sid not in configs
@@ -478,7 +518,23 @@ class DeepSearchMixin(SceneSearchMixin):
                         return (sid, None, "yaml_skipped")
                     logger.debug(f"Script individual config fetch ({sid}) failed: {e}")
                     return (sid, None, "failed")
+                except TimeoutError:
+                    # See _fetch_automation_config: per-request timeout under
+                    # batch concurrency, distinct from a real failure (#1784).
+                    logger.debug(
+                        f"Script individual config fetch ({sid}) timed out "
+                        f"after {INDIVIDUAL_CONFIG_TIMEOUT}s."
+                    )
+                    return (sid, None, "timeout")
                 except Exception as e:
+                    if is_timeout_error(e):
+                        # Client-side HTTP timeout arrived wrapped; still a
+                        # timeout. See _fetch_automation_config.
+                        logger.debug(
+                            f"Script individual config fetch ({sid}) timed "
+                            f"out (client-side HTTP timeout): {e}"
+                        )
+                        return (sid, None, "timeout")
                     logger.debug(f"Script individual config fetch ({sid}) failed: {e}")
                     return (sid, None, "failed")
 
@@ -487,6 +543,7 @@ class DeepSearchMixin(SceneSearchMixin):
                 failed_count,
                 skipped_count,
                 yaml_skipped_count,
+                timeout_count,
             ) = await self._individual_fetch_budgeted(
                 sids_to_fetch,
                 _fetch_script_config,
@@ -497,9 +554,6 @@ class DeepSearchMixin(SceneSearchMixin):
                 "scripts",
             )
             configs.update(fetched_configs)
-        else:
-            failed_count = 0
-            yaml_skipped_count = 0
 
         # Phase 3: Score scripts
         matches = [
@@ -516,7 +570,7 @@ class DeepSearchMixin(SceneSearchMixin):
                 scored, configs, query_lower, exact_match
             )
         ]
-        return matches, skipped_count, failed_count, yaml_skipped_count
+        return matches, skipped_count, failed_count, yaml_skipped_count, timeout_count
 
     async def _search_helper_type(
         self,
@@ -796,6 +850,8 @@ class DeepSearchMixin(SceneSearchMixin):
         script_failed: int = 0,
         automation_yaml_skipped: int = 0,
         script_yaml_skipped: int = 0,
+        automation_timeout: int = 0,
+        script_timeout: int = 0,
         helper_failed: int = 0,
         dashboard_failed: int = 0,
     ) -> dict[str, Any]:
@@ -856,6 +912,8 @@ class DeepSearchMixin(SceneSearchMixin):
             script_failed=script_failed,
             automation_yaml_skipped=automation_yaml_skipped,
             script_yaml_skipped=script_yaml_skipped,
+            automation_timeout=automation_timeout,
+            script_timeout=script_timeout,
             helper_failed=helper_failed,
             dashboard_failed=dashboard_failed,
         )
@@ -871,18 +929,25 @@ class DeepSearchMixin(SceneSearchMixin):
         script_failed: int = 0,
         automation_yaml_skipped: int = 0,
         script_yaml_skipped: int = 0,
+        automation_timeout: int = 0,
+        script_timeout: int = 0,
         helper_failed: int = 0,
         dashboard_failed: int = 0,
     ) -> None:
         """Set ``partial: True`` when the deep-search per-type fetch path lost
         data — either the Attempt-C wall-clock budget exhausted
-        (``*_skipped``), individual fetches raised non-404 exceptions
-        (``*_failed``, caught at ``debug``-level so they would otherwise
-        be silent), or individual fetches returned 404 because the entity
-        is YAML-defined (``*_yaml_skipped``). ``helper_failed`` /
-        ``dashboard_failed`` cover the helper- and dashboard-list/config
-        backends, whose per-unit ``except`` blocks would otherwise swallow a
-        backend outage to an empty list with no signal.
+        (``*_skipped``), individual fetches raised non-404 non-timeout
+        exceptions (``*_failed``, caught at ``debug``-level so they would
+        otherwise be silent), individual fetches returned 404 because the
+        entity is YAML-defined (``*_yaml_skipped``), or individual fetches
+        exceeded the per-request timeout (``*_timeout`` — on servers that
+        serialize config reads a concurrent batch's tail queues past the
+        timeout while perfectly healthy, so the wording points at the
+        batch-size/timeout knobs rather than at the entities, #1784).
+        ``helper_failed`` / ``dashboard_failed`` cover the helper- and
+        dashboard-list/config backends, whose per-unit ``except`` blocks
+        would otherwise swallow a backend outage to an empty list with no
+        signal.
 
         Mirrors ``_apply_scene_partial_flag`` 's "looks complete when it
         isn't" coverage onto the automation/script/helper/dashboard paths —
@@ -902,52 +967,64 @@ class DeepSearchMixin(SceneSearchMixin):
         and the new reasons are concatenated with ``" ; "``.
         """
         reasons: list[str] = []
-        if automation_skipped:
-            reasons.append(
-                f"{automation_skipped} automation(s) not scanned (time budget "
-                "exhausted) — their match status is unknown; this result is "
-                "not exhaustive. Pass `config_time_budget=` on `ha_search` to "
-                "raise the per-call limit (or, for the default, set "
-                "HAMCP_AUTOMATION_CONFIG_TIME_BUDGET or the matching field in "
-                "the web Settings UI's Advanced section)."
-            )
-        if automation_failed:
-            reasons.append(
-                f"{automation_failed} automation(s) not scanned (per-id fetch "
-                "raised a non-404 error) — their match status is unknown; "
-                "this result is not exhaustive."
-            )
-        if automation_yaml_skipped:
-            reasons.append(
-                f"{automation_yaml_skipped} automation(s) not scanned "
-                "(per-id config endpoint returned 404 — these are likely "
-                "YAML-defined automations that the /config/automation/config "
-                "REST endpoint does not expose) — their match status is "
-                "unknown; this result is not exhaustive."
-            )
-        if script_skipped:
-            reasons.append(
-                f"{script_skipped} script(s) not scanned (time budget "
-                "exhausted) — their match status is unknown; this result is "
-                "not exhaustive. Pass `config_time_budget=` on `ha_search` to "
-                "raise the per-call limit (or, for the default, set "
-                "HAMCP_SCRIPT_CONFIG_TIME_BUDGET or the matching field in "
-                "the web Settings UI's Advanced section)."
-            )
-        if script_failed:
-            reasons.append(
-                f"{script_failed} script(s) not scanned (per-id fetch raised "
-                "a non-404 error) — their match status is unknown; this "
-                "result is not exhaustive."
-            )
-        if script_yaml_skipped:
-            reasons.append(
-                f"{script_yaml_skipped} script(s) not scanned (per-id config "
-                "endpoint returned 404 — these are likely YAML-defined "
-                "scripts that the /config/script/config REST endpoint does "
-                "not expose) — their match status is unknown; this result "
-                "is not exhaustive."
-            )
+        # The automation and script fragments are symmetric (noun, per-id
+        # endpoint, budget env var); loop rather than duplicating the four
+        # per-class fragments per type.
+        for noun, endpoint, budget_env, skipped, failed, yaml_skipped, timeout in (
+            (
+                "automation",
+                "/config/automation/config",
+                "HAMCP_AUTOMATION_CONFIG_TIME_BUDGET",
+                automation_skipped,
+                automation_failed,
+                automation_yaml_skipped,
+                automation_timeout,
+            ),
+            (
+                "script",
+                "/config/script/config",
+                "HAMCP_SCRIPT_CONFIG_TIME_BUDGET",
+                script_skipped,
+                script_failed,
+                script_yaml_skipped,
+                script_timeout,
+            ),
+        ):
+            if skipped:
+                reasons.append(
+                    f"{skipped} {noun}(s) not scanned (time budget "
+                    "exhausted) — their match status is unknown; this result "
+                    "is not exhaustive. Pass `config_time_budget=` on "
+                    "`ha_search` to raise the per-call limit (or, for the "
+                    f"default, set {budget_env} or the matching field in "
+                    "the web Settings UI's Advanced section)."
+                )
+            if failed:
+                reasons.append(
+                    f"{failed} {noun}(s) not scanned (per-id fetch raised "
+                    "a non-404 error) — their match status is unknown; this "
+                    "result is not exhaustive."
+                )
+            if yaml_skipped:
+                reasons.append(
+                    f"{yaml_skipped} {noun}(s) not scanned (per-id config "
+                    "endpoint returned 404 — these are likely YAML-defined "
+                    f"{noun}s that the {endpoint} REST endpoint does not "
+                    "expose) — their match status is unknown; this result "
+                    "is not exhaustive."
+                )
+            if timeout:
+                reasons.append(
+                    f"{timeout} {noun}(s) not scanned (per-id fetch timed "
+                    f"out after {INDIVIDUAL_CONFIG_TIMEOUT}s while "
+                    f"{INDIVIDUAL_FETCH_BATCH_SIZE} fetches ran concurrently "
+                    "— this usually means the HA server serves config reads "
+                    f"serially, not that the {noun}s are broken) — their "
+                    "match status is unknown; this result is not exhaustive. "
+                    "Lower HAMCP_INDIVIDUAL_FETCH_BATCH_SIZE and/or raise "
+                    "HAMCP_INDIVIDUAL_CONFIG_TIMEOUT (or the matching fields "
+                    "in the web Settings UI's Advanced section)."
+                )
         if helper_failed:
             reasons.append(
                 f"{helper_failed} helper backend(s) not scanned (per-type list, "