perf: eliminate macOS discovery timeout tail (Fixes #504)

[Karthik Nadig (karthiknadig)]

Summary

Eliminate the deterministic macOS cold-refresh tail caused by duplicate serialized probes of Apple's /usr/bin/python3 shim. Resolve active developer Python executables from filesystem state instead, while preserving legacy /usr/bin/python behavior.

Changes

• resolve DEVELOPER_DIR, xcode_select_link, and standard developer-directory fallbacks without spawning Python
• reuse file-based mapping in Xcode and Command Line Tools locators
• skip unresolved Apple Python 3 shims before generic process probing
• collect phase/locator diagnostics outside timed refreshes and retain privacy-safe timeout counts beyond the bounded stderr tail
• require complete environment/manager inventory from iteration one
• cover selected-Xcode, CommandLineTools, missing-target, versioned-shim, legacy-shim, timeout-eviction, and measurement-isolation behavior

Validation

• full CI, lint, CodeQL, Linux/Windows coverage, and all enforced performance gates pass
• repeat macOS run: P50 120ms vs 99ms baseline; P95 1,256ms vs 30,320ms; 0 probe timeouts; 10/10 environments from iteration one
• repeat Windows/Linux P50: 138ms/53ms vs 124ms/55ms baselines; inventories unchanged
• exact-head Copilot review: 7/7 files, 0 comments, 0 unresolved threads

Fixes #504

[Copilot]

Pull request overview

This PR targets the macOS cold-refresh ~30s tail latency by avoiding duplicate serialized spawn-based resolution of Apple’s /usr/bin/python3 shim. It adds filesystem-based mapping from the shim to the active developer toolchain Python (Xcode / CommandLineTools) and extends the e2e performance harness to collect/aggregate RefreshProgress telemetry and privacy-safe interpreter timeout categories.

Changes:

• Add macOS-specific utilities to detect and resolve /usr/bin/python3 (and python3.<minor>) shims to the active developer directory without spawning Python.
• Update macOS Xcode and Command Line Tools locators to reuse the file-based mapping and add /usr/bin/python3 as an alias only when it truly matches the discovered interpreter.
• Enhance the e2e performance test harness to collect RefreshProgress telemetry, assert phase coverage per iteration, and classify interpreter probe timeouts into privacy-safe buckets.

Show a summary per file

File	Description
crates/pet/tests/e2e_performance.rs	Collects RefreshProgress notifications, aggregates phase/locator timing stats, and classifies interpreter spawn timeouts into privacy-safe labels for CI metrics.
crates/pet/src/locators.rs	Skips spawn-based resolution for unresolved macOS /usr/bin/python3* shims during fallback resolution to avoid deterministic timeout tails.
crates/pet-python-utils/src/macos.rs	New filesystem-based resolver for macOS system Python shims (developer dir selection + alias handling) without spawning.
crates/pet-python-utils/src/lib.rs	Exposes the new macos module.
crates/pet-mac-xcode/src/lib.rs	Resolves /usr/bin/python3* inputs via file mapping and adds /usr/bin/python3 alias via the shared helper instead of spawning.
crates/pet-mac-commandlinetools/src/lib.rs	Same as Xcode locator: file-based shim mapping + shared alias injection, removing spawn-based probing of /usr/bin/python3.

Review details

Tip

Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

[github-actions]

Performance Report (Linux)

Result: ✅ Within regression budgets

Metric	PR	Baseline	Delta	Change	Blocking budget	Status
Server startup P50	1ms	0ms	+1ms	+inf%	>5ms and >100%	🔺
Server startup P95	1ms	1ms	+0ms	+0.0%	>50ms and >200%	➖
Full refresh P50	56ms	55ms	+1ms	+1.8%	>25ms and >30%	🔺
Full refresh P95	352ms	299ms	+53ms	+17.7%	>1000ms and >100%	🔺
Time to first environment P50	13ms	11ms	+2ms	+18.2%	>20ms and >100%	🔺
Time to first environment P95	19ms	15ms	+4ms	+26.7%	>250ms and >100%	🔺

Workload	PR	Baseline
Environments	5	5
Managers	1	1

A regression must exceed both the documented absolute and relative budget. Environment and manager inventories must match exactly.

[github-actions]

Performance Report (macOS)

Result: ✅ Within regression budgets

Metric	PR	Baseline	Delta	Change	Blocking budget	Status
Server startup P50	78ms	69ms	+9ms	+13.0%	>100ms and >50%	🔺
Server startup P95	691ms	7356ms	-6665ms	-90.6%	>10000ms and >100%	✅
Full refresh P50	163ms	99ms	+64ms	+64.6%	>100ms and >50%	🔺
Full refresh P95	1435ms	30320ms	-28885ms	-95.3%	>5000ms and >25%	✅
Time to first environment P50	102ms	99ms	+3ms	+3.0%	>150ms and >50%	🔺
Time to first environment P95	745ms	7433ms	-6688ms	-90.0%	>10000ms and >100%	✅

Workload	PR	Baseline
Environments	10	10
Managers	1	1

A regression must exceed both the documented absolute and relative budget. Environment and manager inventories must match exactly.

[github-actions]

Performance Report (Windows)

Result: ✅ Within regression budgets

Metric	PR	Baseline	Delta	Change	Blocking budget	Status
Server startup P50	10ms	9ms	+1ms	+11.1%	>10ms and >50%	🔺
Server startup P95	13ms	12ms	+1ms	+8.3%	>50ms and >100%	🔺
Full refresh P50	163ms	124ms	+39ms	+31.5%	>50ms and >30%	🔺
Full refresh P95	492ms	2533ms	-2041ms	-80.6%	>5000ms and >100%	✅
Time to first environment P50	38ms	21ms	+17ms	+81.0%	>25ms and >50%	🔺
Time to first environment P95	71ms	80ms	-9ms	-11.2%	>500ms and >100%	✅

Workload	PR	Baseline
Environments	10	10
Managers	2	2

A regression must exceed both the documented absolute and relative budget. Environment and manager inventories must match exactly.

[github-actions]

Test Coverage Report (Linux)

Result: ✅ Within regression budget

Metric	PR	Baseline	Delta
Lines	80.815%	80.693%	+0.121pp
Functions	84.806%	84.791%	+0.015pp

Allowed numerical tolerance: 0.01 percentage points.

[github-actions]

Test Coverage Report (Windows)

Result: ✅ Within regression budget

Metric	PR	Baseline	Delta
Lines	78.207%	78.065%	+0.142pp
Functions	81.533%	81.467%	+0.066pp

Allowed numerical tolerance: 0.01 percentage points.

[Copilot]

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

Suppressed comments (1)

crates/pet/tests/e2e_performance.rs:418

• interpreter_probe_timeout_labels() derives timeout counts by scanning stderr_tail, but that tail is explicitly bounded (STDERR_TAIL_LINES = 100). If PET emits >100 stderr lines after a spawn timeout, the timeout warning can be evicted from the tail and the test will undercount (potentially masking a regression).

Consider tracking timeout labels/counts in spawn_stderr_reader as lines are read (store only matching labels/counters, which should stay small) instead of scanning the bounded tail for matches.

    fn interpreter_probe_timeout_labels(&self) -> Vec<&'static str> {
        self.stderr_tail
            .lock()
            .expect("PET stderr tail mutex poisoned")
            .iter()

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite