fix(launcher): bind installed app to repository runtime

Author: codex

scripts/AuraLauncher.swift

@@ -2161,7 +2161,7 @@ final class AuraLauncherDelegate: NSObject, NSApplicationDelegate,
 
         launchScript = auraRoot.appendingPathComponent("launch_aura.sh")
         auraMainScript = auraRoot.appendingPathComponent("aura_main.py")
-        pythonExecutable = try resolvePythonExecutable()
+        pythonExecutable = try resolvePythonExecutable(resourcesURL: resourcesURL)
 
         let semverFile = resourcesURL.appendingPathComponent("aura-version")
         if let text = try? String(contentsOf: semverFile, encoding: .utf8) {
@@ -2643,21 +2643,24 @@ final class AuraLauncherDelegate: NSObject, NSApplicationDelegate,
         ])
     }
 
-    private func resolvePythonExecutable() throws -> URL {
-        let candidates = [
-            auraRoot.appendingPathComponent(".venv/bin/python3"),
-            URL(fileURLWithPath: "/opt/homebrew/bin/python3.12"),
-            URL(fileURLWithPath: "/usr/local/bin/python3.12"),
-            URL(fileURLWithPath: "/Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12"),
-        ]
-
-        for candidate in candidates where fileManager.isExecutableFile(atPath: candidate.path) {
-            return candidate
+    private func resolvePythonExecutable(resourcesURL: URL) throws -> URL {
+        let runtimePathFile = resourcesURL.appendingPathComponent("aura-python-path")
+        guard let runtimePath = try? String(contentsOf: runtimePathFile, encoding: .utf8)
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+              !runtimePath.isEmpty else {
+            throw NSError(domain: "AuraLauncher", code: 5, userInfo: [
+                NSLocalizedDescriptionKey: "Aura.app has no signed repository Python path. Rebuild the installed app.",
+            ])
         }
-
-        throw NSError(domain: "AuraLauncher", code: 5, userInfo: [
-            NSLocalizedDescriptionKey: "Aura needs a Python 3.12 runtime, but the launcher could not find one.",
-        ])
+        let candidate = URL(fileURLWithPath: runtimePath)
+            .resolvingSymlinksInPath()
+            .standardizedFileURL
+        guard fileManager.isExecutableFile(atPath: candidate.path) else {
+            throw NSError(domain: "AuraLauncher", code: 5, userInfo: [
+                NSLocalizedDescriptionKey: "Aura's signed repository Python runtime is unavailable. Restore the repo environment or rebuild the installed app.",
+            ])
+        }
+        return candidate
     }
 
     private func baseAuraEnvironment() -> [String: String] {

scripts/bundle_app.sh

@@ -85,6 +85,7 @@ EXECUTABLE_NAME="aura-launcher"
 EXECUTABLE_PATH="${MACOS_DIR}/${EXECUTABLE_NAME}"
 ICON_SOURCE="${ROOT_DIR}/aura_icon.icns"
 ROOT_PATH_FALLBACK="${RESOURCES_DIR}/aura-root-path"
+PYTHON_RUNTIME_FILE="${RESOURCES_DIR}/aura-python-path"
 VERSION_FILE="${RESOURCES_DIR}/aura-version"
 VERSION_FULL_FILE="${RESOURCES_DIR}/aura-version-full"
 PROVENANCE_FILE="${RESOURCES_DIR}/aura-launch-provenance.json"
@@ -98,8 +99,41 @@ cd "${ROOT_DIR}"
 
 echo "📦 Building ${APP_NAME} (live source mode)..."
 
-if [ -x "${ROOT_DIR}/.venv/bin/python3" ] && [ -f "${ROOT_DIR}/scripts/build_launcher_icon.py" ]; then
-    "${ROOT_DIR}/.venv/bin/python3" "${ROOT_DIR}/scripts/build_launcher_icon.py" >/dev/null
+PRIMARY_ROOT=""
+GIT_COMMON_DIR="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || true)"
+if [ -n "${GIT_COMMON_DIR}" ] && [ "$(basename "${GIT_COMMON_DIR}")" = ".git" ]; then
+    PRIMARY_ROOT="$(dirname "${GIT_COMMON_DIR}")"
+fi
+
+PYTHON_RUNTIME=""
+PYTHON_CANDIDATES=(
+    "${AURA_PYTHON_RUNTIME:-}"
+    "${ROOT_DIR}/.venv/bin/python3"
+    "${ROOT_DIR}/.venv/bin/python"
+)
+if [ -n "${PRIMARY_ROOT}" ]; then
+    PYTHON_CANDIDATES+=(
+        "${PRIMARY_ROOT}/.venv/bin/python3"
+        "${PRIMARY_ROOT}/.venv/bin/python"
+    )
+fi
+for candidate in "${PYTHON_CANDIDATES[@]}"; do
+    if [ -z "${candidate}" ] || [ ! -x "${candidate}" ]; then
+        continue
+    fi
+    if "${candidate}" -c 'import sys, httpx; raise SystemExit(0 if sys.version_info[:2] == (3, 12) else 1)' >/dev/null 2>&1; then
+        PYTHON_RUNTIME="$("${candidate}" -c 'import sys; print(sys.executable)')"
+        break
+    fi
+done
+if [ -z "${PYTHON_RUNTIME}" ]; then
+    echo "❌ Aura needs the repository Python 3.12 environment with runtime dependencies installed." >&2
+    echo "   Expected .venv under ${ROOT_DIR}${PRIMARY_ROOT:+ or ${PRIMARY_ROOT}}." >&2
+    exit 1
+fi
+
+if [ -f "${ROOT_DIR}/scripts/build_launcher_icon.py" ]; then
+    "${PYTHON_RUNTIME}" "${ROOT_DIR}/scripts/build_launcher_icon.py" >/dev/null
 fi
 
 if [ ! -f "${LAUNCHER_SOURCE}" ]; then
@@ -128,16 +162,10 @@ rm -rf "${APP_DIR}"
 mkdir -p "${MACOS_DIR}" "${RESOURCES_DIR}"
 
 printf '%s\n' "${ROOT_DIR}" > "${ROOT_PATH_FALLBACK}"
+printf '%s\n' "${PYTHON_RUNTIME}" > "${PYTHON_RUNTIME_FILE}"
 cp "${SCREEN_CAPTURE_POLICY_SOURCE}" "${SCREEN_CAPTURE_POLICY_RESOURCE}"
 
-PYTHON_FOR_VERSION="${ROOT_DIR}/.venv/bin/python3"
-if [ ! -x "${PYTHON_FOR_VERSION}" ]; then
-    PYTHON_FOR_VERSION="$(command -v python3 || true)"
-fi
-if [ -z "${PYTHON_FOR_VERSION}" ]; then
-    echo "❌ python3 is required to write Aura.app metadata."
-    exit 1
-fi
+PYTHON_FOR_VERSION="${PYTHON_RUNTIME}"
 
 APP_SEMVER="2026.3.31"
 APP_FULL_VERSION="Aura Luna v${APP_SEMVER}"

tests/test_launcher_polish_contract.py

@@ -249,6 +249,25 @@ def test_bundle_app_prefers_stable_local_codesign_without_timestamp_by_default()
     assert 'CODESIGN_ARGS+=(--timestamp)' in bundle
 
 
+def test_installed_launcher_binds_the_repository_python_across_worktrees():
+    bundle = (PROJECT_ROOT / "scripts" / "bundle_app.sh").read_text(encoding="utf-8")
+    swift = (PROJECT_ROOT / "scripts" / "AuraLauncher.swift").read_text(encoding="utf-8")
+
+    assert 'PYTHON_RUNTIME_FILE="${RESOURCES_DIR}/aura-python-path"' in bundle
+    assert "git rev-parse --path-format=absolute --git-common-dir" in bundle
+    assert '"${PRIMARY_ROOT}/.venv/bin/python3"' in bundle
+    assert "import sys, httpx" in bundle
+    assert 'printf \'%s\\n\' "${PYTHON_RUNTIME}" > "${PYTHON_RUNTIME_FILE}"' in bundle
+    assert "resolvePythonExecutable(resourcesURL: resourcesURL)" in swift
+    resolver = swift.split(
+        "private func resolvePythonExecutable(resourcesURL: URL) throws -> URL {",
+        1,
+    )[1].split("private func baseAuraEnvironment()", 1)[0]
+    assert 'appendingPathComponent("aura-python-path")' in resolver
+    assert "/opt/homebrew/bin/python3.12" not in resolver
+    assert "/usr/local/bin/python3.12" not in resolver
+
+
 def test_launcher_cleanup_shim_exists_at_repo_root():
     shim = PROJECT_ROOT / "aura_cleanup.py"
     target = PROJECT_ROOT / "scripts" / "one_off" / "aura_cleanup.py"