feat(python): skip-if-listed and search-first logic for package management

- Updated PipEnvironmentProvider and PixiEnvironmentProvider to skip installation of already listed packages.
- Introduced GetListJsonAsync method for both providers to retrieve installed package states.
- Enhanced package installation logic to prioritize conda and PyPI based on availability.
- Added tests to verify the new behavior for package management and ensure correct handling of installed states.
- Updated documentation to reflect changes in decision-making for package installation strategies.

Author: trgiangv

docs/agents/known-test-gaps.md

@@ -71,7 +71,9 @@ Thin unit layer (`tests/DevTools.Execution.Tests`, ~23 cases).
 
 ### Well covered
 
-- **Python environment** — pip/pixi path resolution, env probing
+- **Python environment** — pip fixtures; Pixi helper unit tests (`PartitionByAvailability`,
+  `ExtractPackageName`); Parser installed-state via list JSON; opt-in smoke
+  (`RUN_PIXI_SMOKE=1` → setup + Python.NET import)
 - **Execution guard** — `ExecutionGuardContext` ambient mode / rollback summary
 
 ### Gaps (low automated coverage)
@@ -81,6 +83,7 @@ Thin unit layer (`tests/DevTools.Execution.Tests`, ~23 cases).
 - **Host threading** — `IHostContextExecutor`, main-thread marshaling for API calls
 - **MCP dispatch from execution** — `McpPrimitiveDispatcher`, `ToolInvoke.py` payload path
 - **Built-in tools** — open document, registry providers
+- **Pixi AppData ensure/install** — opt-in smoke only; no CI coverage of cold wipe or search-first add
 
 `tests/RevitDevTool.PyServer.Tests/` — small Python parser check only.
 

docs/decisions/0014-pep723-skip-if-listed-search-first.md

@@ -0,0 +1,40 @@
+# 0014 Skip-If-Listed + Search-First (Pixi/Pip)
+
+Date: 2026-08-06  
+Updated: 2026-08-06
+
+## Status
+
+Accepted
+
+## Context
+
+Install/ensure used **try-first** (`pixi add` / `pip install` even when packages
+were already present; Pixi also failed-then-retried channel selection). Prefer
+**skip when listed**, then classify missing packages once (Pixi).
+
+This is a small ensure/install improvement. Warm host open still depends on
+`IsEnvironmentReady()` (home set + `python.exe`); it is not a startup rewrite.
+
+## Decision
+
+1. **Skip if listed (Pixi and Pip)** — `GetListJsonAsync` (`pixi list --json` /
+   `pip list --format=json`) supplies installed names before require-ensure,
+   `InstallPackagesAsync`, and PEP 723 resolve (`PythonDepsManager` → Parser).
+2. **Search-first (Pixi only)** — for missing specs: `pixi search --limit 1`
+   (exit code) → at most one conda batch and one PyPI batch. Not fail-then-retry
+   as primary. Pip is PyPI-only: list-skip then `pip install`.
+3. **Provider shape** — `PyEnvironmentProvider` owns process-scoped
+   `PythonHome` via abstract `ResolvePythonHomeAsync` + `EnsurePythonHomeAsync`
+   (assign once). `IsEnvironmentReady()` is read-only. `GetListJsonAsync` is
+   abstract on the base (no `Backend` switch in callers).
+
+## Non-goals
+
+- Claiming CLI version bumps as a latency win.
+- Pixi shell-hook / fake `CONDA_PREFIX` activation in the host process.
+
+## Consequences
+
+Ensure/install avoid redundant adds and systematic failed solves.
+`PixiPackageHelper` may still read list `kind` for remove/update.

docs/decisions/README.md

@@ -22,3 +22,4 @@ here.
 | [0010](0010-daemon-sole-mcp-host.md) | Daemon is sole MCP host | Accepted |
 | [0011](0011-hybrid-repository-harness-layout.md) | Hybrid repository-harness docs layout | Accepted |
 | [0012](0012-host-mcp-spec-engine.md) | Host MCP spec engine (no SDK on host) | Accepted |
+| [0014](0014-pep723-skip-if-listed-search-first.md) | Skip-if-listed + search-first (Pixi/Pip) | Accepted |

docs/plans/README.md

@@ -30,11 +30,11 @@ decision into `docs/decisions/`; keep task-local choices in the plan.
 
 | Plan | Status |
 |------|--------|
-| [2026-07-27-mcp-dynamic-discovery-and-python-toolset.md](active/2026-07-27-mcp-dynamic-discovery-and-python-toolset.md) | Active — Python alias fix + hybrid search + round-trip cuts |
-| [2026-07-26-mcp-agent-efficiency.md](active/2026-07-26-mcp-agent-efficiency.md) | Active — Phase 1 MCP re-measure / Phase 3 optional pending |
+| [2026-08-02-mrtr-implementation.md](active/2026-08-02-mrtr-implementation.md) | Active — G1 closed; G3/G4 open |
 
 ## Recently Completed
 
 | Plan | Completed |
 |------|-----------|
+| [2026-08-06-pixi-skip-if-listed.md](completed/2026-08-06-pixi-skip-if-listed.md) | 2026-08-06 |
 | [2026-07-25-mcp-call-observability.md](completed/2026-07-25-mcp-call-observability.md) | 2026-07-25 |

docs/plans/completed/2026-08-06-pixi-skip-if-listed.md

@@ -0,0 +1,32 @@
+# Execution Plan: Skip-if-listed + Pixi search-first
+
+Date: 2026-08-06  
+Completed: 2026-08-06
+
+## Status
+
+Completed
+
+## Outcome
+
+Land [0014](../../decisions/0014-pep723-skip-if-listed-search-first.md): replace
+try-first with skip-if-listed (both backends) and Pixi search-first. Pin Pixi
+**0.76.1**. Small ensure/install change — not a host-startup benchmark.
+
+## Done (matches code)
+
+- [x] `PythonInstaller.PixiVersion` = `0.76.1`
+- [x] `PyEnvironmentProvider`: `ResolvePythonHomeAsync` / `EnsurePythonHomeAsync`,
+      read-only `IsEnvironmentReady`, abstract `GetListJsonAsync`, shared
+      `GetInstalledNamesAsync`
+- [x] Pixi: list → skip; missing → search → add batches
+- [x] Pip: list → skip before `pip install` (require ensure + `InstallPackagesAsync`)
+- [x] `PythonDepsManager`: `provider.GetListJsonAsync` → Parser stdin (no Backend switch)
+- [x] No shell-hook / fake activation
+- [x] Tests: `PixiEnvironmentProviderTests`; opt-in `PixiEnvironmentSmokeTests`
+      (`RUN_PIXI_SMOKE=1`)
+
+## Result
+
+Ensure/install paths skip when already listed. Warm open still short-circuits
+when `PythonHome` is set and `python.exe` exists after setup in-process.

source/DevTools.Execution/Providers/Python/PipEnvironmentProvider.cs

@@ -13,15 +13,19 @@ namespace DevTools.Execution.Providers.Python;
 /// where pixi.exe cannot execute due to security policies.
 /// Discovers the CPython distribution shipped with pyRevit (cengines directory),
 /// bootstraps pip, and uses <c>python.exe -m pip</c> for package management.
+/// Policy: skip if listed; otherwise pip install (single channel — no search-first).
 /// </summary>
 public sealed class PipEnvironmentProvider(ILogger<PipEnvironmentProvider> logger) : PyEnvironmentProvider
 {
     public override PythonBackend Backend => PythonBackend.Pip;
 
+    protected override Task<string> ResolvePythonHomeAsync()
+        => DiscoverPyRevitAsync();
+
     public override async Task SetupEnvironmentAsync()
     {
-        PythonHomePath = await DiscoverPyRevitAsync().ConfigureAwait(false);
-        RemovePthFile(PythonHomePath);
+        await EnsurePythonHomeAsync().ConfigureAwait(false);
+        RemovePthFile(PythonHome);
 
         if (!await IsPipAvailableAsync().ConfigureAwait(false))
             await BootstrapPipAsync().ConfigureAwait(false);
@@ -105,12 +109,19 @@ private static async Task<List<string>> GetAttachedClonePathsAsync()
 
     private async Task EnsureRequirePackagesAsync()
     {
-        // pip install is idempotent with version constraints:
-        // no-op if constraint is already satisfied, upgrades if version falls outside range.
-        var specs = RequirePackages.Values.ToList();
+        var installed = await GetInstalledNamesAsync().ConfigureAwait(false);
+        var missing = RequirePackages.Values
+            .Where(spec => !installed.Contains(ExtractPackageName(spec)))
+            .ToList();
+
+        if (missing.Count == 0)
+        {
+            logger.ZLogDebug($"[Pip] Require packages already installed — skipping pip install.");
+            return;
+        }
 
         var args = new List<string> { "-m", "pip", "install", "--prefer-binary", "--no-warn-script-location" };
-        args.AddRange(specs);
+        args.AddRange(missing);
 
         var result = await Cli.Wrap(PythonExe)
             .WithArguments(args)
@@ -121,21 +132,29 @@ private async Task EnsureRequirePackagesAsync()
             .ExecuteAsync().ConfigureAwait(false);
 
         if (result.ExitCode != 0)
-            throw new InvalidOperationException($"Failed to verify required packages: {string.Join(", ", specs)}");
+            throw new InvalidOperationException($"Failed to verify required packages: {string.Join(", ", missing)}");
     }
 
     public override async Task InstallPackagesAsync(
         IEnumerable<string> packages,
         IProgress<string> progress,
         CancellationToken cancellationToken)
     {
-        var list = packages.ToList();
-        if (list.Count == 0) return;
+        var requested = packages.ToList();
+        if (requested.Count == 0) return;
 
-        progress.Report($"Installing {list.Count} package(s) via pip: {string.Join(", ", list)}");
+        var installed = await GetInstalledNamesAsync(cancellationToken).ConfigureAwait(false);
+        var missing = requested.Where(spec => !installed.Contains(ExtractPackageName(spec))).ToList();
+        if (missing.Count == 0)
+        {
+            progress.Report("All requested packages already installed.");
+            return;
+        }
+
+        progress.Report($"Installing {missing.Count} package(s) via pip: {string.Join(", ", missing)}");
 
         var (succeeded, failed) = await TryPipInstallBatchAsync(
-            list, progress, cancellationToken).ConfigureAwait(false);
+            missing, progress, cancellationToken).ConfigureAwait(false);
 
         if (succeeded.Count > 0 && failed.Count > 0)
             progress.Report($"pip: {string.Join(", ", succeeded)}");
@@ -146,7 +165,25 @@ public override async Task InstallPackagesAsync(
                 $"Failed to install the following package(s): {string.Join(", ", failed)}");
         }
 
-        progress.Report($"All {list.Count} package(s) installed via pip.");
+        progress.Report($"All {requested.Count} package(s) processed via pip.");
+    }
+
+    /// <inheritdoc />
+    public override async Task<string> GetListJsonAsync(CancellationToken cancellationToken = default)
+    {
+        if (!IsEnvironmentReady())
+            return string.Empty;
+
+        var stdout = new StringBuilder();
+        var result = await Cli.Wrap(PythonExe)
+            .WithArguments(["-m", "pip", "list", "--format=json"])
+            .WithWorkingDirectory(PythonHome)
+            .WithStandardOutputPipe(PipeTarget.ToStringBuilder(stdout))
+            .WithValidation(CommandResultValidation.None)
+            .ExecuteAsync(cancellationToken)
+            .ConfigureAwait(false);
+
+        return result.ExitCode == 0 ? stdout.ToString().Trim() : string.Empty;
     }
 
     private void RemovePthFile(string targetDir)