fix(install): find a usable python instead of dead-ending on PATH's

The macOS install harness caught this on its first real run: a throwaway
account gets `bot-bottle install: error: python3 3.11 or newer is required`
and stops. A fresh account's PATH is just /etc/paths, which excludes
/opt/homebrew/bin, so `python3` resolves to the Command Line Tools stub —
still 3.9.6 on macOS 26. Homebrew's shellenv line lives in the *installing*
user's ~/.zprofile and is inherited by nobody. The documented `curl … | sh`
path therefore dead-ends for anyone whose profile isn't already set up, which
is every new user, launchd job, and CI runner.

So look past PATH before giving up: try `python3`, then python3.11-3.14, then
/opt/homebrew/bin, /usr/local/bin, ~/.local/bin, and python.org framework
builds, and say which one was picked when it isn't the obvious one. On this
host that turns the failure into a successful install.

The chosen interpreter is now threaded through everything downstream — the pip
probe, the PEP 668 check, the pip --user fallback, and the user-scripts-dir
lookup — which were all still hardcoding `python3` and would otherwise have
run against the 3.9 stub we just rejected. `pipx install` gains `--python`,
since pipx otherwise builds the venv with whichever interpreter pipx itself
was installed with, not the one that passed the version check.

When nothing usable is found the error is now actionable: what was found and
why it's insufficient, where else it looked, a platform-appropriate install
command, and BOT_BOTTLE_PYTHON to point at an interpreter directly. An
explicit BOT_BOTTLE_PYTHON that is too old or unusable is an error rather than
a silent fallback to a different interpreter than the caller asked for.

Three existing tests asserted on incidental literals rather than the behaviour
they describe, and are narrowed to their actual intent:

* `never_uses_sudo` matched the word anywhere, including the new "sudo apt
  install python3.12" remediation *advice*. It now strips string literals and
  comments first, so it still catches sudo as a bare command, in a pipeline,
  and in a command substitution — verified by mutation — while allowing the
  script to print the word.
* `checks_pip_usable_before_fallback` pinned the literal `python3 -m pip`.
* `resolves_user_scripts_dir_not_hardcoded` banned ".local/bin" script-wide;
  it's now scoped to the USER_SCRIPTS assignment it exists to guard, since
  ~/.local/bin is a legitimate place to *find an interpreter*.

README grows the install command and a Requirements section it never had,
leading with the Python floor and why a working `python3` in your own shell
says nothing about what a fresh account sees.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WEfZZhakx13bxTfXcZCoS5

tests/unit/test_install_script.py

@@ -9,6 +9,7 @@ create the config tree, install the package, and verify with `doctor`.
 from __future__ import annotations
 
 import os
+import re
 import sysconfig
 import unittest
 from pathlib import Path
@@ -17,6 +18,22 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 INSTALL_SH = REPO_ROOT / "install.sh"
 
 
+def code_only(text: str) -> str:
+    """Script text with string literals and comments removed.
+
+    Both are places the script *talks about* commands rather than running
+    them — remediation advice quite reasonably says "sudo apt install …" —
+    so assertions about what the script actually executes must not see them.
+    Strings are stripped before comments because a '#' inside a quoted string
+    is not a comment, and several literals here span multiple lines.
+    """
+    without_strings = re.sub(r"\"(?:[^\"\\]|\\.)*\"|'[^']*'", "", text)
+    return "\n".join(
+        ln for ln in without_strings.splitlines()
+        if ln.strip() and not ln.lstrip().startswith("#")
+    )
+
+
 class TestInstallScript(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
@@ -32,12 +49,9 @@ class TestInstallScript(unittest.TestCase):
         self.assertIn("set -eu", self.text)
 
     def test_never_uses_sudo(self):
-        # Only executable lines matter; the header comment may mention sudo.
-        code = [
-            ln for ln in self.text.splitlines()
-            if ln.strip() and not ln.lstrip().startswith("#")
-        ]
-        self.assertNotIn("sudo", "\n".join(code))
+        # The installer must never *invoke* sudo. It may print it: the "no
+        # usable python" error suggests 'sudo apt install python3.12'.
+        self.assertNotIn("sudo", code_only(self.text))
 
     def test_creates_config_tree(self):
         self.assertIn(".bot-bottle/agents", self.text)
@@ -61,7 +75,9 @@ class TestInstallScript(unittest.TestCase):
         self.assertIn("git+*|*.git", self.text)
 
     def test_checks_pip_usable_before_fallback(self):
-        self.assertIn("python3 -m pip --version", self.text)
+        # Against the discovered interpreter, which is not necessarily the
+        # `python3` on PATH — hence no literal command name here.
+        self.assertIn("-m pip --version", self.text)
 
     def test_detects_externally_managed_python(self):
         # PEP 668: 'pip install --user' is blocked on externally-managed
@@ -75,12 +91,35 @@ class TestInstallScript(unittest.TestCase):
         # hardcoding Linux's ~/.local/bin (which is wrong on macOS python.org).
         self.assertIn("get_preferred_scheme", self.text)
         self.assertIn("sysconfig", self.text)
-        # No hardcoded Linux path in executable lines (a comment may mention it).
-        code = "\n".join(
-            ln for ln in self.text.splitlines()
-            if ln.strip() and not ln.lstrip().startswith("#")
-        )
-        self.assertNotIn(".local/bin", code)
+        # ~/.local/bin appears legitimately elsewhere — it's one of the places
+        # the interpreter search looks. What must never happen is USER_SCRIPTS
+        # itself being hardcoded to it.
+        for line in code_only(self.text).splitlines():
+            if "USER_SCRIPTS" in line:
+                self.assertNotIn(".local/bin", line)
+
+    def test_searches_beyond_path_for_an_interpreter(self):
+        # `python3` on PATH is the *oldest* interpreter on a stock Mac: a fresh
+        # account's PATH is /etc/paths, so python3 is the 3.9.6 CLT stub while
+        # the usable build sits somewhere only a shell profile puts on PATH.
+        # Giving up at that point dead-ends every new macOS user.
+        for candidate in ("python3.11", "/opt/homebrew/bin", "Python.framework"):
+            self.assertIn(candidate, self.text)
+
+    def test_interpreter_is_overridable(self):
+        self.assertIn("BOT_BOTTLE_PYTHON", self.text)
+
+    def test_pipx_is_pinned_to_the_vetted_interpreter(self):
+        # Without --python, pipx builds the venv with whichever interpreter
+        # pipx itself was installed with, which need not be the one that
+        # passed the version check.
+        self.assertIn("pipx install --python", self.text)
+
+    def test_version_failure_is_actionable(self):
+        # The failure a new macOS user actually hits must say what to do about
+        # it, not just state the requirement.
+        self.assertIn("brew install python@", self.text)
+        self.assertIn("BOT_BOTTLE_PYTHON=/path/to/python3", self.text)
 
     def test_macos_user_scheme_is_not_dot_local_bin(self):
         # The case the fix exists for: a python.org macOS interpreter uses the