Session Pre-flight Probe

Role: Eliminate environment-class waste (VIRTUALENV_DRIFT, ENV_BLINDNESS, DIRTY_VCS_STAGING) by probing project health before writing any code.

When to Activate

Activate at session start when the workspace contains any of:

• venv/, .venv/, or env/ (Python virtual environment)
• requirements.txt, pyproject.toml, setup.py (Python project)
• package.json (Node project)
• Makefile with test/lint targets
• .git/ directory
• Imports of pyautogui, xdotool, pygame (GUI automation)

Execution Protocol

Step 1: Detect Project Type

Run a quick scan of workspace root:

ls -1 venv/ .venv/ env/ 2>/dev/null | head -1          # Python venv
ls package.json 2>/dev/null                              # Node
grep -l 'pyautogui\|xdotool\|pygame' *.py **/*.py 2>/dev/null  # GUI automation

Step 2: Dispatch a Fast-Tier Preflight Subagent

Dispatch a ${SLOT.MODEL_FAST} read-only research subagent with the appropriate checklist below. The subagent must NOT modify any files.

Python Project Checklist

Execute these checks and report findings as a structured checklist:

1. VENV HEALTH
   - Run: head -1 ./venv/bin/pip (or .venv/bin/pip)
   - Run: cat ./venv/pyvenv.cfg | grep -E "home|command"
   - PASS if shebang and pyvenv.cfg paths match $PWD
   - FAIL if they point to a different directory (stale venv)

2. TEST SUITE
   - Check if any of these exist: Makefile (with test target), pytest.ini, 
     setup.cfg [tool:pytest], pyproject.toml [tool.pytest]
   - If found, run: make test (or pytest --co -q) to verify tests collect
   - Report: test runner command, number of tests, pass/fail
   - If no test suite found, report: "No test suite detected"

3. GIT STATE
   - Run: git status --porcelain | wc -l
   - Run: git log --oneline -3
   - PASS if clean or <5 uncommitted files
   - WARN if >5 uncommitted files or untracked data directories

4. GITIGNORE COVERAGE
   - Run: git ls-files --others --ignored --exclude-standard | wc -l
   - Check .gitignore covers: venv/, __pycache__/, *.pt, *.pth, data/, 
     models/, *.egg-info/, .env
   - WARN if data/ or models/ directories exist but aren't gitignored

5. DEPENDENCY HEALTH
   - Run: ./venv/bin/pip check 2>&1 | head -10
   - PASS if "No broken requirements found"
   - WARN if any dependency conflicts reported

GUI/Automation Addendum (append to Python checklist)

6. DISPLAY ENVIRONMENT
   - Run: echo $DISPLAY
   - Run: xdpyinfo 2>&1 | head -5 (or xrandr --query)
   - PASS if DISPLAY is set and X11 responds
   - FAIL if DISPLAY unset or Xlib errors

7. AUTOMATION LIBRARIES
   - Run: ./venv/bin/python -c "import pyautogui; print(pyautogui.size())"
   - Check for coordinate calibration files (config.py, hud_reader.py constants)
   - WARN if no calibration data found for screen automation

Node Project Checklist

1. Run: node --version && npm --version
2. Run: npm ls --depth=0 2>&1 | tail -5
3. Check: package.json has "test" script
4. Run: npm test --dry-run (or npm test if fast)
5. Git state: same as Python checklist items 3-4

Step 3: Process Results

When the preflight subagent reports back:

• All PASS: Proceed with deliverable work. Log: "✅ Preflight clean"
• Any WARN: Note warnings but proceed. Inject a brief reminder in your working context.
• Any FAIL: Fix before writing code. Environment defects compound — a stale venv causes 40-120 steps of waste if discovered mid-session.

Cost Budget

Anti-Patterns

• Don't skip preflight for "quick fixes" — the 5dd84eed session started as a "quick git setup" and burned 58 steps on venv drift
• Don't use ${SLOT.MODEL_STANDARD} or ${SLOT.MODEL_HEAVY} for preflight — ${SLOT.MODEL_FAST} is sufficient for read-only diagnostics
• Don't let preflight modify files — it's a read-only probe; fixes are the orchestrator's job
• Don't run preflight on non-coding tasks — governance, documentation, and research sessions don't need it