feat(backup): add verified opt-in iCloud leg

launchd/com.brainlayer.jsonl-backup.plist

@@ -10,8 +10,9 @@
 	</array>
 	<key>ProgramArguments</key>
 	<array>
-		<string>/usr/bin/env</string>
-		<string>python3</string>
+		<!-- Rendered through hook_python.resolve_hook_python so ARM and Intel Homebrew
+		     prefixes both use the keg interpreter and never resolve Python through PATH. -->
+		<string>__BRAINLAYER_PYTHON__</string>
 		<string>-m</string>
 		<string>brainlayer.jsonl_backup</string>
 	</array>
@@ -30,8 +31,6 @@
 	<dict>
 		<key>PATH</key>
 		<string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:__HOME__/.local/bin</string>
-		<key>PYTHONPATH</key>
-		<string>__BRAINLAYER_DIR__/src</string>
 		<key>BRAINLAYER_BACKUP_TIMEOUT_SECONDS</key>
 		<string>1800</string>
 		<key>BRAINLAYER_JSONL_BACKUP_DRIVE_FOLDER</key>

scripts/launchd/install.sh

@@ -138,11 +138,45 @@ fi
 # PATH happens to front. On the M4 that is the framework Python's `brainlayer`, and installing from a
 # source checkout fronts `~/Gits/brainlayer/.venv/bin/brainlayer` -- neither of which any release moves.
 BRAINLAYER_BIN="$(stable_brainlayer_path "${BRAINLAYER_BIN:-${BRAINLAYER_KEG_CLI:-$(which brainlayer 2>/dev/null || echo "$HOME/.local/bin/brainlayer")}}")"
+# Capture only caller intent before PYTHON_BIN receives its legacy PATH fallback.
+BRAINLAYER_PYTHON_REQUESTED="${BRAINLAYER_PYTHON:-}"
 # In a keg, an unset PYTHON_BIN must NOT fall through to `command -v python3`: on a Mac whose PATH
 # puts /Library/Frameworks/Python.framework first, that renders a framework interpreter that never
 # sees the keg's site-packages, and no release can move it. An explicit override still wins.
 PYTHON_BIN="$(stable_brainlayer_path "${PYTHON_BIN:-${BRAINLAYER_KEG_PYTHON:-$(command -v python3)}}")"
+# The backup wrappers import BrainLayer itself, so a source install must not inherit
+# `command -v python3`: on the M4 that is the framework interpreter whose global
+# .pth injects the mutable root checkout. Explicit overrides remain explicit; a keg
+# uses its stable opt/ path; otherwise reuse hook_python's ARM/Intel-aware resolver
+# and fail closed when neither Homebrew prefix exists.
 BRAINLAYER_PYTHON="$(stable_brainlayer_path "${BRAINLAYER_PYTHON:-$PYTHON_BIN}")"
+
+resolve_jsonl_backup_python() {
+    if [ -n "$BRAINLAYER_KEG_PYTHON" ] && [ -z "$BRAINLAYER_PYTHON_REQUESTED" ] && [ -z "${BRAINLAYER_HOOK_PYTHON:-}" ]; then
+        BRAINLAYER_PYTHON="$(stable_brainlayer_path "$BRAINLAYER_KEG_PYTHON")"
+        return 0
+    fi
+
+    HOOK_PYTHON_RESOLVER="$BRAINLAYER_DIR/src/brainlayer/hook_python.py"
+    if [ ! -f "$HOOK_PYTHON_RESOLVER" ]; then
+        HOOK_PYTHON_RESOLVER="$BRAINLAYER_DIR/brainlayer/hook_python.py"
+    fi
+    if [ ! -f "$HOOK_PYTHON_RESOLVER" ]; then
+        echo "ERROR: hook_python.py not found; refusing a PATH-derived BrainLayer interpreter" >&2
+        return 1
+    fi
+
+    # `python hook_python.py` would put brainlayer/ itself on sys.path, where
+    # brainlayer/types.py shadows the stdlib `types` module under Apple's Python.
+    # run_path keeps the resolver executable as a standalone stdlib-only script
+    # without adding its package directory to import resolution.
+    if [ -n "$BRAINLAYER_PYTHON_REQUESTED" ]; then
+        BRAINLAYER_PYTHON="$(BRAINLAYER_HOOK_PYTHON="$BRAINLAYER_PYTHON_REQUESTED" /usr/bin/python3 -c 'import runpy, sys; path = sys.argv.pop(1); runpy.run_path(path, run_name="__main__")' "$HOOK_PYTHON_RESOLVER" --print-interpreter)" || return 1
+    else
+        BRAINLAYER_PYTHON="$(/usr/bin/python3 -c 'import runpy, sys; path = sys.argv.pop(1); runpy.run_path(path, run_name="__main__")' "$HOOK_PYTHON_RESOLVER" --print-interpreter)" || return 1
+    fi
+    BRAINLAYER_PYTHON="$(stable_brainlayer_path "$BRAINLAYER_PYTHON")"
+}
 BRAINLAYER_ENV_FILE="${BRAINLAYER_ENV_FILE:-$HOME/.config/brainlayer/brainlayer.env}"
 BRAINLAYER_ENV_RUN="$BRAINLAYER_LIB_DIR/brainlayer-env-run.sh"
 TIER0_WATCHDOG_DST="$BRAINLAYER_LIB_DIR/tier0-watchdog.sh"
@@ -622,14 +656,21 @@ install_plist() {
         verify_gemini_env_file || return 1
     fi
 
+    # XML-escape the interpreter path, then escape sed replacement metacharacters.
+    # `&` is legal in a filename but means "the matched placeholder" to sed.
+    local brainlayer_python_xml
+    local brainlayer_python_sed
+    brainlayer_python_xml="$(printf '%s' "$BRAINLAYER_PYTHON" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g')" || return 1
+    brainlayer_python_sed="$(printf '%s' "$brainlayer_python_xml" | sed -e 's/[\\&|]/\\&/g')" || return 1
+
     # Replace placeholders
     sed \
         -e "s|__HOME__|$HOME|g" \
         -e "s|__BRAINLAYER_BIN__|$BRAINLAYER_BIN|g" \
         -e "s|__BRAINLAYER_DIR__|$BRAINLAYER_DIR|g" \
         -e "s|__BRAINLAYER_LAUNCHD_DIR__|$BRAINLAYER_LAUNCHD_DIR|g" \
         -e "s|__PYTHON_BIN__|$PYTHON_BIN|g" \
-        -e "s|__BRAINLAYER_PYTHON__|$BRAINLAYER_PYTHON|g" \
+        -e "s|__BRAINLAYER_PYTHON__|$brainlayer_python_sed|g" \
         -e "s|__REPO_ROOT__|$BRAINLAYER_DIR|g" \
         -e "s|__BRAINLAYER_ENV_FILE__|$BRAINLAYER_ENV_FILE|g" \
         -e "s|__BRAINLAYER_ENV_RUN__|$BRAINLAYER_ENV_RUN|g" \
@@ -692,6 +733,8 @@ install_jsonl_backup_script() {
         return 1
     fi
 
+    resolve_jsonl_backup_python || return 1
+
     escaped_brainlayer_dir="$(printf '%s' "$BRAINLAYER_DIR" | sed 's/[\\&|]/\\&/g')" || return 1
     sed \
         -e "s|__BRAINLAYER_DIR_VALUE__|$escaped_brainlayer_dir|g" \

scripts/launchd/jsonl-backup.sh

@@ -5,10 +5,7 @@ export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:$HOME/.local/bin"
 export PYTHONUNBUFFERED=1
 : "${BRAINLAYER_BACKUP_TIMEOUT_SECONDS:=1800}"
 export BRAINLAYER_BACKUP_TIMEOUT_SECONDS
-BRAINLAYER_DIR="${BRAINLAYER_DIR:-__BRAINLAYER_DIR_VALUE__}"
-case "$BRAINLAYER_DIR" in
-    __BRAINLAYER_DIR_*) BRAINLAYER_DIR="$HOME/Gits/brainlayer" ;;
-esac
-export PYTHONPATH="$BRAINLAYER_DIR/src${PYTHONPATH:+:$PYTHONPATH}"
+: "${BRAINLAYER_PYTHON:?installer must render the prefix-aware keg interpreter}"
+unset PYTHONPATH
 
-exec "${BRAINLAYER_PYTHON:-python3}" -m brainlayer.jsonl_backup
+exec "$BRAINLAYER_PYTHON" -m brainlayer.jsonl_backup

src/brainlayer/hook_python.py

@@ -23,6 +23,7 @@
 import shlex
 from dataclasses import dataclass
 from typing import Iterable, Iterator, Mapping, Sequence
+from xml.sax.saxutils import escape
 
 __all__ = [
     "BRAINLAYER_HOOK_SCRIPTS",
@@ -36,6 +37,7 @@
     "is_system_python",
     "main",
     "render_hook_command",
+    "render_launchd_plist",
     "resolve_hook_python",
     "shebang_of",
 ]
@@ -54,6 +56,8 @@
     "/usr/local/opt/brainlayer/libexec/venv/bin/python",
 )
 
+_XML_10_FORBIDDEN = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]")
+
 #: Hook scripts this repo owns. The settings.json lint matches on these basenames so
 #: it never touches a hook belonging to another repo. `tests/test_hook_python.py`
 #: asserts every shebang-bearing file under `hooks/` appears here.
@@ -115,7 +119,10 @@ def _tokens(value: str | None) -> list[str]:
     token = value.strip()
     if token.startswith("#!"):
         token = token[2:].strip()
-    return token.split()
+    try:
+        return shlex.split(token)
+    except ValueError:
+        return []
 
 
 def is_bare_python3(value: str | None) -> bool:
@@ -245,10 +252,16 @@ def resolve_hook_python(
                 "substitute another interpreter for an override that was set on purpose — "
                 f"fix the path or unset {HOOK_PYTHON_ENV} to use the keg."
             )
+        if (
+            not is_pinned_interpreter(shlex.quote(override))
+            or not os.path.isfile(override)
+            or not os.access(override, os.X_OK)
+        ):
+            raise HookPythonUnresolved(f"{HOOK_PYTHON_ENV}={override!r} is not an executable Python interpreter")
         return override
 
     for candidate in candidates:
-        if os.path.exists(candidate):
+        if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
             return candidate
         looked_at.append(candidate)
 
@@ -271,6 +284,30 @@ def render_hook_command(
     return f"{shlex.quote(interpreter) if ' ' in interpreter else interpreter} {script_path}"
 
 
+def render_launchd_plist(
+    template: str,
+    *,
+    python: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> str:
+    """Render the prefix-aware keg interpreter into a launchd template.
+
+    Templates stay portable across ARM and Intel Homebrew prefixes. Resolution
+    uses the same fail-closed candidate order and override rules as hook command
+    rendering; a caller-supplied interpreter is accepted only when the existing
+    affirmative pin gate can vouch for it.
+    """
+    interpreter = python or resolve_hook_python(env=env)
+    if (
+        not is_pinned_interpreter(shlex.quote(interpreter))
+        or not os.path.isfile(interpreter)
+        or not os.access(interpreter, os.X_OK)
+        or _XML_10_FORBIDDEN.search(interpreter)
+    ):
+        raise HookPythonUnresolved(f"launchd interpreter is not explicitly pinned: {interpreter!r}")
+    return template.replace("__BRAINLAYER_PYTHON__", escape(interpreter))
+
+
 def _iter_hook_entries(settings: Mapping) -> Iterator[tuple[str, str]]:
     """Yield `(event, command)` for every command hook configured in `settings`."""
     hooks = settings.get("hooks") if isinstance(settings, Mapping) else None
@@ -381,16 +418,22 @@ def _why_unpinned(interpreter: str) -> str:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    """`python -m brainlayer.hook_python [settings.json]` — lint a settings file.
+    """Lint settings, or print the prefix-aware interpreter for installers.
 
     Exits 0 when every BrainLayer hook names its interpreter, 1 when any is
     PATH-resolved, 2 when the file cannot be read. Hooks owned by other repos are
     never reported.
     """
     import argparse
     import json
+    import sys
 
     parser = argparse.ArgumentParser(prog="brainlayer.hook_python")
+    parser.add_argument(
+        "--print-interpreter",
+        action="store_true",
+        help="print the affirmative prefix-aware interpreter and exit",
+    )
     parser.add_argument(
         "settings",
         nargs="?",
@@ -399,6 +442,14 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
     args = parser.parse_args(argv)
 
+    if args.print_interpreter:
+        try:
+            print(resolve_hook_python())
+        except HookPythonUnresolved as exc:
+            print(f"cannot resolve BrainLayer interpreter: {exc}", file=sys.stderr, flush=True)
+            return 2
+        return 0
+
     try:
         with open(args.settings, encoding="utf-8") as handle:
             settings = json.load(handle)