From a530c83a63a64f5fa2bc30f545fa7ec183f41039 Mon Sep 17 00:00:00 2001
From: patrick <aipass.system@gmail.com>
Date: Sun, 3 May 2026 08:57:18 -0700
Subject: [PATCH] =?UTF-8?q?feat(system):=20fix(setup):=20add=20ensurepip?=
 =?UTF-8?q?=20check=20to=20prevent=20broken=20venv=20on=20Debian/Ubuntu=20?=
 =?UTF-8?q?=E2=80=94=20closes=20#495?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: @devpulse <devpulse@aipass>
---
 setup.sh                                            | 13 +++++++++++++
 src/aipass/prax/README.md                           |  3 +--
 src/aipass/spawn/README.md                          |  4 +---
 .../builder/.spawn/.template_registry.json          |  4 ++--
 src/aipass/trigger/README.md                        |  2 +-
 5 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/setup.sh b/setup.sh
index 923927ff..f279ada9 100755
--- a/setup.sh
+++ b/setup.sh
@@ -133,6 +133,19 @@ if [ "$PY_OK" != "1" ]; then
     fi
 fi
 
+# --- Check ensurepip (Debian/Ubuntu split it into python3-venv apt package) ---
+if ! $PYTHON -c 'import ensurepip' &>/dev/null 2>&1; then
+    echo ""
+    echo "FAIL: ensurepip is unavailable for $PYTHON."
+    echo "  Without it, 'python3 -m venv' creates a broken venv (no pip, no activate)."
+    echo ""
+    echo "  Debian/Ubuntu:  sudo apt install python3-venv python3-pip"
+    echo "  Fedora/RHEL:    sudo dnf install python3-pip"
+    echo "  Arch:           (included in base python — file a bug if you hit this)"
+    echo ""
+    exit 1
+fi
+
 # --- Create venv ---
 if [ "$IS_WINDOWS" -eq 1 ] && [ -f ".venv/Scripts/python.exe" ]; then
     # Windows: skip venv recreation if python.exe exists (rm -rf unreliable due to file locking)
diff --git a/src/aipass/prax/README.md b/src/aipass/prax/README.md
index 01f7cfc0..4c7ae120 100644
--- a/src/aipass/prax/README.md
+++ b/src/aipass/prax/README.md
@@ -143,8 +143,7 @@ prax/
 │       └── watcher/                   # Background system watchers
 ├── prax_json/                         # Auto-created per-module config/data/log files
 ├── templates/                         # Dashboard template schema (DASHBOARD.template.json)
-├── tests/                             # 375 tests across 16 files
-└── tools/                             # Standalone utilities (inbox_watchdog.py, verify_branch.py)
+└── tests/                             # 911 tests across 16 files
 ```
 
 ### Design Pattern
diff --git a/src/aipass/spawn/README.md b/src/aipass/spawn/README.md
index ba507bd8..0f9c3d2d 100644
--- a/src/aipass/spawn/README.md
+++ b/src/aipass/spawn/README.md
@@ -139,9 +139,7 @@ spawn/
 │           └── json_handler.py          # Standard JSON I/O, operation logging, 7 API functions
 ├── templates/
 │   ├── builder/                         # Full scaffold template (45 files, 24 dirs)
-│   ├── birthright/                      # Minimal template
-│   └── .archive/
-│       └── agent_mock_branch/           # Reference implementation
+│   └── birthright/                      # Minimal template
 ├── tests/                               # 13 test files, 253 tests
 ├── spawn_json/                          # JSON tracking directory
 ├── tools/                               # Branch verification utilities
diff --git a/src/aipass/spawn/templates/builder/.spawn/.template_registry.json b/src/aipass/spawn/templates/builder/.spawn/.template_registry.json
index ea2fc27f..e096093c 100644
--- a/src/aipass/spawn/templates/builder/.spawn/.template_registry.json
+++ b/src/aipass/spawn/templates/builder/.spawn/.template_registry.json
@@ -155,7 +155,7 @@
       "content_hash": "a4cf0a8e3b4f",
       "has_branch_placeholder": false
     },
-    "f015": {
+    "f026": {
       "path": "apps/modules/__init__.py",
       "name": "__init__.py",
       "content_hash": "e3b0c44298fc",
@@ -263,7 +263,7 @@
       "content_hash": "28e9ae373563",
       "has_branch_placeholder": false
     },
-    "f026": {
+    "f015": {
       "path": "apps/plugins/__init__.py",
       "name": "__init__.py",
       "content_hash": "e3b0c44298fc",
diff --git a/src/aipass/trigger/README.md b/src/aipass/trigger/README.md
index e4dca03f..a96723d3 100644
--- a/src/aipass/trigger/README.md
+++ b/src/aipass/trigger/README.md
@@ -5,7 +5,7 @@
 **Purpose:** Event bus and error dispatch for AIPass. Branches fire events, registered handlers react. Medic watches logs for errors, fingerprints them, gates dispatch through an 8-stage pipeline, and notifies the responsible branch.
 **Module:** `aipass.trigger`
 **Version:** 2.2.0
-**Last Updated:** 2026-04-22
+**Last Updated:** 2026-05-02
 
 ## Commands