@event4u/agent-config 1.41.1 → 2.0.0

package/scripts/_lib/update_check.py

@@ -0,0 +1,183 @@
+"""Daily update-check banner for the ``agent-config`` dispatcher.
+
+Phase 2 of road-to-portable-runtime-and-update-check. Pure functions:
+``check_for_update()`` decides whether a banner should be emitted and
+returns the banner string (or ``None``). The dispatcher prints the
+returned string to ``stderr`` after the subcommand finishes — never
+delaying the work, never prompting.
+
+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``.
+- 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``.
+
+The dispatcher is the only call site. Tests mock ``now``, the state
+path, and ``fetch_latest_from_npm`` to cover every branch.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+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"
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def fetch_latest_from_npm(
+    *,
+    timeout: float = FETCH_TIMEOUT_S,
+    url: str = NPM_REGISTRY_URL,
+) -> Optional[str]:
+    """Return the ``latest`` dist-tag version, or ``None`` on any failure.
+
+    Hard 1 s timeout. Any exception (network, JSON, missing key) yields
+    ``None`` — the update check is best-effort.
+    """
+    try:
+        req = urllib.request.Request(
+            url,
+            headers={"Accept": "application/json", "User-Agent": "agent-config-update-check"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 — fixed URL
+            payload = json.load(resp)
+        version = payload.get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    except (urllib.error.URLError, TimeoutError, ValueError, OSError, json.JSONDecodeError):
+        return None
+    return None
+
+
+def _read_state(path: Path) -> dict:
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+        if isinstance(data, dict):
+            return data
+    except (OSError, ValueError, json.JSONDecodeError):
+        pass
+    return {}
+
+
+def _write_state(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=".update-check-", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2, sort_keys=True)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _should_check(state: dict, now: datetime) -> bool:
+    last = state.get("last_check_utc")
+    if not isinstance(last, str):
+        return True
+    try:
+        last_dt = datetime.fromisoformat(last.replace("Z", "+00:00"))
+    except ValueError:
+        return True
+    if last_dt.tzinfo is None:
+        last_dt = last_dt.replace(tzinfo=timezone.utc)
+    return (now - last_dt) >= CHECK_WINDOW
+
+
+def _format_banner(latest: str, installed: str) -> str:
+    return (
+        f"ℹ️  agent-config {latest} available (you have {installed}).\n"
+        f"    Update: npx {PACKAGE_NAME} update"
+    )
+
+
+def _is_newer(latest: str, installed: str) -> bool:
+    def _parse(v: str) -> tuple:
+        parts = v.lstrip("v").split("-", 1)[0].split(".")
+        out = []
+        for p in parts[:3]:
+            try:
+                out.append(int(p))
+            except ValueError:
+                out.append(0)
+        while len(out) < 3:
+            out.append(0)
+        return tuple(out)
+
+    return _parse(latest) > _parse(installed)
+
+
+def check_for_update(
+    installed_version: str,
+    *,
+    now: Optional[datetime] = None,
+    state_path: Optional[Path] = None,
+    env: Optional[dict] = None,
+    is_tty: Optional[bool] = None,
+    settings_enabled: bool = True,
+    fetcher=fetch_latest_from_npm,
+) -> Optional[str]:
+    """Decide whether to show an update banner. Pure (modulo state file).
+
+    Returns the banner string or ``None``. ``None`` covers every
+    suppression branch (CI, non-TTY, opt-out, within 24 h, network
+    failure, no update available).
+    """
+    env = env if env is not None else os.environ
+    if env.get("AGENT_CONFIG_NO_UPDATE_CHECK") == "1":
+        return None
+    if env.get("CI") in {"1", "true"} or env.get("GITHUB_ACTIONS") == "true":
+        return None
+    if not settings_enabled:
+        return None
+    if is_tty is None:
+        is_tty = sys.stdout.isatty()
+    if not is_tty:
+        return None
+
+    now = now or _now_utc()
+    state_path = state_path or DEFAULT_STATE_PATH
+    state = _read_state(state_path)
+    if not _should_check(state, now):
+        latest = state.get("last_seen_version")
+        if isinstance(latest, str) and _is_newer(latest, installed_version):
+            return _format_banner(latest, installed_version)
+        return None
+
+    latest = fetcher()
+    payload = {
+        "last_check_utc": now.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "last_seen_version": latest or state.get("last_seen_version", ""),
+        "installed_version": installed_version,
+    }
+    try:
+        _write_state(state_path, payload)
+    except OSError:
+        pass
+
+    if not latest or not _is_newer(latest, installed_version):
+        return None
+    return _format_banner(latest, installed_version)

package/scripts/agent-config

@@ -94,6 +94,10 @@ Commands:
                              Usage: council:run <question> --output <path> --confirm
   council:render             Re-render a saved council responses JSON to markdown
                              Usage: council:render <responses.json>
+  update                     Update the agent_config_version pin in .agent-settings.yml
+                             Flags: --check (read-only) | --to <version> (explicit pin)
+  migrate                    One-shot migration off legacy composer / npm install paths
+                             Flags: --dry-run (detect only)
   help                       Show this help
   --version, -V              Print package version
 
@@ -504,6 +508,22 @@ cmd_council() {
   exec env PYTHONPATH="$PACKAGE_ROOT" python3 "$script" "$sub" "$@"
 }
 
+# `agent-config update` — flip the agent_config_version pin in
+# .agent-settings.yml. See scripts/_cli/cmd_update.py (P3.1 of
+# road-to-portable-runtime-and-update-check.md).
+cmd_update() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_update "$@"
+}
+
+# `agent-config migrate` — one-shot migration off legacy composer / npm
+# install paths onto the npx-only runtime. See scripts/_cli/cmd_migrate.py
+# (P3.5 of road-to-portable-runtime-and-update-check.md).
+cmd_migrate() {
+  require_python3
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._cli.cmd_migrate "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -542,6 +562,8 @@ main() {
     council:estimate)        cmd_council estimate "$@" ;;
     council:run)             cmd_council run "$@" ;;
     council:render)          cmd_council render "$@" ;;
+    update)                  cmd_update "$@" ;;
+    migrate)                 cmd_migrate "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)
@@ -552,4 +574,54 @@ main() {
   esac
 }
 
-main "$@"
+# Pre-flight pin resolver: when `.agent-settings.yml` carries a
+# non-empty `agent_config_version` that differs from the running
+# package version, re-exec via `npx @event4u/agent-config@<pin>`.
+# Skipped for `--version`, `help`, `update` and `migrate` (so consumers
+# can escape a bad pin or run the legacy-cleanup before a pin exists),
+# and when `AGENT_CONFIG_NO_PIN_REEXEC=1`. See P3.2 of
+# road-to-portable-runtime-and-update-check.md.
+maybe_pin_reexec() {
+  local cmd="${1-}"
+  case "$cmd" in
+    help|--help|-h|--version|-V|update|migrate|"") return 0 ;;
+  esac
+  if ! command -v python3 >/dev/null 2>&1; then
+    return 0
+  fi
+  local installed
+  installed="$(print_version)"
+  [[ -z "$installed" || "$installed" == "unknown" ]] && return 0
+  env PYTHONPATH="$PACKAGE_ROOT" python3 -m scripts._lib.pin_resolver \
+    --cwd "$CONSUMER_ROOT" --installed "$installed" -- "$@" || true
+}
+
+# Post-subcommand banner: best-effort daily update-check notice on
+# stderr. Runs after the dispatch returns (subshell wrapper below)
+# so the banner appears post-output and never delays the subcommand.
+# Suppressed in CI, on non-TTY stdout, by AGENT_CONFIG_NO_UPDATE_CHECK=1,
+# or by `update_check.enabled: false` in settings. See P2 of
+# road-to-portable-runtime-and-update-check.md.
+run_update_check_banner() {
+  local cmd="${1-}"
+  case "$cmd" in
+    help|--help|-h|--version|-V|"") return 0 ;;
+  esac
+  if ! command -v python3 >/dev/null 2>&1; then
+    return 0
+  fi
+  local banner_script="$PACKAGE_ROOT/scripts/check_update_banner.py"
+  [[ -f "$banner_script" ]] || return 0
+  python3 "$banner_script" --cwd "$CONSUMER_ROOT" 2>/dev/null || true
+}
+
+# Pin re-exec runs before dispatch — if it triggers, the process is
+# replaced and nothing else here matters.
+maybe_pin_reexec "$@"
+
+# Dispatch in a subshell so internal ``exec`` calls do not replace this
+# process — we still get to run the post-subcommand banner.
+( main "$@" )
+rc=$?
+run_update_check_banner "${1-}"
+exit "$rc"

package/scripts/check_overlay_cascade_subdirs.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Guard: ``CASCADE_ELIGIBLE_KINDS`` / ``USER_GLOBAL_OVERLAY_KINDS`` ↔ docs.
+
+Phase 1 of road-to-portable-runtime-and-update-check (P1.6). The
+overlay resolver in :mod:`scripts._lib.agents_overlay` ships two
+constants that gate which ``agents/<kind>/`` subdirs participate in
+the cascade and which of those may live at the user-global layer.
+The same lists are restated in
+``docs/customization.md`` § *"agents/ overlay cascade"* so consumers
+can see them without reading source.
+
+Drift between code and docs is the failure mode this guard catches.
+
+Exit codes: 0 = clean, 1 = drift detected, 3 = internal error.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+sys.path.insert(0, str(REPO_ROOT))
+
+from scripts._lib.agents_overlay import (  # noqa: E402
+    CASCADE_ELIGIBLE_KINDS,
+    USER_GLOBAL_OVERLAY_KINDS,
+)
+
+DOCS_PATH = REPO_ROOT / "docs" / "customization.md"
+
+# Match `agents/<kind>/` in the first column of the overlay table, plus
+# the ✅/❌ markers in columns 2 and 3.
+ROW_RE = re.compile(
+    r"^\|\s*`agents/([a-z][a-z0-9_-]*)/`\s*\|\s*(✅|❌)[^|]*\|\s*(✅|❌)[^|]*\|",
+)
+
+
+def _parse_doc_table(text: str) -> tuple[set[str], set[str], set[str]]:
+    """Return (all-kinds-listed, cascade-yes, user-global-yes) from the table."""
+    all_kinds: set[str] = set()
+    cascade_yes: set[str] = set()
+    user_global_yes: set[str] = set()
+    for line in text.splitlines():
+        match = ROW_RE.match(line)
+        if not match:
+            continue
+        kind, cascade_mark, user_mark = match.groups()
+        all_kinds.add(kind)
+        if cascade_mark == "✅":
+            cascade_yes.add(kind)
+        if user_mark == "✅":
+            user_global_yes.add(kind)
+    return all_kinds, cascade_yes, user_global_yes
+
+
+def main() -> int:
+    if not DOCS_PATH.is_file():
+        print(f"❌  {DOCS_PATH} not found", file=sys.stderr)
+        return 3
+    text = DOCS_PATH.read_text(encoding="utf-8")
+    _, doc_cascade, doc_user_global = _parse_doc_table(text)
+
+    errors: list[str] = []
+
+    code_cascade = set(CASCADE_ELIGIBLE_KINDS)
+    if doc_cascade != code_cascade:
+        only_code = sorted(code_cascade - doc_cascade)
+        only_doc = sorted(doc_cascade - code_cascade)
+        if only_code:
+            errors.append(
+                "CASCADE_ELIGIBLE_KINDS has entries missing from "
+                f"docs/customization.md table: {only_code}",
+            )
+        if only_doc:
+            errors.append(
+                "docs/customization.md table marks these as cascade-eligible "
+                f"but the code list does not: {only_doc}",
+            )
+
+    code_user_global = set(USER_GLOBAL_OVERLAY_KINDS)
+    if doc_user_global != code_user_global:
+        only_code = sorted(code_user_global - doc_user_global)
+        only_doc = sorted(doc_user_global - code_user_global)
+        if only_code:
+            errors.append(
+                "USER_GLOBAL_OVERLAY_KINDS has entries missing from "
+                f"docs/customization.md table: {only_code}",
+            )
+        if only_doc:
+            errors.append(
+                "docs/customization.md table marks these as user-global-eligible "
+                f"but the code list does not: {only_doc}",
+            )
+
+    # Sanity: user-global subset of cascade-eligible.
+    if not code_user_global.issubset(code_cascade):
+        errors.append(
+            "USER_GLOBAL_OVERLAY_KINDS must be a subset of "
+            f"CASCADE_ELIGIBLE_KINDS; surplus: "
+            f"{sorted(code_user_global - code_cascade)}",
+        )
+
+    if errors:
+        print("❌  agents/ overlay cascade drift detected:", file=sys.stderr)
+        for err in errors:
+            print(f"   - {err}", file=sys.stderr)
+        print(
+            "\nFix: update either scripts/_lib/agents_overlay.py "
+            "or docs/customization.md so they agree.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"✅  agents/ overlay cascade in sync · "
+        f"{len(code_cascade)} cascade-eligible, "
+        f"{len(code_user_global)} user-global-eligible",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_template_pin_drift.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Fail when ``package.json.version`` and the project-template pin drift.
+
+CI guard for P3.3 of road-to-portable-runtime-and-update-check.md.
+
+A release bump of ``package.json`` must update
+``agent_config_version`` in
+``.agent-src.uncompressed/templates/agents/agent-project-settings.example.yml``
+(and its compressed twin under ``.agent-src/``) in lockstep. Otherwise
+a fresh ``init`` on a new project would bootstrap onto a stale pin,
+and the pin-resolver would re-exec back to the older version.
+
+Exit codes:
+    0 — pin matches package.json.version (or pin is empty and the
+        ``--allow-empty`` flag is set, used for early development).
+    1 — pin missing, drift detected, or template file unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+PACKAGE_JSON = REPO_ROOT / "package.json"
+TEMPLATE_FILES = (
+    REPO_ROOT / ".agent-src.uncompressed" / "templates" / "agents" / "agent-project-settings.example.yml",
+    REPO_ROOT / ".agent-src" / "templates" / "agents" / "agent-project-settings.example.yml",
+)
+PIN_LINE_RE = re.compile(r"^\s*agent_config_version\s*:\s*\"?([^\"\s#]*)\"?")
+
+
+def _read_package_version() -> str | None:
+    try:
+        data = json.loads(PACKAGE_JSON.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+    version = data.get("version")
+    return version.strip() if isinstance(version, str) else None
+
+
+def _read_template_pin(path: Path) -> str | None:
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            match = PIN_LINE_RE.match(line)
+            if match:
+                return match.group(1).strip()
+    except OSError:
+        return None
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Fail when package.json version and template pin drift.",
+    )
+    parser.add_argument(
+        "--allow-empty",
+        action="store_true",
+        help="Accept an empty pin (used during early-stage development).",
+    )
+    args = parser.parse_args(argv)
+
+    pkg_version = _read_package_version()
+    if not pkg_version:
+        print("❌  check_template_pin_drift: failed to read package.json version.", file=sys.stderr)
+        return 1
+
+    failures: list[str] = []
+    for template in TEMPLATE_FILES:
+        if not template.is_file():
+            failures.append(f"missing template file: {template.relative_to(REPO_ROOT)}")
+            continue
+        pin = _read_template_pin(template)
+        rel = template.relative_to(REPO_ROOT)
+        if pin is None:
+            failures.append(f"{rel}: no `agent_config_version:` line found")
+            continue
+        if pin == "":
+            if not args.allow_empty:
+                failures.append(
+                    f"{rel}: agent_config_version is empty; expected {pkg_version}"
+                )
+            continue
+        if pin != pkg_version:
+            failures.append(
+                f"{rel}: agent_config_version={pin!r} does not match package.json version {pkg_version!r}"
+            )
+
+    if failures:
+        print(
+            "❌  check_template_pin_drift: template pin drift detected.",
+            file=sys.stderr,
+        )
+        for line in failures:
+            print(f"    - {line}", file=sys.stderr)
+        print(
+            "    Fix: update `agent_config_version:` in the listed template(s) to "
+            f"{pkg_version!r} before releasing.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"✅  template pin = package.json version ({pkg_version}).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_update_banner.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Thin CLI wrapper: emit the daily update-check banner to stderr.
+
+Invoked by the ``scripts/agent-config`` dispatcher **after** a
+subcommand finishes. Never raises, never exits non-zero — banner is
+best-effort. See ``scripts/_lib/update_check.py`` for the decision
+logic.
+
+Usage:
+    python3 scripts/check_update_banner.py [--installed-version X.Y.Z]
+
+When ``--installed-version`` is omitted, reads ``package.json`` next to
+the package root (``$PACKAGE_ROOT/package.json``).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from scripts._lib import agent_settings  # noqa: E402
+from scripts._lib import update_check  # noqa: E402
+
+
+def _read_installed_version(package_root: Path) -> str:
+    candidate = package_root / "package.json"
+    try:
+        data = json.loads(candidate.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 ""
+
+
+def _read_settings_flag(cwd: Path) -> bool:
+    try:
+        settings = agent_settings.load_agent_settings(cwd=cwd)
+    except Exception:
+        return True
+    block = settings.get("update_check")
+    if isinstance(block, dict) and block.get("enabled") is False:
+        return False
+    return True
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="check-update-banner", add_help=False)
+    parser.add_argument("--installed-version", default="")
+    parser.add_argument("--cwd", default=str(Path.cwd()))
+    parser.add_argument("--help", "-h", action="store_true")
+    args, _unknown = parser.parse_known_args(argv)
+    if args.help:
+        print(__doc__ or "")
+        return 0
+
+    installed = args.installed_version or _read_installed_version(ROOT)
+    if not installed:
+        return 0
+
+    try:
+        cwd = Path(args.cwd).resolve()
+    except OSError:
+        cwd = ROOT
+    enabled = _read_settings_flag(cwd)
+
+    try:
+        banner = update_check.check_for_update(
+            installed,
+            settings_enabled=enabled,
+        )
+    except Exception:
+        return 0
+
+    if banner:
+        print(banner, file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install

@@ -26,12 +26,6 @@
 #   --quiet           Suppress non-error output
 #   --skip-sync       Skip payload sync (install.sh)
 #   --skip-bridges    Skip bridge files (install.py)
-#   --global          Phase-3: ship kernel rules + curated skills to user-scope
-#                     dirs (~/.claude/, ~/.cursor/, ~/.codeium/windsurf/,
-#                     ~/.config/agent-config/) so the agent has them in every
-#                     project. Pair with --tools to scope surfaces; default = all.
-#   --uninstall       With --global: remove the event4u/ namespace dir from each
-#                     enabled surface (no effect on user-added files).
 #   --help, -h        Show this help
 #
 # Examples:
@@ -59,14 +53,12 @@ QUIET=false
 SKIP_SYNC=false
 SKIP_BRIDGES=false
 LIST_TOOLS=false
-GLOBAL_INSTALL=false
-UNINSTALL=false
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex all"
 
 show_help() {
-    sed -n '3,35p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,29p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -128,8 +120,6 @@ while [[ $# -gt 0 ]]; do
         --quiet)         QUIET=true; shift ;;
         --skip-sync)     SKIP_SYNC=true; shift ;;
         --skip-bridges)  SKIP_BRIDGES=true; shift ;;
-        --global)        GLOBAL_INSTALL=true; shift ;;
-        --uninstall)     UNINSTALL=true; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
@@ -175,16 +165,11 @@ prompt_tools() {
     echo "  ✅  Selected: $TOOLS"
 }
 
-if ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && ! $GLOBAL_INSTALL && [[ -t 0 && -t 1 ]]; then
+if ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && [[ -t 0 && -t 1 ]]; then
     prompt_tools
     TOOLS_EXPLICIT=true
 fi
 
-if $UNINSTALL && ! $GLOBAL_INSTALL; then
-    err "--uninstall is only valid combined with --global"
-    exit 1
-fi
-
 # Default = "all": backward compatible with pre-Phase-1 invocations. An
 # explicit --tools= (empty value) is rejected by validate_tools — only an
 # absent flag falls through to "all".
@@ -262,26 +247,6 @@ run_bridges() {
 
 RC=0
 
-# --global: dedicated user-scope path. Skips the project-bridge sync entirely
-# and forwards to install.py --global (Phase 3 / S13). --uninstall pairs with
-# --global to wipe the event4u/ namespace dir under each surface.
-if $GLOBAL_INSTALL; then
-    if ! python_bin="$(find_python)"; then
-        err "Python 3 not found — required for --global install"
-        exit 1
-    fi
-    if [[ ! -f "$INSTALL_PY" ]]; then
-        err "Missing $INSTALL_PY"
-        exit 1
-    fi
-    args=(--package "$SOURCE_DIR" --global --tools="$TOOLS")
-    $FORCE     && args+=(--force)
-    $QUIET     && args+=(--quiet)
-    $UNINSTALL && args+=(--uninstall)
-    "$python_bin" "$INSTALL_PY" "${args[@]}"
-    exit $?
-fi
-
 if ! $SKIP_SYNC; then
     if [[ ! -f "$INSTALL_SH" ]]; then
         err "Missing $INSTALL_SH"