docs: safer Python re-exec pattern for auto-invoking varlock run

[WalksWithASwagger]

Documents the pattern for a Python script that re-execs itself under varlock run, so callers do not have to wrap every invocation.

• Check __VARLOCK_RUN first so the re-exec does not recurse.
• Use os.execvp, not os.execv, so varlock is resolved from PATH.
• Rebuild the interpreter path from VIRTUAL_ENV / sys.prefix instead of passing sys.executable. On macOS with Homebrew Python, sys.executable is the resolved Cellar binary rather than the venv symlink, so re-execing it drops the child out of the venv and fails in ways that look like a varlock bug.

Closes #992

Previously stacked on #1061. That branch was closed and its fixes landed separately as #1064, #1065, and #1066, so this is now rebased onto main and reduced to the Python docs.

[pullfrog]

Important

The imported @currentEnv path is still order-dependent, and the documented Python command fails for normal PATH-based installations. Both should be addressed before merge.

Reviewed changes across all three commits in the current stacked PR, including env-graph loading, data-type coercion, response leak handling, tests, documentation, and editor hints.

• Imported environment flags: Allows @currentEnv to defer resolution when an @import is expected to provide its key, then loads environment-specific files after imports.
• Data-type corrections: Tightens URL host lists, enum override coercion, port validation, IPv6 parsing, and MD5 normalization, with focused tests and matching docs.
• Leak response completion: Finishes or destroys a ServerResponse before rethrowing a leak detected during end().
• Python guidance: Documents venv-aware self-re-execution under varlock run and links it from __VARLOCK_RUN.
• Tooling and release metadata: Updates VS Code URL option descriptions and records patch releases.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using azure/gpt-5.6-sol ｜ 𝕏}

[pullfrog]

Important

The direct fixes address the prior feedback, but the new recursive directory revisit can select the wrong environment below a directory that has its own @currentEnv.

Reviewed changes since the prior Pullfrog review at 0c17bff, covering the fixes to Python re-execution, imported environment selection, and leak-response framing.

• Python re-execution: Replaced os.execv with os.execvp in both examples so varlock is resolved through PATH.
• Imported environment replay: Revisited imported directories after a late imported environment flag resolves, with coverage for a directory declared before the flag provider.
• Environment flag validation: Distinguished schema and import declarations from values that exist only in auto-loaded environment files.
• Leak response framing: Cleared stale encoding and transfer headers and set the replacement 500 body's content length, with wire-level tests.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using azure/gpt-5.6-sol ｜ 𝕏}

[pullfrog]

Important

The new boundary fix can skip inherited environment files when an own @currentEnv exists only deeper in the subtree.

Reviewed changes since the prior Pullfrog review at fe1b3a9, focused on the nested environment-boundary fix.

• Added an environment boundary check: Stopped outer environment replay when an imported directory reports its own @currentEnv.
• Prevented second environment loads: Changed environment-specific loading to remain fixed after a directory selects its first environment.
• Added nested override coverage: Verified that a service-level prod environment and its descendants are not overwritten by the root dev environment.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using azure/gpt-5.6-sol ｜ 𝕏}

[pullfrog]

Important

The re-exec example can switch to a different virtual environment when VIRTUAL_ENV and the running interpreter disagree.

Reviewed changes since the prior Pullfrog review at 2b599d7, after the branch was rebased and narrowed to Python documentation.

• Narrowed the PR scope: Removed the previously stacked runtime changes, leaving only the Python re-exec guidance and its reserved-variable link.
• Documented Python self-re-execution: Added a recursion guard, PATH-based varlock lookup, and venv interpreter reconstruction for the Homebrew macOS case.
• Expanded reserved-variable guidance: Linked __VARLOCK_RUN to the Python integration example.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using azure/gpt-5.6-sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes since the prior Pullfrog review at b139942, focused on the corrected interpreter selection in the Python re-exec example.

• Selected the running virtual environment: Replaced the shell-derived VIRTUAL_ENV choice with Python's sys.prefix != sys.base_prefix check, preventing a directly invoked interpreter from switching into another activated environment.
• Integrated platform-specific interpreter paths: Built the venv executable as bin/python3 on POSIX and Scripts/python.exe on Windows within the example.

  ^{｜ View workflow run ｜ Using azure/gpt-5.6-sol ｜ 𝕏}