[OwenPriceSkelly]

Summary

hog run imports the script in-process, so a harness (or anything defined at module level, e.g. an Academy Agent subclass) needs its imports available locally, not just on the endpoint. The PEP 723 header already lists them; this makes hog run use it.

When the current interpreter does not satisfy requires-python, or any dependencies entry is not installed (app/utils.py::bootstrap_reasons), hog run re-executes itself as

uv run --no-project --python <requires-python> --with <groundhog spec> --with <dep>... \
       [--exclude-newer …] [--index-url …] [--extra-index-url …] \
       hog run <script> <harness> [-- args]

with GROUNDHOG_BOOTSTRAPPED=1 in the child env (a child that still fails the checks warns and runs in-process, so no loop). Scripts the current environment already satisfies run exactly as before.

• New --no-bootstrap flag / GROUNDHOG_NO_BOOTSTRAP=1: warn and run in-process (the old behaviour). Like --log-level, the flag goes before the script path.
• The groundhog spec is get_groundhog_version_spec() (same as the remote side); a 0.0.0 checkout falls back to its own path.
• [tool.uv] exclude-newer / index-url / extra-index-url are forwarded when set.
• Docs: concepts (new "The driver environment" section), dependencies example (module-level imports are fine for harness-side needs), environment variables, regenerated CLI reference.

Motivating case: a single-file Academy × groundhog demo whose Agent classes need academy-py at import time on the laptop. With this, hog run demo.py -- … just works from a plain uv tool install groundhog-hpc.

Test plan

• uv run pytest (384 passed), uv run ruff check ., uv run ty check .
• End to end from this worktree: a script with dependencies = ["cowsay"] (not installed in the tool env) → Bootstrapping an environment from needs_cowsay.py's metadata (missing dependencies: cowsay) → harness ran under Python 3.13.9 with cowsay 6.1 imported, ~6 s wall including the env build.
• Existing hog run tests unchanged (their headers are satisfied → in-process path).

Depends on #141 only in the sense that the motivating demo needs both; the diffs are independent.

🤖 Generated with Claude Code