Add generic environment-creation utilities (PEP 723 PR 5a/16)

[StellaHuang95]

Part of #1602 (PEP 723 inline script env support). Design doc: #1601.

Split for review (3 PRs). Reviewers flagged the original PR 5 as too large, so it is split into three stacked PRs grouped by dependency layer:

• 5a — generic env-creation utilities — this PR (Add generic environment-creation utilities (PEP 723 PR 5a/16) #1651). Based on main; independent; merges first.
• 5b — inline-script cache + interpreter utilities — Add inline-script cache and interpreter utilities (PEP 723 PR 5b/16) #1655. Stacked on 5a.
• 5c — create() happy path (manager + wiring) — Add PEP 723 inline script environment creation (PEP 723 PR 5c/16) #1656. Stacked on 5b.

Applied together the three PRs are byte-for-byte identical to the original single change. Merge order: 5a → 5b → 5c.

Roadmap context

This is the first slice of PR 5 of 16 in the PEP 723 inline-script roadmap. The full plan lives in #1602.

Phase	PR	Status
Phase 1: Foundation	PR 1: cache key hash utility	merged (#1634)
	PR 2: cache layout + meta.json sidecar	merged (#1635)
	PR 3: requires-python to interpreter selection	merged (#1636)
Phase 2: Manager	PR 4: InlineScriptEnvManager skeleton	merged (#1610)
	PR 5a: generic env-creation utilities	this PR (#1651)
	PR 5b: inline-script cache + interpreter utilities	#1655
	PR 5c: create() happy path (manager + wiring)	#1656
	PR 6: create() uv-install fallback	not started (needs 3, 5)
	PR 7: persistence with get, set, and Memento	not started (needs 4)
	PR 8: activation-time discovery	not started (needs 2, 4, 7)
Phase 3: Routing	PR 9: route PEP 723 scripts to the inline manager	not started (needs 4, 7)
	PR 10: per-script project registration	not started (needs 9)
Phase 4+: UX / lifecycle	PRs 11-16	not started

Why this PR

PR 5c implements InlineScriptEnvManager.create(). Before touching the manager, this PR lands the generic, reusable primitives it relies on — a cross-process file lock, a venv Python-path helper, a cancellation-hardened process runner, and two small createWithProgress options. None of this code is inline-script-specific, so it is reviewed on its own.

What this PR adds

Cross-process file lock (src/common/lockfile.apis.ts, new): acquireFileLock uses an atomic mkdir of a <path>.lock directory plus a per-owner marker file, returning AcquiredFileLock { release, retain }. retain() writes a retained marker so a later acquirer fails fast with ELOCKRETAINED instead of waiting out the 5-minute timeout — used when a build is cancelled mid-flight. Distinct error codes (ELOCKED, ELOCKRETAINED, ELOCKORPHANED, ECOMPROMISED, ERETAINFAILED) separate contention from corruption.

Shared getVenvPythonPath (src/common/utils/virtualEnvironment.ts, new): returns Scripts\python.exe on Windows, else bin/python. Replaces an inline copy in venvUtils and is reused by 5b/5c.

Hardened process helper (src/managers/builtin/helpers.ts): runUV and runPython now share one runProcess implementation whose cancellation guards kill() in try/catch and still emits a clean CancellationError if the process errors after a cancel. Per-caller options preserve existing behavior (collectStderr, logPrefix).

venvUtils.ts: createWithProgress gains CreateWithProgressOptions { trackUvEnvironment }, and CreateEnvironmentResult gains pkgInstallationCancelled so a caller can tell cancellation apart from a real install failure. Existing callers are unaffected (both are optional / additive).

Tests

• lockfile.apis.unit.test.ts — 9 tests: contention, retain/fail-fast, orphaned and compromised locks, and timeout.
• virtualEnvironment.unit.test.ts — 2 tests for getVenvPythonPath on Windows and POSIX.
• helpers.cancellation.unit.test.ts — 4 tests for runProcess cancellation safety.
• venvUtils.createWithProgress.unit.test.ts — 3 tests for trackUvEnvironment and pkgInstallationCancelled.

On this branch alone npm run compile-tests is clean and npm run unittest reports 1447 passing, 0 failing, 4 pending.

User impact

None. These are internal primitives with no new user-visible behavior. The refactors to helpers.ts and venvUtils.ts are behavior-preserving for existing callers.

[edvilme]

LGTM:)

[edvilme]

Maybe this could be moved to a more generic location? But it doesn't bother me too much.

[eleanorjboyd]

is cleanup required by this error stage? you went through and confirmed we aren't leaving stuff behind in people's file systems right?

[StellaHuang95]

This change I made only catches proc.kill() throwing so the operation still reports CancellationError because it didn't catch the exception before, these 2 functions don't do cleanups, cleanup belongs to the caller. If you're asking about inline script manager in particular, that will be handled at the inline manager level later.