@event4u/agent-config 2.3.0 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.3.0",
+    "version": "2.4.1",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_uninstall.py

@@ -302,7 +302,7 @@ def _parse(argv: list[str]) -> argparse.Namespace:
         ),
     )
     parser.add_argument("--global", dest="global_mode", action="store_true",
-                        help="operate on user-scope lockfile (~/.config/agent-config/installed.lock)")
+                        help="operate on user-scope lockfile (~/.event4u/agent-config/installed.lock; legacy ~/.config/agent-config/installed.lock read as fallback)")
     parser.add_argument("--tools", default=None,
                         help="comma-separated tool IDs to uninstall (default: all in lockfile)")
     parser.add_argument("--project", default=None, help="project root (default: cwd)")
@@ -422,6 +422,7 @@ def _uninstall_project(opts: argparse.Namespace) -> int:
 
 def _uninstall_global(opts: argparse.Namespace) -> int:
     lock_path = installed_lock.lockfile_path()
+    write_path = installed_lock.lockfile_write_path()
     lock = installed_lock.read_lockfile(lock_path)
     if lock is None and not opts.force:
         print(f"❌  no global lockfile at {lock_path}", file=sys.stderr)
@@ -442,15 +443,24 @@ def _uninstall_global(opts: argparse.Namespace) -> int:
             removed_names.append(tool)
     if lock is not None and not opts.dry_run:
         remaining = [t for t in lock.get("tools", []) if t not in tools]
+        version = lock.get("agent_config_version", "")
         if remaining:
-            installed_lock.write_lockfile(remaining, version=lock.get("agent_config_version", ""))
+            installed_lock.write_lockfile(version, remaining, path=write_path)
+            # Drop the legacy file if it differs from the canonical write
+            # target so the namespace migration completes on uninstall.
+            if lock_path != write_path:
+                try:
+                    lock_path.unlink()
+                except OSError:
+                    pass
             print(f"✅  lockfile updated ({len(tools)} entries removed, {len(remaining)} kept)")
         else:
-            try:
-                lock_path.unlink()
-                print(f"✅  lockfile deleted ({lock_path})")
-            except OSError as exc:
-                print(f"⚠️   could not delete lockfile: {exc}")
+            for target in {lock_path, write_path}:
+                try:
+                    target.unlink()
+                except OSError:
+                    pass
+            print(f"✅  lockfile deleted ({write_path})")
     return 0
 
 

package/scripts/_cli/cmd_update.py

@@ -233,24 +233,28 @@ def main(
 
 
 def _refresh_global_lockfile(version: str, *, out=sys.stdout) -> None:
-    """Update ``~/.config/agent-config/installed.lock`` if it exists.
+    """Update the global ``installed.lock`` if it exists.
+
+    Resolution prefers ``~/.event4u/agent-config/installed.lock`` and
+    falls back to the legacy ``~/.config/agent-config/installed.lock``.
 
     Phase 1.6 — the lockfile is only present when the user has run a
     global install; we never create one here, but we keep it in lockstep
     when ``update`` flips the pin. Atomic write goes through
     ``installed_lock.write_lockfile``.
     """
-    lock_path = installed_lock.lockfile_path()
-    existing = installed_lock.read_lockfile(path=lock_path)
+    read_path = installed_lock.lockfile_path()
+    write_path = installed_lock.lockfile_write_path()
+    existing = installed_lock.read_lockfile(path=read_path)
     if existing is None:
         return
     recorded = existing.get("agent_config_version")
     tools = list(existing.get("tools", []))
-    if recorded == version:
-        print(f"ℹ️  {lock_path} already records {version}.", file=out)
+    if recorded == version and read_path == write_path:
+        print(f"ℹ️  {write_path} already records {version}.", file=out)
         return
-    installed_lock.write_lockfile(version, tools, path=lock_path)
-    print(f"✅  Refreshed global lockfile at {lock_path}.", file=out)
+    installed_lock.write_lockfile(version, tools, path=write_path)
+    print(f"✅  Refreshed global lockfile at {write_path}.", file=out)
 
 
 def _detect_installed_version() -> str:

package/scripts/_lib/agent_settings.py

@@ -5,11 +5,18 @@ how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
 
 Resolution order (deepest wins; user-global is whitelist-filtered only):
 
-  N. ``~/.config/agent-config/agent-settings.yml``  (user-global; whitelist only)
+  N. ``~/.event4u/agent-config/agent-settings.yml`` (user-global; whitelist only)
 N-1. ``<repo-root>/.agent-settings.yml``            (project-wide; all keys)
 N-2. ``<intermediate-dir>/.agent-settings.yml``     (subsystem-scoped; all keys)
   1. ``<CWD>/.agent-settings.yml``                  (deepest, wins; all keys)
 
+The user-global path is resolved via the sibling
+:mod:`work_engine._lib.user_global_paths` module (vendored from
+``scripts/_lib/user_global_paths.py`` so the engine stays self-contained
+when shipped into consumer projects) with a read-fallback to the legacy
+``~/.config/agent-config/agent-settings.yml`` so pre-2.4 installs keep
+working during the namespace migration.
+
 ``<repo-root>`` is the nearest ancestor that contains ``.git`` (directory
 **or** file — submodule support). The walk stops there — it never drifts
 into a parent repo or ``$HOME``. When ``cwd`` is ``None`` (default), the
@@ -37,12 +44,26 @@ import logging
 from pathlib import Path
 from typing import Any, Iterator
 
+from . import user_global_paths
+
 logger = logging.getLogger(__name__)
 
 DEFAULT_PROJECT_FILE = ".agent-settings.yml"
-DEFAULT_USER_GLOBAL_FILE = (
-    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
-)
+USER_GLOBAL_FILENAME = "agent-settings.yml"
+
+#: Canonical write target under the new ``~/.event4u/agent-config/``
+#: namespace. Reads route through :func:`_resolve_user_global_file` so
+#: pre-2.4 installs are still picked up from ``~/.config/agent-config/``
+#: until the migration shim copies them across.
+DEFAULT_USER_GLOBAL_FILE = user_global_paths.write_target(USER_GLOBAL_FILENAME)
+
+
+def _resolve_user_global_file() -> Path:
+    """Return the active user-global settings path with legacy fallback."""
+    found = user_global_paths.resolve_with_fallback(USER_GLOBAL_FILENAME)
+    if found is not None:
+        return found
+    return DEFAULT_USER_GLOBAL_FILE
 
 #: Exact dotted paths allowed to cascade from user-global into the merged
 #: settings. Anything not listed here is silently ignored when present in
@@ -129,7 +150,8 @@ def load_agent_settings(
 
     ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
     ``user_global_path`` defaults to
-    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``~/.event4u/agent-config/agent-settings.yml`` (with a read fallback
+    to the legacy ``~/.config/agent-config/agent-settings.yml``). Both arguments accept
     ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
     user-global that are not on the whitelist.
 
@@ -143,7 +165,7 @@ def load_agent_settings(
     with pre-cascade callers.
     """
     user_global_raw = _read_yaml(
-        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+        Path(user_global_path) if user_global_path else _resolve_user_global_file(),
     ) or {}
 
     user_global_filtered, ignored = _filter_whitelist(
@@ -181,7 +203,7 @@ def iter_setting_overrides(
     Never blocks, never raises on missing files.
     """
     user_global_path_resolved = (
-        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE
+        Path(user_global_path) if user_global_path else _resolve_user_global_file()
     )
     user_global_raw = _read_yaml(user_global_path_resolved) or {}
     user_global_filtered, _ = _filter_whitelist(user_global_raw, MERGEABLE_KEYS)

package/scripts/_lib/agents_overlay.py

@@ -8,9 +8,12 @@ user-global directory (when the ``kind`` is whitelisted).
 
 Resolution order (deepest wins, every layer optional):
 
-  N. ``~/.config/agent-config/agents/<kind>/<name>.md``  (user-global; weakest;
+  N. ``~/.event4u/agent-config/agents/<kind>/<name>.md`` (user-global; weakest;
                                                           ``kind`` must be in
-                                                          ``USER_GLOBAL_OVERLAY_KINDS``)
+                                                          ``USER_GLOBAL_OVERLAY_KINDS``;
+                                                          legacy
+                                                          ``~/.config/agent-config/agents/``
+                                                          tree read as fallback)
 N-1. ``<repo-root>/agents/<kind>/<name>.md``
 N-2. ``<intermediate-dir>/agents/<kind>/<name>.md``      (optional)
   1. ``<CWD>/agents/<kind>/<name>.md``                   (deepest, wins)
@@ -34,6 +37,7 @@ from __future__ import annotations
 import logging
 from pathlib import Path
 
+from scripts._lib import user_global_paths
 from scripts._lib.agent_settings import find_project_root
 
 logger = logging.getLogger(__name__)
@@ -50,13 +54,17 @@ CASCADE_ELIGIBLE_KINDS: frozenset[str] = frozenset({
 })
 
 #: Subset of :data:`CASCADE_ELIGIBLE_KINDS` allowed to live at the
-#: user-global layer (``~/.config/agent-config/agents/<kind>/``).
+#: user-global layer (``~/.event4u/agent-config/agents/<kind>/``).
 #: ``contexts/`` and ``decisions/`` are project-shaped and must not leak
 #: across projects; only ``overrides/`` — the developer's personal
 #: layer — is whitelisted.
 USER_GLOBAL_OVERLAY_KINDS: frozenset[str] = frozenset({"overrides"})
 
-USER_GLOBAL_AGENTS_DIR = Path.home() / ".config" / "agent-config" / "agents"
+#: Canonical write target under the new vendor namespace. The probe in
+#: :func:`resolve_overlay` adds the legacy ``~/.config/agent-config/agents/``
+#: tree as a read-only fallback for pre-2.4 installs.
+USER_GLOBAL_AGENTS_DIR = user_global_paths.write_target("agents")
+_LEGACY_USER_GLOBAL_AGENTS_DIR = user_global_paths.legacy_xdg_root() / "agents"
 
 
 def resolve_overlay(name: str, kind: str, cwd: Path) -> Path | None:
@@ -83,6 +91,9 @@ def resolve_overlay(name: str, kind: str, cwd: Path) -> Path | None:
     candidates: list[Path] = []
 
     if kind in USER_GLOBAL_OVERLAY_KINDS:
+        # Legacy first, new last — deepest wins, so the new namespace
+        # overrides the legacy path when both happen to exist mid-migration.
+        candidates.append(_LEGACY_USER_GLOBAL_AGENTS_DIR / kind / f"{name}.md")
         candidates.append(USER_GLOBAL_AGENTS_DIR / kind / f"{name}.md")
 
     root = find_project_root(cwd)

package/scripts/_lib/claude_desktop_bundler.py

@@ -0,0 +1,150 @@
+"""Claude Desktop skill ZIP bundler (Phase 4 of event4u-namespace roadmap).
+
+Claude Desktop has no filesystem convention for skills; the Customize →
+Skills UI accepts a ZIP per skill via the Upload button. This module
+walks ``<package_root>/.agent-src/skills/*`` and produces one
+``<skill-name>.zip`` per directory into ``dest_dir``.
+
+Contract:
+
+- Each ZIP contains ``SKILL.md`` plus every sibling file under the same
+  directory (recursive). Symlinks are dereferenced so the ZIP is
+  self-contained.
+- Exclusions: ``.git*``, ``__pycache__``, ``*.pyc`` — matched on the
+  basename of any path component.
+- A skill folder without a ``SKILL.md`` is skipped (defensive: avoids
+  shipping Claude-Code orchestrator stubs that don't follow the
+  Anthropic skill schema).
+- Writes are atomic via tempfile → ``os.replace``.
+- Idempotent: each ZIP gets a sibling ``<skill-name>.sha256`` recording
+  the manifest digest. If the recomputed digest matches the recorded
+  one, the existing ZIP is left untouched (unless ``force=True``).
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Iterable, Optional
+
+#: Filenames or path components that are never included in a bundle.
+_EXCLUDED_BASENAMES = frozenset({"__pycache__", ".DS_Store"})
+_EXCLUDED_PREFIXES = (".git",)
+_EXCLUDED_SUFFIXES = (".pyc", ".pyo")
+
+
+def _is_excluded(rel_parts: tuple[str, ...]) -> bool:
+    """Return True if any component matches the exclusion lists."""
+    for part in rel_parts:
+        if part in _EXCLUDED_BASENAMES:
+            return True
+        if part.startswith(_EXCLUDED_PREFIXES):
+            return True
+        if part.endswith(_EXCLUDED_SUFFIXES):
+            return True
+    return False
+
+
+def _walk_skill_files(skill_dir: Path) -> list[tuple[Path, tuple[str, ...]]]:
+    """Return ``[(abs_path, rel_parts), ...]`` for every file in the skill.
+
+    Symlinks are followed (``os.walk(..., followlinks=True)``) so a
+    bundle from a symlinked entry under ``.agent-src/skills/`` contains
+    the actual target content, not a dangling symlink.
+    """
+    out: list[tuple[Path, tuple[str, ...]]] = []
+    resolved = skill_dir.resolve()
+    for root, dirs, files in os.walk(resolved, followlinks=True):
+        root_path = Path(root)
+        rel_root = root_path.relative_to(resolved)
+        # Prune excluded dirs in-place so os.walk skips them.
+        dirs[:] = [d for d in dirs if not _is_excluded((d,))]
+        for fname in files:
+            rel_parts = (*rel_root.parts, fname) if rel_root.parts else (fname,)
+            if _is_excluded(rel_parts):
+                continue
+            out.append((root_path / fname, rel_parts))
+    out.sort(key=lambda item: item[1])
+    return out
+
+
+def _manifest_digest(files: Iterable[tuple[Path, tuple[str, ...]]]) -> str:
+    """Hash sorted (rel_path, content_sha256) pairs into one digest.
+
+    Stable across runs as long as the input set + bytes are stable. Used
+    as the idempotency token written to ``<skill>.sha256``.
+    """
+    h = hashlib.sha256()
+    for abs_path, rel_parts in files:
+        rel = "/".join(rel_parts)
+        h.update(rel.encode("utf-8"))
+        h.update(b"\x00")
+        h.update(hashlib.sha256(abs_path.read_bytes()).digest())
+        h.update(b"\x00")
+    return h.hexdigest()
+
+
+def _atomic_write_zip(
+    zip_path: Path, files: list[tuple[Path, tuple[str, ...]]]
+) -> None:
+    """Write ``files`` into ``zip_path`` atomically (temp + rename)."""
+    zip_path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{zip_path.stem}.", suffix=".zip.tmp", dir=str(zip_path.parent),
+    )
+    os.close(fd)
+    tmp_path = Path(tmp_name)
+    try:
+        with zipfile.ZipFile(tmp_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for abs_path, rel_parts in files:
+                zf.write(abs_path, arcname="/".join(rel_parts))
+        os.replace(tmp_path, zip_path)
+    finally:
+        if tmp_path.exists():
+            tmp_path.unlink()
+
+
+def build_skill_bundles(
+    package_root: Path,
+    dest_dir: Path,
+    force: bool = False,
+    curation: Optional[list[str]] = None,
+) -> list[Path]:
+    """Build per-skill ZIPs under ``dest_dir``.
+
+    Returns the list of ZIP paths that were (re-)written this call. ZIPs
+    skipped because their content digest matched the existing sidecar
+    are not in the returned list (but remain on disk).
+
+    ``curation`` optionally restricts the build to the given skill
+    names; ``None`` bundles every skill folder containing ``SKILL.md``.
+    """
+    skills_root = package_root / ".agent-src" / "skills"
+    if not skills_root.is_dir():
+        return []
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for entry in sorted(skills_root.iterdir()):
+        if not (entry.is_dir() or entry.is_symlink()):
+            continue
+        skill_name = entry.name
+        if curation is not None and skill_name not in curation:
+            continue
+        skill_md = entry / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        files = _walk_skill_files(entry)
+        if not files:
+            continue
+        digest = _manifest_digest(files)
+        zip_path = dest_dir / f"{skill_name}.zip"
+        digest_path = dest_dir / f"{skill_name}.sha256"
+        recorded = digest_path.read_text(encoding="utf-8").strip() if digest_path.exists() else ""
+        if not force and recorded == digest and zip_path.exists():
+            continue
+        _atomic_write_zip(zip_path, files)
+        digest_path.write_text(digest + "\n", encoding="utf-8")
+        written.append(zip_path)
+    return written

package/scripts/_lib/installed_lock.py

@@ -1,4 +1,4 @@
-"""Global-install lockfile at ``~/.config/agent-config/installed.lock``.
+"""Global-install lockfile at ``~/.event4u/agent-config/installed.lock``.
 
 Phase 1.6 of road-to-global-first-install (ADR-007 D5). Records the
 package version that performed the most recent user-scope install plus
@@ -10,6 +10,12 @@ flip in ``.agent-settings.yml``.
 The schema is intentionally minimal YAML so the module can read and
 write without depending on ``pyyaml``. Atomic writes go through
 ``tempfile + os.replace`` per ADR-007 risk-mitigation row.
+
+Path resolution is delegated to :mod:`scripts._lib.user_global_paths`
+(Phase 1 of road-to-event4u-namespace-and-claude-desktop.md): writes
+land at ``~/.event4u/agent-config/installed.lock``; reads fall back to
+the legacy ``~/.config/agent-config/installed.lock`` if the new path
+is missing, so pre-2.4 installs keep working during the transition.
 """
 from __future__ import annotations
 
@@ -21,10 +27,22 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from scripts._lib import user_global_paths
+
 LOCKFILE_ENV = "AGENT_CONFIG_INSTALLED_LOCK"
-DEFAULT_LOCKFILE = Path.home() / ".config" / "agent-config" / "installed.lock"
 SCHEMA_VERSION = 1
 
+
+def _default_lockfile() -> Path:
+    """Canonical write target for the lockfile (new namespace)."""
+    return user_global_paths.write_target("installed.lock")
+
+
+# Module-level constant retained for back-compat with importers that read
+# ``installed_lock.DEFAULT_LOCKFILE`` directly. Derived from the helper so
+# the path tracks any future override of ``event4u_root()``.
+DEFAULT_LOCKFILE = _default_lockfile()
+
 _VERSION_RE = re.compile(r'^\s*agent_config_version\s*:\s*"?([^"\s]+)"?\s*$')
 _SCHEMA_RE = re.compile(r"^\s*schema_version\s*:\s*(\d+)\s*$")
 _INSTALLED_AT_RE = re.compile(r'^\s*installed_at\s*:\s*"?([^"\s]+)"?\s*$')
@@ -32,12 +50,46 @@ _TOOL_RE = re.compile(r"^\s*-\s*([A-Za-z0-9_\-.]+)\s*$")
 
 
 def lockfile_path(env: Optional[dict] = None) -> Path:
-    """Return the active lockfile path, honoring the env override."""
+    """Return the active lockfile path for **reads**, honoring overrides.
+
+    Resolution order:
+
+    1. ``$AGENT_CONFIG_INSTALLED_LOCK``  — explicit full-path override.
+    2. ``~/.event4u/agent-config/installed.lock`` if it exists on disk.
+    3. ``~/.config/agent-config/installed.lock``  (legacy fallback, read-only).
+    4. Canonical write target under the new namespace (Step 2 fallthrough).
+
+    Readers benefit from (3) so pre-2.4 installs keep working while the
+    migration shim has not yet run. Writers must use
+    :func:`lockfile_write_path` so a stale legacy file does not anchor
+    subsequent writes to the deprecated location.
+    """
+    env = env if env is not None else os.environ
+    override = env.get(LOCKFILE_ENV)
+    if override:
+        return Path(override).expanduser()
+    resolved = user_global_paths.resolve_with_fallback("installed.lock", env=env)
+    if resolved is not None:
+        return resolved
+    return user_global_paths.write_target("installed.lock", env=env)
+
+
+def lockfile_write_path(env: Optional[dict] = None) -> Path:
+    """Return the canonical write target for the lockfile.
+
+    Unlike :func:`lockfile_path`, this never falls back to the legacy
+    ``~/.config/agent-config/`` location. Honors the
+    ``$AGENT_CONFIG_INSTALLED_LOCK`` override for tests, otherwise pins
+    to ``~/.event4u/agent-config/installed.lock``. Callers in
+    ``init``, ``update``, and ``uninstall`` use this so writes always
+    land in the new namespace regardless of whether a stale legacy
+    lockfile is still present.
+    """
     env = env if env is not None else os.environ
     override = env.get(LOCKFILE_ENV)
     if override:
         return Path(override).expanduser()
-    return DEFAULT_LOCKFILE
+    return user_global_paths.write_target("installed.lock", env=env)
 
 
 def read_lockfile(path: Optional[Path] = None) -> Optional[dict]:

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**

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