@event4u/agent-config 1.41.1 → 2.0.0

package/scripts/_cli/cmd_update.py

@@ -0,0 +1,226 @@
+"""``agent-config update`` — explicit, opt-in update of the version pin.
+
+Phase 3 of road-to-portable-runtime-and-update-check (P3.1). The
+command is the only user-driven path that flips
+``agent_config_version`` in ``.agent-settings.yml``; the daily banner
+(P2) never writes settings files.
+
+Flags:
+
+* ``--check`` — print the available latest version + return; no write.
+* ``--to <version>`` — pin to an exact version (registry-existence
+  checked). Downgrades are allowed; the pin is a project decision.
+* (no flag) — pin to the registry's ``latest`` tag.
+
+Write target: the **deepest** ``.agent-settings.yml`` in the project
+cascade that already carries the ``agent_config_version`` key. When no
+file carries it, the repo-root file is created/edited. Comments and
+key ordering are preserved by line-based substitution.
+
+The npx cache is warmed via
+``npx --yes @event4u/agent-config@<new> --version`` so the next
+invocation is offline-fast. The P2 state file is refreshed in
+lockstep — the new ``installed_version`` is recorded so the banner
+does not yell about the old pin.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from scripts._lib import update_check
+from scripts._lib.agent_settings import (
+    DEFAULT_PROJECT_FILE,
+    _resolve_cascade_paths,
+    find_project_root,
+)
+
+PACKAGE_NAME = "@event4u/agent-config"
+PIN_KEY = "agent_config_version"
+REGISTRY_VERSION_URL = f"https://registry.npmjs.org/{PACKAGE_NAME}/{{version}}"
+PIN_LINE_RE = re.compile(r"^(\s*agent_config_version\s*:\s*)(.*)$")
+
+
+def _normalize(version: str) -> str:
+    return version.strip().lstrip("v")
+
+
+def _registry_has_version(version: str, *, timeout: float = 1.0) -> bool:
+    url = REGISTRY_VERSION_URL.format(version=_normalize(version))
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            return resp.status == 200
+    except (urllib.error.URLError, TimeoutError, OSError):
+        return False
+
+
+def _find_pin_file(cwd: Path) -> Path:
+    """Return the deepest cascade file that carries the pin, else repo root."""
+    cascade = _resolve_cascade_paths(cwd, None)
+    for path in reversed(cascade):
+        if path.is_file() and _read_pin_line(path) is not None:
+            return path
+    # No file carries it — pick the repo-root cascade entry (shallowest).
+    if cascade:
+        return cascade[0]
+    return cwd / DEFAULT_PROJECT_FILE
+
+
+def _read_pin_line(path: Path) -> Optional[int]:
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            for idx, line in enumerate(fh):
+                if PIN_LINE_RE.match(line):
+                    return idx
+    except OSError:
+        return None
+    return None
+
+
+def _write_pin(path: Path, new_version: str) -> bool:
+    """Rewrite the pin in ``path``; return ``True`` if the file changed."""
+    target = f'agent_config_version: "{_normalize(new_version)}"\n'
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+    except FileNotFoundError:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(target, encoding="utf-8")
+        return True
+    for idx, line in enumerate(lines):
+        if PIN_LINE_RE.match(line):
+            if lines[idx] == target:
+                return False
+            lines[idx] = target
+            path.write_text("".join(lines), encoding="utf-8")
+            return True
+    # File exists but has no pin line — append at end.
+    if lines and not lines[-1].endswith("\n"):
+        lines.append("\n")
+    lines.append(target)
+    path.write_text("".join(lines), encoding="utf-8")
+    return True
+
+
+def _warm_npx_cache(version: str, *, runner=subprocess.run) -> None:
+    try:
+        runner(
+            ["npx", "--yes", f"{PACKAGE_NAME}@{_normalize(version)}", "--version"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=120,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+def _refresh_state(installed: str, latest: str, state_path: Path) -> None:
+    state = update_check._read_state(state_path)
+    payload = {
+        "last_check_utc": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "last_seen_version": latest,
+        "installed_version": installed,
+    }
+    state.update(payload)
+    try:
+        update_check._write_state(state_path, state)
+    except OSError:
+        pass
+
+
+def main(
+    argv: Optional[list[str]] = None,
+    *,
+    cwd: Optional[Path] = None,
+    installed_version: Optional[str] = None,
+    fetcher=update_check.fetch_latest_from_npm,
+    version_checker=_registry_has_version,
+    cache_warmer=_warm_npx_cache,
+    state_path: Optional[Path] = None,
+    out=sys.stdout,
+    err=sys.stderr,
+) -> int:
+    """Entry point. ``scripts/agent-config`` dispatches here."""
+    parser = argparse.ArgumentParser(
+        prog="agent-config update",
+        description="Update the agent_config_version pin in .agent-settings.yml.",
+    )
+    parser.add_argument("--check", action="store_true",
+                        help="Print the latest available version and exit. No file is written.")
+    parser.add_argument("--to", metavar="VERSION",
+                        help="Pin to an explicit version (registry-existence checked).")
+    args = parser.parse_args(argv)
+
+    cwd = (cwd or Path.cwd()).resolve()
+    installed_version = installed_version or _detect_installed_version()
+    state_path = state_path or update_check.DEFAULT_STATE_PATH
+
+    if args.to:
+        target = _normalize(args.to)
+        if not version_checker(target):
+            print(
+                f"❌  agent-config: version {target} not found on the npm registry.",
+                file=err,
+            )
+            return 1
+        latest = target
+    else:
+        latest = fetcher()
+        if not latest:
+            print(
+                "❌  agent-config: failed to fetch latest version from the npm registry.",
+                file=err,
+            )
+            return 1
+        latest = _normalize(latest)
+
+    if args.check:
+        if update_check._is_newer(latest, installed_version):
+            print(f"agent-config {latest} available (you have {installed_version}).", file=out)
+            print(f"Update: npx {PACKAGE_NAME} update", file=out)
+        else:
+            print(f"agent-config is up to date ({installed_version}).", file=out)
+        return 0
+
+    pin_file = _find_pin_file(cwd)
+    changed = _write_pin(pin_file, latest)
+    try:
+        rel = pin_file.relative_to(cwd)
+    except ValueError:
+        rel = pin_file
+
+    if changed:
+        print(f"✅  Pinned {PACKAGE_NAME} to {latest} in {rel}.", file=out)
+    else:
+        print(f"ℹ️  {rel} already pins to {latest}.", file=out)
+
+    cache_warmer(latest)
+    _refresh_state(latest, latest, state_path)
+    return 0
+
+
+def _detect_installed_version() -> str:
+    """Read ``version`` from the package's own ``package.json``."""
+    pkg_json = Path(__file__).resolve().parents[2] / "package.json"
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+        version = data.get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    except (OSError, ValueError, json.JSONDecodeError):
+        pass
+    return "0.0.0"
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())
+

package/scripts/_lib/agent_settings.py

@@ -3,17 +3,24 @@
 Phase 1 of road-to-portable-dev-preferences. Single source of truth for
 how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
 
-Resolution order (project wins, user-global fills gaps for whitelisted
-keys only):
+Resolution order (deepest wins; user-global is whitelist-filtered only):
 
-  1. Project ``./.agent-settings.yml``                  (full file, all keys)
-  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
-  3. Built-in defaults                                  (currently empty)
+  N. ``~/.config/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)
+
+``<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
+loader behaves identically to the pre-cascade contract: project file +
+user-global only, no ancestor walk. Back-compat is hard.
 
 Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
 non-whitelisted key in the user-global file is silently ignored — the
 ``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
-debugging.
+debugging. Non-root in-project layers (intermediate + CWD) are **not**
+whitelist-filtered — they live inside the project boundary.
 
 Contract — pure, read-only, tolerant:
 
@@ -28,7 +35,7 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import Any
+from typing import Any, Iterator
 
 logger = logging.getLogger(__name__)
 
@@ -53,10 +60,70 @@ MERGEABLE_KEYS: tuple[str, ...] = (
 _DEFAULTS: dict[str, Any] = {}
 
 
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from ``start`` looking for ``.git`` (file or directory).
+
+    Returns the first ancestor that contains ``.git`` as a file (submodule
+    pointer) or directory (regular checkout), or ``None`` if the walk
+    reaches the filesystem root without finding one. The walk stops at
+    the project boundary — it never drifts into a parent repo or
+    ``$HOME``.
+
+    Pure read-only; never touches the filesystem beyond ``exists()``
+    probes on the ``.git`` entry.
+    """
+    current = start.resolve() if start.exists() else start
+    # ``Path.parents`` excludes ``current`` itself, so probe it first.
+    for candidate in [current, *current.parents]:
+        git_marker = candidate / ".git"
+        if git_marker.exists():
+            return candidate
+    return None
+
+
+def _resolve_cascade_paths(
+    cwd: Path | None,
+    project_path: Path | str | None,
+) -> list[Path]:
+    """Return the ordered cascade of in-project settings files (shallow → deep).
+
+    When ``cwd`` is provided and ``find_project_root(cwd)`` succeeds, the
+    list contains every ``<dir>/.agent-settings.yml`` from the repo root
+    down to ``cwd`` (inclusive on both ends), shallowest first. When
+    ``cwd`` is ``None`` or no ``.git`` is reached, falls back to the
+    single legacy project path — back-compat with the pre-cascade
+    loader.
+    """
+    if cwd is None:
+        legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
+        return [legacy]
+
+    root = find_project_root(cwd)
+    if root is None:
+        legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
+        return [legacy]
+
+    cwd_resolved = cwd.resolve()
+    # Build the chain root → … → cwd (shallowest first, deepest last).
+    chain: list[Path] = []
+    cursor = cwd_resolved
+    while True:
+        chain.append(cursor)
+        if cursor == root:
+            break
+        parent = cursor.parent
+        if parent == cursor:
+            break
+        cursor = parent
+    chain.reverse()
+    return [d / DEFAULT_PROJECT_FILE for d in chain]
+
+
 def load_agent_settings(
     project_path: Path | str | None = None,
     user_global_path: Path | str | None = None,
     verbose: bool = False,
+    cwd: Path | None = None,
 ) -> dict[str, Any]:
     """Return the merged settings dict.
 
@@ -65,10 +132,16 @@ def load_agent_settings(
     ``~/.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.
+
+    ``cwd`` enables the in-project cascade: when provided **and**
+    ``find_project_root(cwd)`` reaches a ``.git`` ancestor, the loader
+    walks every ``.agent-settings.yml`` from the repo root down to
+    ``cwd`` and merges them shallowest → deepest (deepest wins).
+    Non-root layers are **not** whitelist-filtered (they live inside the
+    project boundary). When ``cwd`` is ``None`` (default), the loader
+    falls back to the single ``project_path`` behaviour — back-compat
+    with pre-cascade callers.
     """
-    project = _read_yaml(
-        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
-    ) or {}
     user_global_raw = _read_yaml(
         Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
     ) or {}
@@ -82,12 +155,48 @@ def load_agent_settings(
             sorted(ignored),
         )
 
+    cascade = _resolve_cascade_paths(cwd, project_path)
+
     merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
     _deep_merge(merged, user_global_filtered)
-    _deep_merge(merged, project)
+    for path in cascade:
+        layer = _read_yaml(path) or {}
+        if layer:
+            _deep_merge(merged, layer)
     return merged
 
 
+def iter_setting_overrides(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    cwd: Path | None = None,
+) -> Iterator[tuple[str, Any, Path]]:
+    """Yield ``(dotted_key, value, source_path)`` for every leaf setting.
+
+    Walks the same cascade as :func:`load_agent_settings` and emits one
+    tuple per leaf observed at each layer (user-global → repo-root →
+    intermediates → CWD). Callers can detect overrides by grouping
+    tuples on ``dotted_key`` — the deepest tuple per group wins. Useful
+    for ``task settings:trace`` and other banner-only diagnostics.
+    Never blocks, never raises on missing files.
+    """
+    user_global_path_resolved = (
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE
+    )
+    user_global_raw = _read_yaml(user_global_path_resolved) or {}
+    user_global_filtered, _ = _filter_whitelist(user_global_raw, MERGEABLE_KEYS)
+    if user_global_filtered:
+        for key in _leaf_paths(user_global_filtered):
+            yield key, _get_dotted(user_global_filtered, key), user_global_path_resolved
+
+    for path in _resolve_cascade_paths(cwd, project_path):
+        layer = _read_yaml(path)
+        if not layer:
+            continue
+        for key in _leaf_paths(layer):
+            yield key, _get_dotted(layer, key), path
+
+
 def _read_yaml(path: Path) -> dict[str, Any] | None:
     """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
     if not path.is_file():

package/scripts/_lib/agents_overlay.py

@@ -0,0 +1,109 @@
+"""Resolve files under ``agents/<kind>/<name>.md`` via the cascade.
+
+Phase 1 of road-to-portable-runtime-and-update-check. Companion to
+``agent_settings.py``: where the settings loader merges YAML, this
+resolves single-file overlays — overrides, contexts, decisions — to a
+single deepest match across the in-project ancestor chain plus the
+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;
+                                                          ``kind`` must be in
+                                                          ``USER_GLOBAL_OVERLAY_KINDS``)
+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)
+
+Asymmetry: ``overrides/`` is the developer's personal layer and may
+live user-global; ``contexts/`` and ``decisions/`` are project-shaped
+and must not leak across projects, so the user-global layer is
+silently skipped for them. Stateful subdirs (``state/``, ``memory/``,
+``roadmaps/``, ``work_engine/``, ``council-*/``) are not cascade-eligible
+at all and raise ``ValueError`` when passed as ``kind``.
+
+Contract — pure, read-only, tolerant:
+
+* Does not read file contents — returns the resolved ``Path`` only.
+* Missing layer / missing file → silently skipped, never raises.
+* Invalid ``kind`` → ``ValueError`` (programmer error, not user input).
+* No file is ever created or written by this module.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from scripts._lib.agent_settings import find_project_root
+
+logger = logging.getLogger(__name__)
+
+#: Subdirs of ``agents/`` that participate in the cascade. Every entry
+#: is **additive** (single-file artefacts; deepest wins). Stateful or
+#: session-scoped subdirs (``state/``, ``memory/``, ``roadmaps/``,
+#: ``work_engine/``, ``.agent-prices.md``, ``council-*/``) are
+#: deliberately excluded — they are project-rooted only.
+CASCADE_ELIGIBLE_KINDS: frozenset[str] = frozenset({
+    "overrides",
+    "contexts",
+    "decisions",
+})
+
+#: Subset of :data:`CASCADE_ELIGIBLE_KINDS` allowed to live at the
+#: user-global layer (``~/.config/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"
+
+
+def resolve_overlay(name: str, kind: str, cwd: Path) -> Path | None:
+    """Return the deepest existing ``agents/<kind>/<name>.md`` or ``None``.
+
+    Walks the in-project ancestor chain from ``cwd`` to the ``.git``
+    repo root (inclusive) and probes each layer for
+    ``agents/<kind>/<name>.md``. Falls through to the user-global
+    directory only when ``kind in USER_GLOBAL_OVERLAY_KINDS``. Returns
+    the **deepest** existing file (highest precedence), or ``None`` if
+    no layer carries the overlay.
+
+    ``name`` is treated as a basename — no path traversal, no
+    subdirectories. Callers that need nested layouts should encode the
+    structure inside the overlay file, not the filename.
+    """
+    if kind not in CASCADE_ELIGIBLE_KINDS:
+        raise ValueError(
+            f"agents_overlay: kind {kind!r} not cascade-eligible "
+            f"(allowed: {sorted(CASCADE_ELIGIBLE_KINDS)})",
+        )
+
+    # Candidate layers, shallowest → deepest. Last match wins.
+    candidates: list[Path] = []
+
+    if kind in USER_GLOBAL_OVERLAY_KINDS:
+        candidates.append(USER_GLOBAL_AGENTS_DIR / kind / f"{name}.md")
+
+    root = find_project_root(cwd)
+    if root is not None:
+        cwd_resolved = cwd.resolve()
+        chain: list[Path] = []
+        cursor = cwd_resolved
+        while True:
+            chain.append(cursor)
+            if cursor == root:
+                break
+            parent = cursor.parent
+            if parent == cursor:
+                break
+            cursor = parent
+        chain.reverse()
+        for layer_dir in chain:
+            candidates.append(layer_dir / "agents" / kind / f"{name}.md")
+
+    deepest: Path | None = None
+    for candidate in candidates:
+        if candidate.is_file():
+            deepest = candidate
+    return deepest

package/scripts/_lib/pin_resolver.py

@@ -0,0 +1,152 @@
+"""Pin-aware version resolver for the ``agent-config`` dispatcher.
+
+Phase 3 of road-to-portable-runtime-and-update-check (P3.2). The
+dispatcher consults this module **before** doing any work. If
+``.agent-settings.yml`` carries a non-empty ``agent_config_version``
+pin and the currently running package version does not match, the
+process re-execs via ``npx @event4u/agent-config@<pin> <argv>``.
+
+Determinism is the goal: a consumer's ``npx`` cache may resolve to a
+different version than the project pinned to, and the resolver
+guarantees the pinned version is the one that actually runs.
+
+Escape hatch: ``AGENT_CONFIG_NO_PIN_REEXEC=1`` disables the re-exec
+entirely (used for local development of the package itself and for
+the recursion guard described below).
+
+Recursion guard: the parent sets ``AGENT_CONFIG_PIN_REEXEC_DEPTH=1``
+on the child env so the re-exec'd child does not loop if the freshly
+spawned ``npx`` resolves to a still-mismatched version. One re-exec
+per process, full stop.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Optional
+
+PACKAGE_NAME = "@event4u/agent-config"
+PIN_KEY = "agent_config_version"
+NO_REEXEC_ENV = "AGENT_CONFIG_NO_PIN_REEXEC"
+REEXEC_DEPTH_ENV = "AGENT_CONFIG_PIN_REEXEC_DEPTH"
+
+
+def _normalize(version: str) -> str:
+    return version.strip().lstrip("v")
+
+
+def read_pin(cwd: Path, *, settings_loader=None) -> Optional[str]:
+    """Return the pinned version from the cascaded settings, or ``None``.
+
+    Empty string and missing key both yield ``None``.
+    """
+    if settings_loader is None:
+        from scripts._lib import agent_settings  # local import (test override)
+
+        settings_loader = agent_settings.load_agent_settings
+
+    try:
+        settings = settings_loader(cwd=cwd)
+    except Exception:
+        return None
+    raw = settings.get(PIN_KEY)
+    if not isinstance(raw, str):
+        return None
+    pin = raw.strip()
+    return pin or None
+
+
+def should_reexec(
+    pin: Optional[str],
+    installed: str,
+    *,
+    env: Optional[dict] = None,
+) -> bool:
+    """Pure predicate: do we need to re-exec under the pinned version?"""
+    env = env if env is not None else os.environ
+    if env.get(NO_REEXEC_ENV) == "1":
+        return False
+    if env.get(REEXEC_DEPTH_ENV) == "1":
+        return False
+    if not pin:
+        return False
+    if not installed:
+        return False
+    return _normalize(pin) != _normalize(installed)
+
+
+def build_reexec_argv(pin: str, argv: list[str]) -> list[str]:
+    """Build the ``npx`` argv that re-execs at the pinned version."""
+    return ["npx", "--yes", f"{PACKAGE_NAME}@{_normalize(pin)}", *argv]
+
+
+def maybe_reexec(
+    installed: str,
+    *,
+    cwd: Optional[Path] = None,
+    argv: Optional[list[str]] = None,
+    env: Optional[dict] = None,
+    runner=None,
+) -> Optional[int]:
+    """Re-exec at the pinned version if needed; return the child exit code.
+
+    Returns ``None`` when no re-exec is performed (caller continues).
+    The injected ``runner`` covers the test path — defaults to
+    :func:`os.execvpe` on real invocations.
+    """
+    cwd = cwd or Path.cwd()
+    argv = argv if argv is not None else sys.argv
+    env = env if env is not None else os.environ
+
+    pin = read_pin(cwd)
+    if not should_reexec(pin, installed, env=env):
+        return None
+
+    assert pin is not None  # narrowed by should_reexec
+    npx = shutil.which("npx")
+    if not npx:
+        # Cannot re-exec without npx — silently fall back to running
+        # the locally-installed version. Better to do something than
+        # to die because of a missing CLI.
+        return None
+
+    new_argv = build_reexec_argv(pin, argv[1:] if argv else [])
+    child_env = dict(env)
+    child_env[REEXEC_DEPTH_ENV] = "1"
+
+    if runner is None:
+        # Replace the current process; never returns on success.
+        os.execvpe(npx, new_argv, child_env)
+        return 1  # unreachable on POSIX
+    return runner(npx, new_argv, child_env)
+
+
+def _parse_cli(argv: list[str]) -> tuple[Path, str, list[str]]:
+    """Parse the dispatcher-facing argv: ``--cwd X --installed Y -- ARGS``."""
+    cwd = Path.cwd()
+    installed = ""
+    forward: list[str] = []
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+        if token == "--cwd" and i + 1 < len(argv):
+            cwd = Path(argv[i + 1])
+            i += 2
+        elif token == "--installed" and i + 1 < len(argv):
+            installed = argv[i + 1]
+            i += 2
+        elif token == "--":
+            forward = argv[i + 1:]
+            break
+        else:
+            i += 1
+    return cwd, installed, forward
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cwd, installed, forward = _parse_cli(sys.argv[1:])
+    # Build the argv the child should see: ``agent-config <forward...>``.
+    child_argv = ["agent-config", *forward]
+    maybe_reexec(installed, cwd=cwd, argv=child_argv)