ha-mcp-dev 7.14.2.dev2107__tar.gz → 7.14.2.dev2112__tar.gz

{ha_mcp_dev-7.14.2.dev2107/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2112}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.2.dev2107
+Version: 7.14.2.dev2112
 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.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2112}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.2.dev2107"
+version = "7.14.2.dev2112"
 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.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2112}/src/ha_mcp/__main__.py

@@ -31,7 +31,7 @@ import stat  # noqa: E402
 import sys  # noqa: E402
 import threading  # noqa: E402
 from collections.abc import Coroutine  # noqa: E402
-from typing import TYPE_CHECKING, Any  # noqa: E402
+from typing import TYPE_CHECKING, Any, NoReturn  # noqa: E402
 
 from fastmcp.exceptions import ToolError  # noqa: E402
 from pydantic import ValidationError as PydanticValidationError  # noqa: E402
@@ -131,6 +131,16 @@ SHUTDOWN_TIMEOUT_SECONDS = 2.0
 _shutdown_event: asyncio.Event | None = None
 _shutdown_in_progress = False
 
+# Set by the stdio entry point (main) so signal-initiated shutdown arms a
+# hard-deadline watchdog. HTTP entry points leave this False.
+_force_exit_on_shutdown = False
+
+# Hard deadline for a signal-initiated stdio shutdown. Must exceed the sum
+# of the graceful phases (server-stop wait + resource cleanup + task
+# cancellation, SHUTDOWN_TIMEOUT_SECONDS each) so it only fires when the
+# graceful path is truly stuck (issue #2027).
+_SHUTDOWN_WATCHDOG_SECONDS = 10.0
+
 # Stdin error message for Docker without -i flag
 _STDIN_ERROR_MESSAGE = """
 ==============================================================================
@@ -589,16 +599,29 @@ async def _cleanup_resources() -> None:
 
 
 async def _cancel_tasks(*tasks: asyncio.Task) -> None:
-    """Cancel tasks and wait for completion, swallowing CancelledError."""
-    for task in tasks:
-        if not task.done():
-            task.cancel()
-            try:
-                await task
-            except asyncio.CancelledError:
-                # Expected: we just cancelled this task, swallow its
-                # CancelledError so remaining tasks still get awaited.
-                pass
+    """Cancel tasks and wait for completion, bounding the wait.
+
+    A task can ignore cancellation indefinitely — the stdio transport does
+    when a blocking stdin read is in flight (issue #2027) — so the wait is
+    bounded instead of awaiting each task unboundedly. Stragglers are
+    logged and abandoned; the stdio entry point force-exits anyway.
+    """
+    pending = [task for task in tasks if not task.done()]
+    if not pending:
+        return
+    for task in pending:
+        task.cancel()
+    done, still_pending = await asyncio.wait(pending, timeout=SHUTDOWN_TIMEOUT_SECONDS)
+    if still_pending:
+        logger.warning(
+            "%d task(s) ignored cancellation during shutdown", len(still_pending)
+        )
+    for task in done:
+        if task.cancelled():
+            continue
+        exc = task.exception()
+        if exc is not None:
+            logger.warning(f"Task raised during shutdown: {exc!r}")
 
 
 async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
@@ -622,14 +645,22 @@ async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
         if shutdown_task in done:
             logger.info("Shutdown signal received, stopping server...")
             server_task.cancel()
-            try:
-                await asyncio.wait_for(server_task, timeout=SHUTDOWN_TIMEOUT_SECONDS)
-            except TimeoutError:
+            # asyncio.wait, not wait_for: wait_for's timeout path awaits the
+            # cancellation completing, which hangs when the stdio transport
+            # ignores cancellation mid-stdin-read (issue #2027). wait simply
+            # returns after the timeout, leaving the straggler abandoned.
+            stopped, _ = await asyncio.wait(
+                {server_task}, timeout=SHUTDOWN_TIMEOUT_SECONDS
+            )
+            if server_task in stopped:
+                try:
+                    server_task.result()
+                except asyncio.CancelledError:
+                    # Expected: we just cancelled server_task above; swallow
+                    # its CancelledError so shutdown can proceed to cleanup.
+                    pass
+            else:
                 logger.warning("Server did not stop within timeout")
-            except asyncio.CancelledError:
-                # Expected: we just cancelled server_task above; swallow its
-                # CancelledError so shutdown can proceed to cleanup.
-                pass
         elif server_task in done:
             # Server task finished on its own (no shutdown signal). Re-raise any
             # exception it captured so a hard startup failure surfaces as a
@@ -696,6 +727,20 @@ def _signal_handler(signum: int, frame: Any) -> None:
         sys.exit(1)
 
     _shutdown_in_progress = True
+
+    if _force_exit_on_shutdown:
+        # The SDK's stdio teardown hangs if a stdin read is in flight when
+        # the server task is cancelled: the CancelledError gets stuck being
+        # thrown into stdio_server's task group while the reader thread is
+        # parked in a blocking stdin read, so asyncio.run never returns
+        # (issue #2027 — leftover stdio instances that never exit).
+        # Guarantee the process dies even if the graceful path is stuck.
+        # Armed BEFORE the log line below: logging writes to stderr, and a
+        # full stderr pipe would block this handler before it armed anything.
+        watchdog = threading.Timer(_SHUTDOWN_WATCHDOG_SECONDS, _shutdown_watchdog_fire)
+        watchdog.daemon = True
+        watchdog.start()
+
     logger.info(f"Received {sig_name}, initiating graceful shutdown...")
 
     # Signal the shutdown event if we have an event loop
@@ -720,6 +765,61 @@ async def _run_with_graceful_shutdown() -> None:
     await _run_with_shutdown(_get_mcp().run_async(show_banner=_get_show_banner()))
 
 
+def _force_exit(code: int) -> NoReturn:
+    """Exit the stdio process without interpreter finalization (issue #2027).
+
+    The MCP SDK's stdio transport reads stdin through anyio's worker-thread
+    pool, so a daemon thread is parked in a blocking stdin read holding the
+    ``BufferedReader`` lock whenever no message is in flight. If the process
+    exits while that read is pending — SIGTERM, or the client vanishing
+    mid-read — interpreter finalization tries to close stdin, cannot acquire
+    the lock, and CPython aborts: ``Fatal Python error: _enter_buffered_busy``
+    → SIGABRT (a crash dialog on macOS). The reader lives in the SDK, so the
+    entry point neutralizes it instead: flush what matters, then skip
+    finalization entirely. By this point ``_run_with_shutdown`` has already
+    run resource cleanup, and a stdio server persists nothing at exit.
+
+    The flush is best-effort and time-bounded in a daemon thread: if the
+    client stopped draining stdout/stderr, the SDK's writer thread can be
+    blocked on the full pipe holding the buffered-writer lock, and flushing
+    inline would wait on that same lock forever — turning the hard-exit
+    path (including the shutdown watchdog) back into a hang. ``os._exit``
+    runs unconditionally once the bounded wait elapses.
+    """
+
+    def _best_effort_flush() -> None:
+        logging.shutdown()
+        for stream in (sys.stdout, sys.stderr):
+            try:
+                stream.flush()
+            except Exception:  # nothing actionable at exit
+                pass
+
+    try:
+        flusher = threading.Thread(target=_best_effort_flush, daemon=True)
+        flusher.start()
+        flusher.join(timeout=1.0)
+    finally:
+        os._exit(code)
+
+
+def _shutdown_watchdog_fire() -> None:
+    """Hard-deadline fallback for a stuck graceful shutdown (issue #2027).
+
+    The warning is fire-and-forget in a daemon thread: logging writes to
+    stderr, and a full stderr pipe blocking the warning would block the
+    watchdog itself — the very condition it exists to escape.
+    """
+    threading.Thread(
+        target=lambda: logger.warning(
+            "Graceful shutdown did not complete within %.0fs; forcing exit",
+            _SHUTDOWN_WATCHDOG_SECONDS,
+        ),
+        daemon=True,
+    ).start()
+    _force_exit(0)
+
+
 # CLI entry point (for pyproject.toml) - use FastMCP's built-in runner
 def main() -> None:
     """Run server via CLI using FastMCP's stdio transport."""
@@ -758,7 +858,28 @@ def main() -> None:
     # Best-effort: failure logs a warning but doesn't block MCP startup.
     _maybe_spawn_settings_sidecar()
 
-    _run_entrypoint(_run_with_graceful_shutdown(), "Server")
+    # Route every exit through _force_exit: letting interpreter finalization
+    # run aborts when the SDK's stdin reader thread still holds the stdin
+    # lock. _run_entrypoint always leaves via sys.exit; the BaseException
+    # arm covers hard-stop paths (e.g. the re-raised CancelledError from the
+    # #1544 handling) that would otherwise bypass the force-exit. It also
+    # lets the signal handler arm the shutdown watchdog (stdio only).
+    global _force_exit_on_shutdown
+    _force_exit_on_shutdown = True
+    code = 1  # abnormal termination unless an exit says otherwise
+    try:
+        _run_entrypoint(_run_with_graceful_shutdown(), "Server")
+        code = 0
+    except SystemExit as exc:
+        if isinstance(exc.code, int):
+            code = exc.code
+        elif exc.code is None:
+            code = 0
+        # any other code (an error-message string) keeps the default 1
+    except BaseException:
+        logger.error("Server terminated abnormally", exc_info=True)
+    finally:
+        _force_exit(code)
 
 
 def _maybe_spawn_settings_sidecar() -> None:

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2112}/src/ha_mcp/errors.py

@@ -116,6 +116,14 @@ class ErrorCode(StrEnum):
     # backup directory is unusable). Fail-closed: nothing was changed.
     BACKUP_CAPTURE_FAILED = "BACKUP_CAPTURE_FAILED"
 
+    # Entity visibility enforce mode (#2015). A read was refused because the
+    # opt-in visibility filter's enforce mode is active and the request would
+    # surface an entity the filter hides — either the tool's output references a
+    # hidden entity, or the tool's output cannot be scanned (screenshots, sandbox
+    # code). Direct reads of a hidden entity are concealed as ENTITY_NOT_FOUND
+    # instead; this code marks the refuse-on-contact case. No data was returned.
+    ENTITY_VISIBILITY_ENFORCED = "ENTITY_VISIBILITY_ENFORCED"
+
 
 # Default suggestions for common error codes
 DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2112}/src/ha_mcp/llm_exposure.py

@@ -14,9 +14,10 @@ axis from the global enable/disable in the settings UI:
 
 The single source of truth travels **in-band**: :class:`LlmExposureMiddleware`
 stamps every ``tools/list`` entry with
-``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool}`` so the component
-(one more loopback MCP client) filters on data that can never drift from the
-server's settings, with zero extra round-trips. Stamping re-reads the
+``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool, "policy": {...}}``
+so the component (one more loopback MCP client) filters on data that can never
+drift from the server's settings, with zero extra round-trips. The ``policy``
+block reports the serving server's gating state (#1990 — see META_POLICY_KEY). Stamping re-reads the
 persisted settings behind a short coalescing cache (2s TTL), so settings-UI
 changes apply on the agent's next conversation turn without a restart.
 
@@ -31,7 +32,7 @@ from __future__ import annotations
 
 import logging
 import time
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from typing import TYPE_CHECKING, Any
 
 from fastmcp.server.middleware import Middleware
@@ -50,6 +51,15 @@ META_NAMESPACE = "ha_mcp"
 META_EXPOSED_KEY = "llm_api_exposed"
 META_PINNED_KEY = "pinned"
 
+# Serving-server policy/identity block stamped alongside the per-tool keys
+# (#1990). A client (or a debugging agent) reading tools/list can see the
+# ACTUAL gating state of the server answering this connection — configured
+# flag, live middleware, and rule count — plus the deployment mode. Without
+# this, a client pointed at a different server than the one the user
+# configured rules on fails silently: calls execute ungated and nothing
+# anywhere says "this server has zero rules".
+META_POLICY_KEY = "policy"
+
 # Key in tool_config.json holding the user's per-tool overrides
 # ({tool_name: bool}). Sparse on purpose: only tools the user explicitly
 # flipped are stored, so tools added by future releases keep getting their
@@ -153,9 +163,17 @@ class LlmExposureMiddleware(Middleware):
     is hidden or altered for regular MCP clients.
     """
 
-    def __init__(self) -> None:
-        """Initialize the short-lived settings cache."""
+    def __init__(self, policy_live: Callable[[], bool] | None = None) -> None:
+        """Initialize the short-lived settings cache.
+
+        ``policy_live`` reports whether the gating middleware/queue are
+        actually wired on this server (they only wire at startup); the
+        stamp carries it so "configured but not enforcing until restart"
+        is visible on the wire.
+        """
         self._cache: tuple[float, dict[str, bool], set[str]] | None = None
+        self._policy_live = policy_live
+        self._policy_cache: tuple[float, dict[str, Any]] | None = None
 
     def _current_settings(self) -> tuple[dict[str, bool], set[str]]:
         """Return (overrides, pinned) with a short TTL over the file reads."""
@@ -192,6 +210,47 @@ class LlmExposureMiddleware(Middleware):
         self._cache = (now, overrides, pinned)
         return overrides, pinned
 
+    def _policy_block(self) -> dict[str, Any]:
+        """Serving-server policy/identity block (TTL-cached like the overrides).
+
+        Best-effort: a failure to read settings or the policy file stamps
+        conservative values (enabled=False / rules=0) rather than breaking
+        tools/list — the block is diagnostic metadata, not enforcement.
+        """
+        now = time.monotonic()
+        if (
+            self._policy_cache is not None
+            and now - self._policy_cache[0] < _OVERRIDES_TTL_SECONDS
+        ):
+            return self._policy_cache[1]
+        from ._version import is_embedded, is_running_in_addon
+
+        block: dict[str, Any] = {
+            "enabled": False,
+            "live": bool(self._policy_live()) if self._policy_live else False,
+            "rules": 0,
+            "deployment": (
+                "embedded"
+                if is_embedded()
+                else ("addon" if is_running_in_addon() else "standalone")
+            ),
+        }
+        try:
+            from .config import get_global_settings
+
+            block["enabled"] = bool(get_global_settings().enable_tool_security_policies)
+        except Exception:
+            logger.debug("policy stamp: settings read failed", exc_info=True)
+        try:
+            from .policy.persistence import load_policy
+            from .utils.data_paths import get_data_dir
+
+            block["rules"] = len(load_policy(get_data_dir()).rules)
+        except Exception:
+            logger.debug("policy stamp: policy read failed", exc_info=True)
+        self._policy_cache = (now, block)
+        return block
+
     async def on_list_tools(
         self,
         context: MiddlewareContext[mt.ListToolsRequest],
@@ -200,6 +259,7 @@ class LlmExposureMiddleware(Middleware):
         """Stamp ``_meta.ha_mcp`` on every tool in the list result."""
         tools = await call_next(context)
         overrides, pinned = self._current_settings()
+        policy_block = self._policy_block()
 
         stamped: list[Tool] = []
         for tool in tools:
@@ -209,6 +269,7 @@ class LlmExposureMiddleware(Middleware):
                 tool.name, tool.tags or set(), overrides
             )
             namespace[META_PINNED_KEY] = tool.name in pinned
+            namespace[META_POLICY_KEY] = policy_block
             meta[META_NAMESPACE] = namespace
             stamped.append(tool.model_copy(update={"meta": meta}))
         return stamped

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2112}/src/ha_mcp/policy/handlers.py

@@ -11,6 +11,7 @@ from pydantic import ValidationError
 from starlette.requests import Request
 from starlette.responses import JSONResponse
 
+from ..utils.config_write_lock import config_write_guard
 from .approval_queue import ApprovalQueue
 from .model import Policy
 from .persistence import load_policy, save_policy
@@ -86,24 +87,29 @@ async def _put_config(
     # Optimistic concurrency: reject if the on-disk version moved
     # between this caller's GET and PUT. Returns the current policy
     # so the client can rebase if it wants to retry.
-    current = load_policy(data_dir)
-    if new_policy.version != current.version:
-        return JSONResponse(
-            {
-                "error": "policy version mismatch — reload before saving",
-                "current_version": current.version,
-                "current_policy": current.model_dump(mode="json"),
-            },
-            status_code=409,
-        )
-    save_policy(data_dir, new_policy)
-    # Drop the remember-cache only when rules actually changed.
-    # Editing just wait_seconds / approval_ttl_minutes shouldn't
-    # invalidate in-flight remembered approvals; only a rule change
-    # could make a previously-approved call now want a different
-    # outcome.
-    if current.rules != new_policy.rules:
-        queue.clear_remember_cache()
+    # Serialize the version-check + save against the developer tool
+    # (set_policy / set_tool) AND against other processes (the stdio
+    # sidecar runs this same handler in its own process) so a concurrent
+    # writer can't slip between the read and the write and lose an update.
+    async with config_write_guard():
+        current = load_policy(data_dir)
+        if new_policy.version != current.version:
+            return JSONResponse(
+                {
+                    "error": "policy version mismatch — reload before saving",
+                    "current_version": current.version,
+                    "current_policy": current.model_dump(mode="json"),
+                },
+                status_code=409,
+            )
+        save_policy(data_dir, new_policy)
+        # Drop the remember-cache only when rules actually changed.
+        # Editing just wait_seconds / approval_ttl_minutes shouldn't
+        # invalidate in-flight remembered approvals; only a rule change
+        # could make a previously-approved call now want a different
+        # outcome.
+        if current.rules != new_policy.rules:
+            queue.clear_remember_cache()
     return JSONResponse({"saved": True, "version": new_policy.version + 1})
 
 

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2112}/src/ha_mcp/policy/middleware.py

@@ -35,6 +35,29 @@ PROXY_META_TOOLS = frozenset(
     }
 )
 
+# ha_dev_manage_server actions that MANAGE the approval queue itself.
+# Gating these deadlocks by construction: with a wildcard (or
+# ha_dev_manage_server) rule in place, an MCP-only "approve" call would
+# itself require approval — creating a second pending entry instead of
+# deciding the first, so nothing can ever be approved through the tool.
+# Only the queue-management actions are exempt; update_source / restart
+# remain gateable like any other high-stakes action.
+_APPROVAL_MANAGEMENT_TOOL = "ha_dev_manage_server"
+_APPROVAL_MANAGEMENT_ACTIONS = frozenset({"list_pending", "approve", "deny"})
+
+
+def _is_approval_management(name: str, args: dict[str, Any]) -> bool:
+    """True for dev-tool calls that manage the approval queue itself."""
+    return (
+        name == _APPROVAL_MANAGEMENT_TOOL
+        and args.get("action") in _APPROVAL_MANAGEMENT_ACTIONS
+    )
+
+
+def _passes_ungated(name: str, args: dict[str, Any]) -> bool:
+    """Calls that must bypass gating: proxy meta-tools + queue management."""
+    return name in PROXY_META_TOOLS or _is_approval_management(name, args)
+
 
 class PolicyMiddleware(Middleware):
     """Gate tool calls against a Policy, blocking with progress heartbeats."""
@@ -78,7 +101,7 @@ class PolicyMiddleware(Middleware):
         name = context.message.name
         args = context.message.arguments or {}
 
-        if name in PROXY_META_TOOLS:
+        if _passes_ungated(name, args):
             return await call_next(context)
 
         if evaluate(name, args, policy) != Verdict.REQUIRE_APPROVAL:

{ha_mcp_dev-7.14.2.dev2107 → ha_mcp_dev-7.14.2.dev2112}/src/ha_mcp/policy/model.py

@@ -16,6 +16,14 @@ PredicateOp = Literal[
     "eq", "neq", "in", "not_in", "regex", "contains", "exists", "gt", "lt"
 ]
 
+# Schema generation of the persisted policy file. Version 2 = ANY-match
+# condition semantics (PR #1993): each UI condition is its own rule; a rule's
+# predicates AND together (a condition with sub-parameters). Files WITHOUT the
+# marker were written under the pre-#1993 editor, which packed every condition
+# into one AND-ed rule — ``persistence.migrate_policy_any_semantics`` splits
+# those once at startup and stamps the file.
+POLICY_SCHEMA_VERSION = 2
+
 
 class Predicate(BaseModel):
     """Single condition on a tool call's arguments (e.g. args.domain in [...])."""
@@ -103,6 +111,9 @@ class Policy(BaseModel):
     approval_ttl_minutes: int = Field(default=5, ge=1, le=60)
     rules: list[Rule] = Field(default_factory=list)
     version: int = Field(default=0, ge=0)
+    # ANY-match schema marker (see POLICY_SCHEMA_VERSION). Detection of
+    # unmigrated files reads the RAW json (this default would mask it).
+    schema_version: int = Field(default=POLICY_SCHEMA_VERSION, ge=1)
 
     @model_validator(mode="after")
     def _wait_must_be_less_than_ttl(self) -> "Policy":

ha_mcp_dev-7.14.2.dev2112/src/ha_mcp/policy/persistence.py

@@ -0,0 +1,125 @@
+"""Atomic load/save for tool_policy.json (mirrors tool_config.json pattern in settings_ui/__init__.py)."""
+
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from .model import Policy, Rule
+
+logger = logging.getLogger(__name__)
+
+POLICY_FILENAME = "tool_policy.json"
+
+
+def load_policy(data_dir: Path) -> Policy:
+    path = data_dir / POLICY_FILENAME
+    if not path.exists():
+        return Policy()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ValueError(f"tool_policy.json is not valid JSON: {e}") from e
+    try:
+        return Policy.model_validate(raw)
+    except ValidationError as e:
+        raise ValueError(f"tool_policy.json failed schema validation: {e}") from e
+
+
+def migrate_policy_any_semantics(data_dir: Path) -> bool:
+    """One-time migration of a pre-ANY policy file (PR #1993). Returns True on write.
+
+    The pre-#1993 editor packed every UI condition into ONE rule with the
+    predicates AND-ed ("require approval when ALL conditions match"). The
+    editor now writes one rule per condition and the UI reads "ANY condition
+    matches" — so an untouched old file would silently enforce AND while the
+    UI claims ANY. This splits every multi-predicate rule of an UNSTAMPED
+    file into one single-predicate rule each (the explicit, documented
+    breaking change: old AND conditions become OR, the more-restrictive
+    direction) and stamps ``schema_version`` so the migration never re-runs —
+    post-upgrade multi-predicate rules (a condition with AND-ed
+    sub-parameters, hand-authored or via future UI) are left intact.
+
+    Detection reads the RAW json: the Policy model defaults
+    ``schema_version`` to current, which would mask an unstamped file.
+    Missing or corrupt files are left alone (load_policy surfaces corruption).
+
+    The whole read-split-save runs under ``config_file_lock()`` so a
+    concurrent writer in another process (the stdio settings sidecar) can't
+    interleave with the migration's read-modify-write. The blocking lock is
+    taken inline: this runs once during server construction, before anything
+    is served. The sync entry points construct pre-loop; OAuth/OIDC construct
+    on a just-started ``asyncio.run`` loop (``_run_oauth_server`` /
+    ``_run_oidc_server``) where the sync constructor cannot await — but no
+    other task is scheduled on that loop yet, so a held lock can only delay
+    startup, never stall a served client.
+    """
+    from ..utils.config_write_lock import config_file_lock
+
+    with config_file_lock(data_dir):
+        return _migrate_policy_any_semantics_locked(data_dir)
+
+
+def _migrate_policy_any_semantics_locked(data_dir: Path) -> bool:
+    path = data_dir / POLICY_FILENAME
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return False
+    except (OSError, json.JSONDecodeError):
+        logger.warning("policy migration: cannot read %s; leaving as-is", path)
+        return False
+    if not isinstance(raw, dict) or raw.get("schema_version") is not None:
+        return False
+    try:
+        policy = Policy.model_validate(raw)
+    except ValidationError:
+        logger.warning("policy migration: %s failed validation; leaving as-is", path)
+        return False
+    new_rules: list[Rule] = []
+    split = 0
+    for rule in policy.rules:
+        if len(rule.when) > 1:
+            split += 1
+            new_rules.extend(
+                Rule(
+                    tool_name=rule.tool_name,
+                    when=[predicate],
+                    remember_minutes=rule.remember_minutes,
+                )
+                for predicate in rule.when
+            )
+        else:
+            new_rules.append(rule)
+    save_policy(data_dir, policy.model_copy(update={"rules": new_rules}))
+    logger.info(
+        "Migrated %s to ANY-match condition semantics: split %d multi-condition "
+        "rule(s) into one rule per condition (%d -> %d rules) and stamped "
+        "schema_version. Conditions that previously ALL had to match now EACH "
+        "gate on their own.",
+        path,
+        split,
+        len(policy.rules),
+        len(new_rules),
+    )
+    return True
+
+
+def save_policy(data_dir: Path, policy: Policy) -> None:
+    # Bump version on every save so optimistic-concurrency callers can
+    # detect mid-flight edits (PUT /api/policy/config 409s when the
+    # caller's payload version != on-disk version).
+    bumped = policy.model_copy(update={"version": policy.version + 1})
+    data_dir.mkdir(parents=True, exist_ok=True)
+    path = data_dir / POLICY_FILENAME
+    fd, tmp_path = tempfile.mkstemp(prefix=f".{POLICY_FILENAME}.", dir=data_dir)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(bumped.model_dump(mode="json"), f, indent=2, sort_keys=True)
+        os.replace(tmp_path, path)
+    except Exception:
+        Path(tmp_path).unlink(missing_ok=True)
+        raise