# How Agent Reach Prevents Stale Venv Shims with Backend Health Probing

> Agent Reach stops stale venv shims by running health probes. It finds broken interpreters and provides precise reinstall commands.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-07

---

**Agent Reach prevents stale venv shims by executing a lightweight health probe that attempts to run the binary and detects broken interpreters, then suggests exact reinstall commands.**

When system Python upgrades occur, virtual environment shims pointing to the old interpreter path become invalid while still appearing on the system PATH. Agent Reach solves this by implementing a defensive probing layer that validates executable health before use, ensuring users receive clear remediation guidance instead of cryptic execution errors.

## The Stale Shim Problem

Third-party CLI tools like `yt-dlp`, `ffmpeg`, and `gh` are often installed via Python package managers such as `pipx` or `uv tool install`. These tools create shim executables that reference a specific Python interpreter path. When users upgrade their system Python, the referenced interpreter may be deleted or moved, rendering the shim broken. Standard PATH lookups via `shutil.which` still locate the file, but attempting execution raises `FileNotFoundError` or `OSError`, causing confusing failures in automation scripts.

## How the Health Probe Works

The health probing system is implemented in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) and distinguishes between truly missing binaries and stale shims that exist but cannot execute.

### The probe_command() Function

The `probe_command()` function performs a validation subprocess:

- Locates the command using `shutil.which`
- Executes the command with a safe argument (defaults to `--version`)
- Captures output and exit codes within a configurable timeout

```python
from agent_reach.probe import probe_command

result = probe_command("yt-dlp", ["--version"], timeout=5, package="yt-dlp")

```

### Detecting Broken Shims vs Other Failures

The probe categorizes results into five distinct states:

- **missing** – The command is not found on PATH
- **broken** – The executable exists but raises `FileNotFoundError` or `OSError` during execution, indicating a stale shim
- **timeout** – The process hangs beyond the supplied timeout duration
- **error** – Non-zero exit codes representing application-level failures
- **ok** – Successful execution and response

When detecting a `broken` status, the system generates a specific remediation hint via `reinstall_hint()`, suggesting commands like `uv tool install --force yt-dlp` or `pipx reinstall yt-dlp`.

## Integration with Channel Checks

Each Agent Reach channel validates its dependencies through the base class in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). Channel implementations such as [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) and [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) override the `check()` method to invoke `probe_command()` for their respective binaries.

The `doctor` command (implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) aggregates these individual probe results into a unified health report, displaying the `broken` status with remediation hints rather than generic "command not found" messages.

## Automatic Remediation with reinstall_hint()

When the probe detects a stale shim, it transforms the technical error into actionable guidance. The hint message identifies the specific package manager command needed to rebuild the shim:

```text
命令存在但无法执行——通常是系统 Python 升级后 venv 解释器丢失。重装即可修复：
  uv tool install --force yt-dlp
或：pipx reinstall yt-dlp

```

This allows users to resolve environment issues with a single command instead of debugging interpreter paths manually.

## Code Example: Probing a Binary Directly

You can utilize the probing system directly to validate tool availability:

```python
from agent_reach.probe import probe_command

# Probe a tool that should be available (e.g., yt-dlp)

result = probe_command("yt-dlp", ["--version"], timeout=5, package="yt-dlp")

if result.ok:
    print("yt‑dlp is healthy:", result.output)
elif result.status == "broken":
    print("Stale shim detected! Hint:", result.hint)
else:
    print(f"{result.status.title()} – {result.hint or result.output}")

```

Running this after a system-Python upgrade returns a `broken` status with the reinstall instruction if the `yt-dlp` shim references the old interpreter.

## Summary

- **Stale shims** occur when system Python upgrades invalidate virtual environment interpreter paths while leaving executable files on PATH
- **`probe_command()`** in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) validates binaries by attempting execution and catching `FileNotFoundError` or `OSError`
- **Five distinct states** (missing, broken, timeout, error, ok) provide precise failure classification
- **Channel integration** ensures every dependency is validated through the base class `check()` method
- **`reinstall_hint()`** generates package-manager-specific commands to fix broken shims immediately

## Frequently Asked Questions

### What is a stale venv shim?

A stale venv shim is an executable wrapper created by Python package managers like `pipx` or `uv` that references a specific Python interpreter path. When the system Python version changes or the virtual environment is deleted, the interpreter path becomes invalid, causing the shim to raise `FileNotFoundError` or `OSError` despite still appearing in the system PATH.

### How does Agent Reach distinguish between a missing command and a broken shim?

Agent Reach uses the `probe_command()` function in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) to execute a subprocess test. If `shutil.which` locates the file but the OS raises `FileNotFoundError` or `OSError` during execution, the probe classifies the result as `broken`. If the file is not found on PATH, it returns `missing`, allowing the system to provide appropriate remediation for each scenario.

### What should I do when Agent Reach reports a broken status?

When Agent Reach reports a `broken` status, it includes a remediation hint generated by `reinstall_hint()`. Follow the suggested command, typically `uv tool install --force <package>` or `pipx reinstall <package>`, to rebuild the shim with the correct interpreter path. This resolves the stale reference without requiring manual PATH editing.

### Where is the health probe logic located in the Agent Reach codebase?

The core probing logic resides in [`agent_reach/probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py), which implements `probe_command()` and the `ProbeResult` class. Integration with specific channels appears in files like [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) and [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), while aggregation and reporting logic is found in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). Comprehensive test coverage exists in [`tests/test_probe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_probe.py).