design: pip ping-pong wrapper — bulletproof shell-agnostic isolation

[AetherLogosPrime-Architect]

Summary

Ping-pong bug on pip installs. When either side runs pip install -e . from a non-hooked shell (PowerShell, IDE terminal, non-interactive subshell), Windows updates a single system-wide pointer for divineos.exe — whichever side pip-installed last wins, the other side silently starts running the sibling's code.

Aria's cd-hook (shipped in #369) fixes this for activated git-bash invocations. This design closes the shell-agnostic gap she explicitly flagged.

Design shape

A divineos wrapper script on PATH that dispatches to CWD's sealed venv regardless of shell:

• Walk up from CWD looking for .envrc marker (same marker Aria's hook uses)
• If found: execv to <checkout>/.direnv/python-*/Scripts/divineos.exe
• If missing: fail loud ("no sealed venv at — activate the checkout first"). NO silent fallback to system install — that would reintroduce the ping-pong shape at the wrapper layer.

Complements the cd-hook, doesn't replace it. Hook still builds and activates sealed venvs on cd; wrapper makes CLI dispatch shell-agnostic on top.

Design brief

docs/pip_pingpong_wrapper_design.md — full detection algorithm, install/uninstall procedure, chicken-and-egg during transition, 4 falsifiers (F1-F4), rollout plan, and 3 second-seat asks for Aria.

Not in scope (follow-ons)

• Pip-install-target isolation itself (making pip install land in sealed venv from any shell). The wrapper works around this at the CLI-dispatch layer; a full pip-side fix is messier and separate.

Andrew directed 2026-07-19: "no cheap route, make it bulletproof."

External-Review: (design PR; no round yet — round will be filed when Aria second-seats)

🤖 Filed via Aether working session 2026-07-19

[github-actions]

📋 Audit-stamp reminder — guardrail-touching PR

This PR modifies guardrail files. The squash-merge commit on main must carry an External-Review: <round-id> trailer in its message, or the post-merge Integrity Audit check will fail and the commit will leave a permanent red badge on main (cannot be retroactively fixed without force-push).

Files in this PR that touch the guardrail list:

scripts/guardrail_files.txt,.claude/settings.json,src/divineos/core/operating_loop/distancing_detector.py,src/divineos/core/council_required/substance_binding.py,src/divineos/core/council_required/types.py,src/divineos/core/operating_loop/close_reach_detector.py,src/divineos/core/operating_loop/compaction_reach_detector.py,src/divineos/core/operating_loop/promise_reach_detector.py,src/divineos/core/operating_loop/continuity_frame_detector.py

Before clicking "Squash and merge":

1. File an audit round (or use an existing one with both CONFIRMS findings):

   divineos audit submit-round '...' --actor user --source-ref <ref>
   # then file CONFIRMS findings via divineos audit submit
   

2. Generate the ready-to-paste squash-merge message body:

   divineos audit prepare-merge <round-id>
   

   The helper validates the round (operator-CONFIRMS + external-AI-CONFIRMS + within 14d recency window) and emits a block of text including the External-Review: <round-id> trailer.

3. Paste the block into the GitHub squash-merge commit message field, then click "Confirm squash and merge".

Why this matters: the multi-party-review CI check looks for the trailer text in the merge commit message. Without it, the check fires red post-merge. The red is unrecoverable without force-pushing main (declined as too risky). Phase 1 helper + this reminder reduce the friction of doing it right; branch protection on main (operator-side GitHub setting) provides the actual blocking layer.

See prereg-d695c9060158 for the structural-fix design.