@event4u/agent-config 2.2.2 → 2.4.0

package/scripts/_lib/installed_tools.py

@@ -4,7 +4,7 @@ Phase 3 of road-to-global-first-install (ADR-008). Committed
 bill-of-materials for AI tooling a project depends on. Sibling to the
 global lockfile (``installed_lock.py``) but architecturally distinct:
 
-- ``installed_lock.py`` lives in ``~/.config/agent-config/`` and tracks
+- ``installed_lock.py`` lives in ``~/.event4u/agent-config/`` and tracks
   the user-scope environment (a single ``agent_config_version`` and a
   flat ``tools[]`` list).
 - ``installed_tools.py`` lives in ``agents/`` and tracks **per-project**
@@ -21,17 +21,46 @@ from __future__ import annotations
 
 import os
 import re
-import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
 
+try:
+    from scripts._lib.fs_atomic import write_atomic  # noqa: PLC0415
+except ImportError:  # pragma: no cover — alt sys.path layout (tests)
+    from _lib.fs_atomic import write_atomic  # type: ignore[no-redef]  # noqa: PLC0415
+
 MANIFEST_ENV = "AGENT_CONFIG_INSTALLED_TOOLS"
 DEFAULT_MANIFEST_RELATIVE = Path("agents") / "installed-tools.lock"
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
+
+#: Schema versions older writers may have emitted. Reading any of these
+#: succeeds; writing always produces :data:`SCHEMA_VERSION`.
+SCHEMA_VERSIONS_SUPPORTED = (1, 2)
 
 _VALID_SCOPES = ("global", "project")
 
+#: Permitted values for ``files[].kind`` (P1.1, road-to-multi-package-
+#: coexistence). ``bridge`` = team-pointer marker (e.g. ``.cursorrules``);
+#: ``deployed`` = bundle content we wrote (e.g. ``.augment/rules/*.md``);
+#: ``marker`` = one-off sentinel (e.g. ``claude-desktop`` install marker).
+FILE_KINDS = frozenset({"bridge", "deployed", "marker"})
+
+#: Stable known deploy roots — directories under which the doctor
+#: command surveys for foreign files. Writers may extend the live
+#: ``deploy_roots`` field per project; this constant is the canonical
+#: default the installer seeds.
+DEFAULT_DEPLOY_ROOTS = (
+    ".augment/rules",
+    ".augment/skills",
+    ".augment/commands",
+    ".cursor/rules",
+    ".claude/skills",
+    ".claude/commands",
+    ".clinerules",
+    ".windsurf/rules",
+)
+
 
 def manifest_path(project_root: Path, env: Optional[dict] = None) -> Path:
     """Return the active manifest path, honoring the env override."""
@@ -56,31 +85,71 @@ def read_manifest(path: Path) -> Optional[dict[str, Any]]:
 
     Tolerates partial / malformed files: missing keys yield missing dict
     entries rather than raising, so a corrupted file does not brick
-    ``init``.
+    ``init``. v1 and v2 wire formats both return the same shape — v2
+    optional fields (``deploy_roots``, per-tool ``files`` /
+    ``merged_keys``) default to empty lists when absent, so callers can
+    iterate without ``.get(..., [])`` boilerplate (P1.2).
     """
     try:
         text = path.read_text(encoding="utf-8")
     except (FileNotFoundError, OSError):
         return None
+    data: Optional[dict[str, Any]] = None
     try:
         import yaml  # type: ignore[import-untyped]
-        data = yaml.safe_load(text) or {}
-        if isinstance(data, dict):
-            data.setdefault("tools", [])
-            return data
+        loaded = yaml.safe_load(text) or {}
+        if isinstance(loaded, dict):
+            data = loaded
     except ImportError:
         pass
     except Exception:
         # Fall through to the manual parser; corrupt YAML is recoverable
         # from our strict schema as long as the top-level shape holds.
         pass
-    return _parse_manual(text)
+    if data is None:
+        data = _parse_manual(text)
+    return _normalise_v2_shape(data)
+
+
+def _normalise_v2_shape(data: dict[str, Any]) -> dict[str, Any]:
+    """Backfill v2 optional fields so consumers can iterate uniformly.
+
+    Idempotent: calling on an already-normalised dict is a no-op. Does
+    not mutate input lists — replaces missing keys with fresh empties.
+    """
+    if data.get("tools") is None:
+        data["tools"] = []
+    if data.get("deploy_roots") is None:
+        data["deploy_roots"] = []
+    for tool in data["tools"]:
+        if not isinstance(tool, dict):
+            continue
+        if tool.get("files") is None:
+            tool["files"] = []
+        if tool.get("merged_keys") is None:
+            tool["merged_keys"] = []
+    return data
 
 
 def _parse_manual(text: str) -> dict[str, Any]:
+    """Strict v1 manual parser; v2 nested fields are skipped, not raised.
+
+    The fallback parser handles the canonical v1 wire format (top-level
+    scalars + ``tools`` array with single-level key:value entries). For
+    v2 manifests it still extracts the top-level scalars and the
+    per-tool scalar fields, but silently drops nested arrays
+    (``files``, ``merged_keys``) and top-level ``deploy_roots``. Callers
+    that need full v2 fidelity must have ``pyyaml`` available — the
+    manual path is a degraded read, not a v2 round-trip.
+    """
     data: dict[str, Any] = {"tools": []}
     in_tools = False
     current: Optional[dict[str, Any]] = None
+    # When the current tool entry opened a nested array (``files:`` or
+    # ``merged_keys:``), we suppress recognition of the deeper ``- key``
+    # lines as new tools until the indent climbs back to the per-tool
+    # level (4 spaces).
+    skip_until_outdent = False
     for raw in text.splitlines():
         stripped = raw.strip()
         if not stripped or stripped.startswith("#"):
@@ -88,25 +157,39 @@ def _parse_manual(text: str) -> dict[str, Any]:
         if stripped == "tools:":
             in_tools = True
             current = None
+            skip_until_outdent = False
             continue
         if in_tools:
+            indent = len(raw) - len(raw.lstrip(" "))
+            if skip_until_outdent and indent > 4:
+                continue
+            skip_until_outdent = False
             m = _LIST_DASH_RE.match(raw)
-            if m:
+            if m and indent == 2:
                 first = m.group(1)
                 current = {}
                 data["tools"].append(current)
-                # Could be inline like `- name: foo` — handle that.
                 inline = _TOP_KEY_RE.match(first)
                 if inline:
                     current[inline.group(1)] = inline.group(2)
                 continue
             mk = _INDENT_KEY_RE.match(raw)
-            if mk and current is not None:
-                current[mk.group(1)] = mk.group(2)
+            if mk and current is not None and indent == 4:
+                key, val = mk.group(1), mk.group(2)
+                if key in ("files", "merged_keys") and not val:
+                    skip_until_outdent = True
+                    continue
+                current[key] = val
                 continue
         m_top = _TOP_KEY_RE.match(raw)
         if m_top:
             key, value = m_top.group(1), m_top.group(2)
+            if key == "deploy_roots" and not value:
+                # Top-level v2 array — skip until next top-level scalar.
+                in_tools = False
+                current = None
+                skip_until_outdent = True
+                continue
             if key == "schema_version":
                 try:
                     data[key] = int(value)
@@ -116,6 +199,7 @@ def _parse_manual(text: str) -> dict[str, Any]:
                 data[key] = value
             in_tools = False
             current = None
+            skip_until_outdent = False
     return data
 
 
@@ -127,17 +211,54 @@ def _parse_manual(text: str) -> dict[str, Any]:
 def _render(
     version: str,
     tools: list[dict[str, Any]],
+    *,
+    deploy_roots: Optional[list[str]] = None,
 ) -> str:
     lines = [
         f"schema_version: {SCHEMA_VERSION}",
         f'agent_config_version: "{version}"',
-        "tools:",
     ]
+    if deploy_roots:
+        lines.append("deploy_roots:")
+        for root in deploy_roots:
+            lines.append(f"  - {root}")
+    lines.append("tools:")
     for tool in tools:
         lines.append(f"  - name: {tool['name']}")
         lines.append(f"    scope: {tool['scope']}")
         lines.append(f"    bridge_marker: {tool['bridge_marker']}")
         lines.append(f'    installed_at: "{tool["installed_at"]}"')
+        status = tool.get("status")
+        if status:
+            lines.append(f"    status: {status}")
+        files = tool.get("files") or []
+        if files:
+            # Sort by path ascending — deterministic output for golden-
+            # file tests and stable team diffs (P1.3).
+            files = sorted(files, key=lambda f: f["path"])
+            lines.append("    files:")
+            for entry in files:
+                lines.append(f"      - path: {entry['path']}")
+                lines.append(f"        kind: {entry['kind']}")
+                sha = entry.get("sha256")
+                if sha is None:
+                    lines.append("        sha256: null")
+                else:
+                    lines.append(f'        sha256: "{sha}"')
+        merged = tool.get("merged_keys") or []
+        if merged:
+            # Sort by (file, json_pointer) ascending — deterministic
+            # output regardless of insertion order (P1.3).
+            merged = sorted(
+                merged, key=lambda e: (e["file"], e["json_pointer"]),
+            )
+            lines.append("    merged_keys:")
+            for entry in merged:
+                lines.append(f"      - file: {entry['file']}")
+                lines.append(f"        json_pointer: \"{entry['json_pointer']}\"")
+                vh = entry.get("value_hash")
+                if vh is not None:
+                    lines.append(f'        value_hash: "{vh}"')
     return "\n".join(lines) + "\n"
 
 
@@ -145,24 +266,23 @@ def write_manifest(
     path: Path,
     version: str,
     tools: list[dict[str, Any]],
+    *,
+    deploy_roots: Optional[list[str]] = None,
 ) -> Path:
-    """Atomically write the manifest; return the path written."""
-    path.parent.mkdir(parents=True, exist_ok=True)
-    rendered = _render(version, tools)
-    fd, tmp_name = tempfile.mkstemp(
-        prefix=".installed-tools.lock.", dir=str(path.parent), text=False
-    )
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
-            fh.write(rendered)
-        os.replace(tmp_name, path)
-    except Exception:
-        try:
-            os.unlink(tmp_name)
-        except OSError:
-            pass
-        raise
-    return path
+    """Atomically write the manifest; return the path written.
+
+    Delegates to :func:`scripts._lib.fs_atomic.write_atomic` so the
+    crash-safety guarantees (fsync file, atomic rename, fsync parent
+    dir) are shared with every other v2 writer. See P1.0 of
+    ``road-to-multi-package-coexistence`` for the rationale.
+
+    ``deploy_roots`` is the optional top-level v2 field listing
+    directories the doctor command surveys for foreign files. When
+    omitted, the field is not emitted (callers may rely on
+    :data:`DEFAULT_DEPLOY_ROOTS` for the survey scope).
+    """
+    rendered = _render(version, tools, deploy_roots=deploy_roots)
+    return write_atomic(path, rendered)
 
 
 # ---------------------------------------------------------------------------
@@ -191,6 +311,8 @@ def upsert_tool(
     bridge_marker: str,
     installed_at: Optional[str] = None,
     force: bool = False,
+    files: Optional[list[dict[str, Any]]] = None,
+    merged_keys: Optional[list[dict[str, Any]]] = None,
 ) -> list[dict[str, Any]]:
     """Return a new tools list with ``name`` added or refreshed.
 
@@ -199,10 +321,34 @@ def upsert_tool(
     * Same name, different scope → raise ``ScopeMismatchError`` unless
       ``force=True``, in which case the entry is rewritten.
     * New name → appended in install order (not alphabetised).
+
+    ``files`` / ``merged_keys`` are the v2 per-tool inventories
+    (P1.4). When provided, they replace whatever was previously
+    recorded on the entry — the installer is authoritative for the
+    set of artefacts it just wrote. When ``None``, existing values
+    are preserved on the idempotent path and absent on first-write.
     """
     if scope not in _VALID_SCOPES:
         raise ValueError(f"scope must be one of {_VALID_SCOPES}: {scope!r}")
     stamp = installed_at or _today()
+
+    def _build(prior: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        entry: dict[str, Any] = {
+            "name": name,
+            "scope": scope,
+            "bridge_marker": bridge_marker,
+            "installed_at": stamp,
+        }
+        if files is not None:
+            entry["files"] = list(files)
+        elif prior is not None and prior.get("files"):
+            entry["files"] = list(prior["files"])
+        if merged_keys is not None:
+            entry["merged_keys"] = list(merged_keys)
+        elif prior is not None and prior.get("merged_keys"):
+            entry["merged_keys"] = list(prior["merged_keys"])
+        return entry
+
     result: list[dict[str, Any]] = []
     found = False
     for entry in existing:
@@ -210,26 +356,24 @@ def upsert_tool(
             found = True
             recorded = str(entry.get("scope", ""))
             if recorded == scope:
-                # Idempotent no-op — preserve original installed_at.
-                result.append(entry)
+                if files is None and merged_keys is None:
+                    # Idempotent no-op — preserve original entry.
+                    result.append(entry)
+                else:
+                    # Refresh inventories, preserve installed_at.
+                    refreshed = _build(prior=entry)
+                    refreshed["installed_at"] = entry.get(
+                        "installed_at", stamp,
+                    )
+                    result.append(refreshed)
                 continue
             if not force:
                 raise ScopeMismatchError(name, recorded, scope)
-            result.append({
-                "name": name,
-                "scope": scope,
-                "bridge_marker": bridge_marker,
-                "installed_at": stamp,
-            })
+            result.append(_build(prior=entry))
             continue
         result.append(entry)
     if not found:
-        result.append({
-            "name": name,
-            "scope": scope,
-            "bridge_marker": bridge_marker,
-            "installed_at": stamp,
-        })
+        result.append(_build())
     return result
 
 

package/scripts/_lib/json_pointers.py

@@ -0,0 +1,260 @@
+"""JSON-pointer helpers for the v2 ``merged_keys[]`` manifest field.
+
+P1.5 of road-to-multi-package-coexistence (Anthropic constraint
+2026-05-12). When a tool merges into a shared JSON file, the manifest
+records which JSON pointers it owns so uninstall can subtract them
+cleanly without touching foreign keys. Two invariants:
+
+1. **No array indices.** Pointers MUST target named object keys only.
+   ``/hooks/PostToolUse`` is valid; ``/hooks/PostToolUse/0`` is not.
+   Array indices shift when another tool inserts or removes entries
+   at the same array, so an index-based pointer corrupts other
+   packages' ownership records on neighbour-tool uninstall.
+2. **Arrays carry a ``value_hash`` discriminator.** A pointer that
+   targets a parent whose value is a list records the SHA-256 of the
+   JSON-serialised list contents the install wrote, so uninstall can
+   identify the owned elements by content rather than position.
+
+This module is dependency-free (stdlib only) so it can be imported in
+both the installer (``scripts/install.py``) and the manifest layer
+(``scripts/_lib/installed_tools.py``).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Optional
+
+
+class ArrayIndexPointerError(ValueError):
+    """Raised when a JSON pointer segment is an array index."""
+
+    def __init__(self, pointer: str, segment: str):
+        super().__init__(
+            f"json_pointer {pointer!r} targets array index {segment!r}; "
+            "pointers MUST target named object keys only "
+            "(see road-to-multi-package-coexistence.md § P1.5)"
+        )
+        self.pointer = pointer
+        self.segment = segment
+
+
+def _escape_segment(key: str) -> str:
+    """Escape a JSON pointer segment per RFC 6901 § 4."""
+    return key.replace("~", "~0").replace("/", "~1")
+
+
+def validate_pointer(pointer: str) -> None:
+    """Raise :class:`ArrayIndexPointerError` if any segment is an integer.
+
+    The empty pointer (``""``) is valid (targets the document root).
+    Otherwise the pointer must start with ``/`` and split into
+    segments; each segment that parses cleanly as a non-negative
+    integer is rejected (RFC 6901 array-index syntax).
+    """
+    if pointer == "":
+        return
+    if not pointer.startswith("/"):
+        raise ValueError(
+            f"json_pointer {pointer!r} must start with '/' (RFC 6901)"
+        )
+    # Skip the leading empty segment from the leading slash.
+    segments = pointer.split("/")[1:]
+    for seg in segments:
+        # RFC 6901 § 4 — array index = unsigned integer, no leading zero
+        # except for "0" itself.
+        if seg.isdigit() and (seg == "0" or not seg.startswith("0")):
+            raise ArrayIndexPointerError(pointer, seg)
+
+
+def value_hash(value: Any) -> str:
+    """Return a stable SHA-256 hex digest of ``value`` (JSON-serialised).
+
+    Uses canonical JSON (sorted keys, no whitespace) so the hash is
+    insertion-order independent. Used to discriminate tool-owned
+    entries in a shared array on uninstall.
+    """
+    payload = json.dumps(value, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def collect_pointers(
+    overlay: dict,
+    *,
+    prefix: str = "",
+    include_arrays: bool = True,
+) -> list[dict[str, Any]]:
+    """Walk an overlay dict and return one entry per object-key pointer.
+
+    Each entry: ``{"json_pointer": str, "value_hash": Optional[str]}``.
+    ``value_hash`` is set when the targeted value is a list (arrays
+    need content-hash discrimination on uninstall); for nested dicts
+    we recurse and emit a pointer for each inner key. Scalars get a
+    pointer with ``value_hash=None`` (the key/value pair fully
+    identifies the merge).
+
+    The collector NEVER emits array-index pointers — list contents
+    are owned wholesale at the parent key.
+    """
+    entries: list[dict[str, Any]] = []
+    for key, value in overlay.items():
+        pointer = f"{prefix}/{_escape_segment(str(key))}"
+        if isinstance(value, dict):
+            # Recurse so the manifest captures the leaf object keys,
+            # not just the root container. Empty dicts get a single
+            # entry at the key so an uninstall can still remove them.
+            if not value:
+                entries.append({"json_pointer": pointer, "value_hash": None})
+            else:
+                entries.extend(
+                    collect_pointers(
+                        value, prefix=pointer, include_arrays=include_arrays,
+                    )
+                )
+        elif isinstance(value, list):
+            entries.append(
+                {
+                    "json_pointer": pointer,
+                    "value_hash": value_hash(value) if include_arrays else None,
+                }
+            )
+        else:
+            entries.append({"json_pointer": pointer, "value_hash": None})
+    # Validate every emitted pointer once at the end — cheap and
+    # guarantees the invariant even if a future caller hand-crafts
+    # entries.
+    for entry in entries:
+        validate_pointer(entry["json_pointer"])
+    return entries
+
+
+def build_merge_entries(
+    file_label: str,
+    overlay: dict,
+) -> list[dict[str, Any]]:
+    """Return v2 ``merged_keys[]`` entries for a single JSON merge.
+
+    ``file_label`` is the manifest-relative file path the merge
+    touched (e.g. ``.cursor/hooks.json``). The overlay is the dict the
+    installer wrote into the file; only its top-level object keys
+    become pointers (recursing through nested objects, halting at
+    lists / scalars).
+    """
+    pointers = collect_pointers(overlay)
+    return [
+        {
+            "file": file_label,
+            "json_pointer": entry["json_pointer"],
+            "value_hash": entry["value_hash"],
+        }
+        for entry in pointers
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Subtraction (P2.2 — uninstall round-trip)
+# ---------------------------------------------------------------------------
+
+
+def _split_segments(pointer: str) -> list[str]:
+    """Split a non-empty pointer into unescaped segments."""
+    if pointer == "":
+        return []
+    # RFC 6901: leading '/' separates segments; unescape ~1 → '/' and ~0 → '~'.
+    parts = pointer.split("/")[1:]
+    return [p.replace("~1", "/").replace("~0", "~") for p in parts]
+
+
+def _navigate(doc: Any, segments: list[str]) -> tuple[Any, str] | None:
+    """Walk ``doc`` down ``segments`` and return ``(parent_dict, leaf_key)``.
+
+    Returns ``None`` when any intermediate segment is missing or not a
+    dict (we never descend into lists by index, see :func:`validate_pointer`).
+    """
+    if not segments:
+        return None
+    cursor = doc
+    for seg in segments[:-1]:
+        if not isinstance(cursor, dict) or seg not in cursor:
+            return None
+        cursor = cursor[seg]
+    if not isinstance(cursor, dict):
+        return None
+    leaf = segments[-1]
+    if leaf not in cursor:
+        return None
+    return cursor, leaf
+
+
+def subtract_pointers(
+    doc: dict,
+    entries: list[dict[str, Any]],
+) -> tuple[dict, list[dict[str, Any]]]:
+    """Remove the pointers in ``entries`` from ``doc``; trim empty ancestors.
+
+    ``entries`` is a list of ``{"json_pointer": str, "value_hash":
+    Optional[str]}`` records (the per-file slice of a tool's
+    ``merged_keys[]``). For each entry:
+
+    * ``value_hash is None`` → delete the key at the pointer.
+    * ``value_hash is set`` → the target is a list owned wholesale by
+      the tool. Delete only when the current value's hash still
+      matches; otherwise treat as **drift** (a neighbour package or
+      the user edited the array) and skip, surfacing a warning.
+
+    After every leaf removal we walk up the ancestor chain and drop
+    any empty dict the removal left behind — but only empty ones. A
+    neighbour tool's remaining keys keep the container alive, so its
+    contributions are never touched.
+
+    Returns ``(updated_doc, warnings)`` where ``warnings`` is a list of
+    ``{"pointer": str, "reason": "missing" | "drift", "expected_hash":
+    Optional[str], "actual_hash": Optional[str]}`` entries describing
+    pointers that could not be subtracted cleanly.
+    """
+    warnings: list[dict[str, Any]] = []
+    # Sort longest-first so leaves are removed before their ancestors —
+    # otherwise ancestor cleanup races leaf removal in deep trees.
+    ordered = sorted(
+        entries,
+        key=lambda e: len(_split_segments(e["json_pointer"])),
+        reverse=True,
+    )
+    for entry in ordered:
+        pointer = entry["json_pointer"]
+        expected = entry.get("value_hash")
+        segments = _split_segments(pointer)
+        nav = _navigate(doc, segments)
+        if nav is None:
+            warnings.append({
+                "pointer": pointer,
+                "reason": "missing",
+                "expected_hash": expected,
+                "actual_hash": None,
+            })
+            continue
+        parent, leaf = nav
+        if expected is not None:
+            actual = value_hash(parent[leaf])
+            if actual != expected:
+                warnings.append({
+                    "pointer": pointer,
+                    "reason": "drift",
+                    "expected_hash": expected,
+                    "actual_hash": actual,
+                })
+                continue
+        del parent[leaf]
+        # Trim empty-ancestor chain — never remove a container that
+        # still holds foreign keys.
+        for depth in range(len(segments) - 1, 0, -1):
+            ancestor_segments = segments[:depth]
+            anc_nav = _navigate(doc, ancestor_segments)
+            if anc_nav is None:
+                break
+            anc_parent, anc_leaf = anc_nav
+            if isinstance(anc_parent[anc_leaf], dict) and not anc_parent[anc_leaf]:
+                del anc_parent[anc_leaf]
+                continue
+            break
+    return doc, warnings

package/scripts/_lib/update_check.py

@@ -10,7 +10,10 @@ Design constraints (see roadmap P2):
 
 - Stdlib only (no new deps); the package's Python floor is stdlib-only.
 - 1 s hard timeout on the registry call; network failure is silent.
-- 24 h cadence gated by ``~/.config/agent-config/update-check.json``.
+- 24 h cadence gated by ``~/.event4u/agent-config/update-check.json``
+  (legacy ``~/.config/agent-config/update-check.json`` is read once as
+  a fallback so the cadence is not reset on the first run after the
+  Phase-1 namespace migration).
 - Suppress in CI, on non-TTY stdout, when ``AGENT_CONFIG_NO_UPDATE_CHECK=1``,
   or when ``update_check.enabled: false`` in settings.
 - State file mode is ``0600``.
@@ -30,12 +33,29 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Optional
 
+from scripts._lib import user_global_paths
+
 PACKAGE_NAME = "@event4u/agent-config"
 NPM_REGISTRY_URL = f"https://registry.npmjs.org/{PACKAGE_NAME}/latest"
 FETCH_TIMEOUT_S = 1.0
 CHECK_WINDOW = timedelta(hours=24)
 
-DEFAULT_STATE_PATH = Path.home() / ".config" / "agent-config" / "update-check.json"
+STATE_FILENAME = "update-check.json"
+
+#: Canonical write target. Reads are routed via
+#: :func:`_resolve_state_path` with a read-fallback to the legacy
+#: ``~/.config/agent-config/update-check.json`` so a fresh install
+#: under the new namespace does not lose the 24 h cadence window
+#: established by a pre-2.4 install.
+DEFAULT_STATE_PATH = user_global_paths.write_target(STATE_FILENAME)
+
+
+def _resolve_state_path() -> Path:
+    """Return the active state path, preferring the new namespace."""
+    found = user_global_paths.resolve_with_fallback(STATE_FILENAME)
+    if found is not None:
+        return found
+    return DEFAULT_STATE_PATH
 
 
 def _now_utc() -> datetime:
@@ -159,8 +179,12 @@ def check_for_update(
         return None
 
     now = now or _now_utc()
-    state_path = state_path or DEFAULT_STATE_PATH
-    state = _read_state(state_path)
+    # When the caller does not pin a state path, route through the
+    # fallback resolver so a pre-2.4 install's cadence file is still
+    # consulted before we decide to re-check npm.
+    read_path = state_path or _resolve_state_path()
+    write_path = state_path or DEFAULT_STATE_PATH
+    state = _read_state(read_path)
     if not _should_check(state, now):
         latest = state.get("last_seen_version")
         if isinstance(latest, str) and _is_newer(latest, installed_version):
@@ -174,7 +198,7 @@ def check_for_update(
         "installed_version": installed_version,
     }
     try:
-        _write_state(state_path, payload)
+        _write_state(write_path, payload)
     except OSError:
         pass