@team-agent/installer 0.5.70 → 0.5.72

package/crates/team-agent/src/leader/owner_bind.rs

@@ -220,6 +220,16 @@ fn bind_provider_from_env_or_pane(command: &str, pane: Option<PaneInfo>) -> Prov
         .unwrap_or(Provider::Codex)
 }
 
+pub(crate) fn strict_owner_bind_provider(
+    explicit_provider: Option<&str>,
+    observed_command: &str,
+) -> Option<Provider> {
+    match explicit_provider.filter(|value| !value.is_empty()) {
+        Some(raw) => super::helpers::parse_provider(raw),
+        None => super::attribute_command_provider(observed_command),
+    }
+}
+
 pub fn owner_bind_provider_wire(command: &str) -> &'static str {
     if let Ok(raw) = std::env::var("TEAM_AGENT_LEADER_PROVIDER") {
         // env 显式 provider:经 parse_provider(单一表,知 copilot)校验后透传其 wire 串;
@@ -341,6 +351,17 @@ mod e11_provider_bind_tests {
         assert_eq!(owner_bind_provider_wire("copilot --banner"), "copilot");
     }
 
+    #[test]
+    fn strict_provider_never_falls_back_from_unknown_explicit_or_command() {
+        assert_eq!(
+            strict_owner_bind_provider(Some("pi"), "codex"),
+            Some(Provider::Pi)
+        );
+        assert_eq!(strict_owner_bind_provider(Some("unknown"), "codex"), None);
+        assert_eq!(strict_owner_bind_provider(None, "pi"), Some(Provider::Pi));
+        assert_eq!(strict_owner_bind_provider(None, "node"), None);
+    }
+
     #[test]
     fn known_commands_map_via_single_source() {
         assert_eq!(

package/crates/team-agent/src/leader/provider_attribution.rs

@@ -96,6 +96,9 @@ fn provider_from_pid_env(pid: u32) -> Option<Provider> {
 
 fn provider_from_command_text(text: &str) -> Option<Provider> {
     let lower = text.to_ascii_lowercase();
+    if pi_command_text(&lower) {
+        return Some(Provider::Pi);
+    }
     if cursor_agent_command_text(&lower) {
         return Some(Provider::CursorAgent);
     }
@@ -104,6 +107,18 @@ fn provider_from_command_text(text: &str) -> Option<Provider> {
         .find_map(|(needle, provider)| lower.contains(needle).then_some(*provider))
 }
 
+fn pi_command_text(lower: &str) -> bool {
+    lower
+        .split_whitespace()
+        .next()
+        .is_some_and(|token| {
+            token == "pi"
+                || token == "pi.exe"
+                || token.ends_with("/pi")
+                || token.ends_with("\\pi.exe")
+        })
+}
+
 /// Cursor 二进制名为 `agent`，不能做 substring contains（会误伤 `team-agent`）。
 /// 认精确 token `cursor-agent` / `…/agent`，且必须带 `--sandbox` 或 `--trust`。
 fn cursor_agent_command_text(lower: &str) -> bool {
@@ -194,6 +209,16 @@ mod tests {
         }
     }
 
+    #[test]
+    fn exact_pi_command_is_attributed_without_substring_guessing() {
+        assert_eq!(attribute_command_provider("pi"), Some(Provider::Pi));
+        assert_eq!(
+            attribute_command_provider("/opt/homebrew/bin/pi --model openai/gpt-5"),
+            Some(Provider::Pi)
+        );
+        assert_eq!(attribute_command_provider("pilot"), None);
+    }
+
     #[test]
     fn direct_command_form_recognizes_copilot() {
         assert_eq!(

package/crates/team-agent/src/leader/registry.rs

@@ -243,7 +243,10 @@ pub fn register_binding_from_state_best_effort(
     );
     let event_log = crate::event_log::EventLog::new(workspace);
     let write_result = write_entry_best_effort(&entry);
-    if write_result.is_some() {
+    // Fresh quick-start is acquisition-only: it must never displace another
+    // same-pane row. Its caller performs a validated-LIVE check before this
+    // write; manual/restart ownership paths keep existing behavior.
+    if write_result.is_some() && source != "quick-start" {
         let _ = mark_displaced_same_pane_entries_unbound(&entry);
     }
     let status = if let Some(path) = &write_result {
@@ -543,6 +546,27 @@ pub fn list_validated_with_gc() -> Vec<(LeaderRegistryEntry, &'static str, Optio
     out
 }
 
+/// Refuse a fresh quick-start binding when the caller pane already backs a
+/// canonically LIVE receiver for another workspace/team. This is read-only:
+/// quick-start never displaces or takes over an existing binding.
+#[must_use]
+pub(crate) fn live_same_pane_binding_elsewhere(
+    pane_id: &str,
+    workspace: &Path,
+    team_key: &str,
+) -> bool {
+    let workspace = std::fs::canonicalize(workspace).unwrap_or_else(|_| workspace.to_path_buf());
+    list_validated_no_gc().into_iter().any(|(entry, status, _)| {
+        status == "LIVE"
+            && entry
+                .channel
+                .get("pane_id")
+                .and_then(Value::as_str)
+                == Some(pane_id)
+            && (entry.workspace != workspace || entry.team_key != team_key)
+    })
+}
+
 /// Same as `list_validated_with_gc` but preserves all entries. `send
 /// --to-leader` needs to see stale entries so it can refuse with
 /// `registry_stale` (and never silently fall through to

package/crates/team-agent/src/leader/start.rs

@@ -138,15 +138,18 @@ pub(crate) fn prepare_leader_start_with_nested_attach(
 ) -> Result<PreparedLeaderStart, PrepareLeaderStartError> {
     let explicit_external_path = external_leader || attach_existing || attach_session.is_some();
     let state_external_path = workspace_state_uses_external_leader(workspace);
-    let (ambient_authority, managed_client_attach_mode, managed_provider_reentry) =
+    let (ambient_authority, managed_client_attach_mode, managed_exec_provider) =
         if explicit_external_path || state_external_path {
             (ambient_pane_authority_preflight(workspace)?, None, false)
         } else if workspace_state_is_managed_provider_reentry(workspace) {
             (ambient_pane_authority_preflight(workspace)?, None, true)
         } else {
-            let (authority, attach_mode) =
-                managed_launcher_ambient_route(workspace, allow_nested_attach)?;
-            (authority, attach_mode, false)
+            managed_launcher_ambient_route(
+                provider,
+                provider_args,
+                workspace,
+                allow_nested_attach,
+            )?
         };
     let plan = leader_start_plan_with_ambient_authority(
         provider,
@@ -158,7 +161,7 @@ pub(crate) fn prepare_leader_start_with_nested_attach(
         external_leader,
         std::env::var_os("TMUX").is_some(),
         managed_client_attach_mode,
-        managed_provider_reentry,
+        managed_exec_provider,
     )?;
     Ok(PreparedLeaderStart {
         plan,
@@ -206,7 +209,7 @@ fn leader_start_plan_with_ambient_authority(
     external_leader: bool,
     in_tmux: bool,
     managed_client_attach_mode: Option<ManagedClientAttachMode>,
-    managed_provider_reentry: bool,
+    managed_exec_provider: bool,
 ) -> Result<LeaderStartPlan, LeaderError> {
     if attach_session.is_some() && !confirm_attach {
         return Err(LeaderError::Start(
@@ -264,7 +267,7 @@ fn leader_start_plan_with_ambient_authority(
         } else {
             false
         };
-    let mode = if managed_provider_reentry {
+    let mode = if managed_exec_provider {
         LeaderStartMode::ExecProvider
     } else if !external_path {
         LeaderStartMode::ManagedTmuxClient
@@ -555,17 +558,24 @@ fn ambient_pane_authority_preflight(
 }
 
 fn managed_launcher_ambient_route(
+    provider: Provider,
+    provider_args: &[String],
     workspace: &Path,
     allow_nested_attach: bool,
 ) -> Result<
     (
         Option<VerifiedAmbientPaneAuthority>,
         Option<ManagedClientAttachMode>,
+        bool,
     ),
     PrepareLeaderStartError,
 > {
     let Some(tmux) = std::env::var_os("TMUX") else {
-        return Ok((None, Some(ManagedClientAttachMode::AttachSession)));
+        return Ok((
+            None,
+            Some(ManagedClientAttachMode::AttachSession),
+            false,
+        ));
     };
     let tmux = tmux.into_string().map_err(|_| {
         PrepareLeaderStartError::PaneAuthorityRefused(ambient_tmux_endpoint_refusal(
@@ -575,6 +585,15 @@ fn managed_launcher_ambient_route(
     })?;
     let observed_endpoint = validated_ambient_tmux_endpoint(workspace, &tmux)
         .map_err(PrepareLeaderStartError::PaneAuthorityRefused)?;
+    if provider == Provider::Pi && provider_args.is_empty() && !allow_nested_attach {
+        // Pi's zero-argument managed entry already owns this verified pane as its
+        // user-facing terminal. Replacing the current process is safe on either
+        // the workspace server or another server; switching/attaching would move
+        // the user away from the positively verified workspace pane.
+        let authority = verified_ambient_pane_authority(workspace, &tmux)
+            .map_err(PrepareLeaderStartError::PaneAuthorityRefused)?;
+        return Ok((Some(authority), None, true));
+    }
     let target_socket_name = TmuxBackend::for_workspace(workspace)
         .tmux_endpoint()
         .ok_or_else(|| LeaderError::Start("workspace tmux endpoint missing".to_string()))?;
@@ -589,7 +608,11 @@ fn managed_launcher_ambient_route(
     if same_server {
         let authority = verified_ambient_pane_authority(workspace, &tmux)
             .map_err(PrepareLeaderStartError::PaneAuthorityRefused)?;
-        return Ok((Some(authority), Some(ManagedClientAttachMode::SwitchClient)));
+        return Ok((
+            Some(authority),
+            Some(ManagedClientAttachMode::SwitchClient),
+            false,
+        ));
     }
     if !allow_nested_attach {
         return Err(LeaderError::Validation(format!(
@@ -603,6 +626,7 @@ fn managed_launcher_ambient_route(
     Ok((
         Some(authority),
         Some(ManagedClientAttachMode::AttachSession),
+        false,
     ))
 }
 

package/crates/team-agent/src/lifecycle/launch/add_agent.rs

@@ -93,6 +93,51 @@ impl Drop for AgentReservation {
     }
 }
 
+fn discover_pi_model_candidates(requested: &str) -> Result<Vec<String>, ()> {
+    crate::lifecycle::launch::pi_mcp::pi_model_candidates(requested).map_err(|_| ())
+}
+
+fn preflight_role_with_pi_model(
+    run_workspace: &Path,
+    team_dir: &Path,
+    agent_id: &AgentId,
+    role_file_path: &Path,
+    discover: &mut dyn FnMut(&str) -> Result<Vec<String>, ()>,
+) -> Result<(), LifecycleError> {
+    if !role_file_path.exists() {
+        return Err(LifecycleError::Compile(format!(
+            "role file not found: {}",
+            role_file_path.display()
+        )));
+    }
+    let (meta, _) = crate::compiler::read_front_matter(role_file_path)
+        .map_err(|error| LifecycleError::Compile(error.to_string()))?;
+    crate::compiler::preflight_pi_role_model_with(&meta, discover).map_err(|error| {
+        LifecycleError::PiModelPreflight {
+            requested: error.requested,
+            candidates: error.candidates,
+            action: error.action,
+            not_ready: error.not_ready,
+        }
+    })?;
+    let team_meta = crate::compiler::read_front_matter(&team_dir.join("TEAM.md"))
+        .map(|(meta, _)| meta)
+        .unwrap_or(Value::Null);
+    let compiled = crate::compiler::compile_role_agent(
+        role_file_path,
+        &team_meta,
+        &run_workspace.display().to_string(),
+    )
+    .map_err(|error| LifecycleError::Compile(error.to_string()))?;
+    if compiled.id != agent_id.as_str() {
+        return Err(LifecycleError::Compile(format!(
+            "role file declares name '{}' but add-agent id is '{}'",
+            compiled.id, agent_id
+        )));
+    }
+    Ok(())
+}
+
 fn reserve_agent_slot(
     workspace: &Path,
     team: Option<&str>,
@@ -209,6 +254,25 @@ pub fn add_agent(
     role_file_path: &Path,
     open_display: bool,
     team: Option<&str>,
+) -> Result<AddAgentReport, LifecycleError> {
+    let mut discover = discover_pi_model_candidates;
+    add_agent_with_pi_preflight(
+        workspace,
+        agent_id,
+        role_file_path,
+        open_display,
+        team,
+        &mut discover,
+    )
+}
+
+fn add_agent_with_pi_preflight(
+    workspace: &Path,
+    agent_id: &AgentId,
+    role_file_path: &Path,
+    open_display: bool,
+    team: Option<&str>,
+    discover: &mut dyn FnMut(&str) -> Result<Vec<String>, ()>,
 ) -> Result<AddAgentReport, LifecycleError> {
     let selected = match crate::state::selector::resolve_active_team(
         workspace,
@@ -225,13 +289,14 @@ pub fn add_agent(
                     workspace, team,
                 )
                 .unwrap_or_else(|_| crate::tmux_backend::TmuxBackend::for_workspace(workspace));
-            return add_agent_with_transport(
+            return add_agent_with_transport_pi_preflight(
                 workspace,
                 agent_id,
                 role_file_path,
                 open_display,
                 team,
                 &transport,
+                discover,
             );
         }
         Err(error) => return Err(LifecycleError::TeamSelect(error.to_string())),
@@ -242,6 +307,13 @@ pub fn add_agent(
         team: Some(selected.team_key.as_str()),
         agent_id: Some(agent_id),
     })?;
+    preflight_role_with_pi_model(
+        &selected.run_workspace,
+        &selected.team_dir,
+        agent_id,
+        role_file_path,
+        discover,
+    )?;
     let reservation = reserve_agent_slot(
         &selected.run_workspace,
         Some(selected.team_key.as_str()),
@@ -292,9 +364,38 @@ pub fn add_agent_force(
     open_display: bool,
     team: Option<&str>,
     force: bool,
+) -> Result<AddAgentReport, LifecycleError> {
+    let mut discover = discover_pi_model_candidates;
+    add_agent_force_with_pi_preflight(
+        workspace,
+        agent_id,
+        role_file_path,
+        open_display,
+        team,
+        force,
+        &mut discover,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+fn add_agent_force_with_pi_preflight(
+    workspace: &Path,
+    agent_id: &AgentId,
+    role_file_path: &Path,
+    open_display: bool,
+    team: Option<&str>,
+    force: bool,
+    discover: &mut dyn FnMut(&str) -> Result<Vec<String>, ()>,
 ) -> Result<AddAgentReport, LifecycleError> {
     if !force {
-        return add_agent(workspace, agent_id, role_file_path, open_display, team);
+        return add_agent_with_pi_preflight(
+            workspace,
+            agent_id,
+            role_file_path,
+            open_display,
+            team,
+            discover,
+        );
     }
     let selected = crate::state::selector::resolve_active_team(
         workspace,
@@ -322,6 +423,7 @@ pub fn add_agent_force(
         open_display,
         Some(canonical_team_key.as_str()),
         &transport,
+        discover,
     )
 }
 
@@ -340,6 +442,28 @@ pub(crate) fn add_agent_with_transport(
     open_display: bool,
     team: Option<&str>,
     transport: &dyn Transport,
+) -> Result<AddAgentReport, LifecycleError> {
+    let mut discover = discover_pi_model_candidates;
+    add_agent_with_transport_pi_preflight(
+        workspace,
+        agent_id,
+        role_file_path,
+        open_display,
+        team,
+        transport,
+        &mut discover,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn add_agent_with_transport_pi_preflight(
+    workspace: &Path,
+    agent_id: &AgentId,
+    role_file_path: &Path,
+    open_display: bool,
+    team: Option<&str>,
+    transport: &dyn Transport,
+    discover: &mut dyn FnMut(&str) -> Result<Vec<String>, ()>,
 ) -> Result<AddAgentReport, LifecycleError> {
     let run_workspace = crate::model::paths::canonical_run_workspace(workspace)
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
@@ -349,6 +473,13 @@ pub(crate) fn add_agent_with_transport(
         team,
         agent_id: Some(agent_id),
     })?;
+    preflight_role_with_pi_model(
+        &run_workspace,
+        workspace,
+        agent_id,
+        role_file_path,
+        discover,
+    )?;
     let reservation = reserve_agent_slot(&run_workspace, team, agent_id)?;
     drop(lifecycle_lock);
     add_agent_with_transport_at_paths_reserved(
@@ -380,15 +511,40 @@ pub(crate) fn add_agent_with_transport_force(
     team: Option<&str>,
     force: bool,
     transport: &dyn Transport,
+) -> Result<AddAgentReport, LifecycleError> {
+    let mut discover = discover_pi_model_candidates;
+    add_agent_with_transport_force_pi_preflight(
+        workspace,
+        agent_id,
+        role_file_path,
+        open_display,
+        team,
+        force,
+        transport,
+        &mut discover,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn add_agent_with_transport_force_pi_preflight(
+    workspace: &Path,
+    agent_id: &AgentId,
+    role_file_path: &Path,
+    open_display: bool,
+    team: Option<&str>,
+    force: bool,
+    transport: &dyn Transport,
+    discover: &mut dyn FnMut(&str) -> Result<Vec<String>, ()>,
 ) -> Result<AddAgentReport, LifecycleError> {
     if !force {
-        return add_agent_with_transport(
+        return add_agent_with_transport_pi_preflight(
             workspace,
             agent_id,
             role_file_path,
             open_display,
             team,
             transport,
+            discover,
         );
     }
     let run_workspace = crate::model::paths::canonical_run_workspace(workspace)
@@ -407,6 +563,7 @@ pub(crate) fn add_agent_with_transport_force(
         open_display,
         team,
         transport,
+        discover,
     )
 }
 
@@ -415,6 +572,7 @@ pub(crate) fn add_agent_with_transport_force(
 /// returns: 新席报告；成功后还要过快照的一致性校验
 /// errors: 角色文件不存在先行返回 Compile；摘除、加回或一致性校验失败时按快照恢复并返回错误
 /// ---
+#[allow(clippy::too_many_arguments)]
 pub(super) fn force_recreate_with_transport_locked(
     run_workspace: &Path,
     team_dir: &Path,
@@ -423,15 +581,16 @@ pub(super) fn force_recreate_with_transport_locked(
     open_display: bool,
     team: Option<&str>,
     transport: &dyn Transport,
+    discover: &mut dyn FnMut(&str) -> Result<Vec<String>, ()>,
 ) -> Result<AddAgentReport, LifecycleError> {
     // Reject an unusable replacement source before consuming the old seat.
-    // Deeper compile/spawn failures remain covered by the transaction snapshot.
-    if !role_file_path.exists() {
-        return Err(LifecycleError::Compile(format!(
-            "role file not found: {}",
-            role_file_path.display()
-        )));
-    }
+    preflight_role_with_pi_model(
+        run_workspace,
+        team_dir,
+        agent_id,
+        role_file_path,
+        discover,
+    )?;
     let snapshot = crate::lifecycle::restart::remove::ForceRecreateSnapshot::capture(
         run_workspace,
         agent_id,

package/crates/team-agent/src/lifecycle/launch/pi_mcp.rs

@@ -15,10 +15,12 @@
 
 use std::collections::BTreeSet;
 use std::fs::OpenOptions;
-use std::io::Write;
+use std::io::{Read, Write};
 use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
 use std::path::{Path, PathBuf};
-use std::process::Command;
+use std::process::{Command, Stdio};
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
 
 use sha2::{Digest, Sha256};
 
@@ -450,13 +452,24 @@ pub(crate) fn validate_pi_wrapper_source(
 /// errors: identity、序列化、目录、写盘或 rename 失败时返回 ProviderError
 /// ---
 pub(crate) fn write_pi_wrapper(request: PiWrapperRequest<'_>) -> Result<PathBuf, ProviderError> {
+    write_pi_wrapper_with_publish(request, |from, to| std::fs::rename(from, to))
+}
+
+pub(crate) fn write_pi_wrapper_with_publish(
+    request: PiWrapperRequest<'_>,
+    publish: impl FnOnce(&Path, &Path) -> std::io::Result<()>,
+) -> Result<PathBuf, ProviderError> {
     let source = render_pi_wrapper(&request)?;
     validate_pi_wrapper_source(&source, request.adapter, request.candidate_executable)?;
     let parent = request.destination.parent().ok_or_else(|| {
         ProviderError::Io("Pi wrapper destination has no parent directory".to_string())
     })?;
-    std::fs::create_dir_all(parent)
-        .map_err(|error| ProviderError::Io(format!("{}: {error}", parent.display())))?;
+    std::fs::create_dir_all(parent).map_err(|error| {
+        ProviderError::Io(format!(
+            "Pi wrapper atomic write stage=create_parent path={}: {error}",
+            parent.display()
+        ))
+    })?;
     let temp = parent.join(format!(".team-mcp.ts.{}.tmp", std::process::id()));
     let write_result = (|| {
         let mut file = OpenOptions::new()
@@ -464,22 +477,38 @@ pub(crate) fn write_pi_wrapper(request: PiWrapperRequest<'_>) -> Result<PathBuf,
             .write(true)
             .mode(0o600)
             .open(&temp)
-            .map_err(|error| ProviderError::Io(format!("{}: {error}", temp.display())))?;
-        file.write_all(source.as_bytes())
-            .map_err(|error| ProviderError::Io(format!("{}: {error}", temp.display())))?;
-        file.sync_all()
-            .map_err(|error| ProviderError::Io(format!("{}: {error}", temp.display())))?;
-        std::fs::rename(&temp, request.destination).map_err(|error| {
+            .map_err(|error| {
+                ProviderError::Io(format!(
+                    "Pi wrapper atomic write stage=open_temp path={}: {error}",
+                    temp.display()
+                ))
+            })?;
+        file.write_all(source.as_bytes()).map_err(|error| {
             ProviderError::Io(format!(
-                "rename {} to {}: {error}",
-                temp.display(),
-                request.destination.display()
+                "Pi wrapper atomic write stage=write_temp path={}: {error}",
+                temp.display()
             ))
         })?;
-        std::fs::set_permissions(request.destination, std::fs::Permissions::from_mode(0o600))
+        file.set_permissions(std::fs::Permissions::from_mode(0o600))
             .map_err(|error| {
-                ProviderError::Io(format!("{}: {error}", request.destination.display()))
+                ProviderError::Io(format!(
+                    "Pi wrapper atomic write stage=chmod_temp_fd path={}: {error}",
+                    temp.display()
+                ))
             })?;
+        file.sync_all().map_err(|error| {
+            ProviderError::Io(format!(
+                "Pi wrapper atomic write stage=fsync_temp path={}: {error}",
+                temp.display()
+            ))
+        })?;
+        publish(&temp, request.destination).map_err(|error| {
+            ProviderError::Io(format!(
+                "Pi wrapper atomic write stage=rename_publish from={} to={}: {error}",
+                temp.display(),
+                request.destination.display()
+            ))
+        })?;
         Ok(request.destination.to_path_buf())
     })();
     if write_result.is_err() {
@@ -559,6 +588,78 @@ fn executable_file_type(path: &Path) -> Result<PiExecutableFileType, ProviderErr
     }
 }
 
+/// Discover candidates with one PATH-first catalog observation. This deliberately
+/// does not resolve adapters or scan wrapper chains; callers use it only for
+/// rejecting an unqualified role model before lifecycle mutation.
+pub(crate) fn run_pi_catalog(
+    executable: &Path,
+    timeout: Duration,
+    max_bytes: u64,
+) -> Result<Vec<u8>, String> {
+    let mut child = Command::new(executable)
+        .arg("--list-models")
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+        .map_err(|_| "Pi executable is unavailable on PATH".to_string())?;
+    let stdout = child.stdout.take().ok_or_else(|| {
+        let _ = child.kill();
+        let _ = child.wait();
+        "Pi model catalog output unavailable".to_string()
+    })?;
+    let (sender, receiver) = mpsc::channel();
+    std::thread::spawn(move || {
+        let mut bytes = Vec::new();
+        let result = stdout.take(max_bytes + 1).read_to_end(&mut bytes);
+        let _ = sender.send((result, bytes));
+    });
+    let start = Instant::now();
+    loop {
+        match child.try_wait() {
+            Ok(Some(status)) => {
+                let (result, bytes) = receiver.recv_timeout(timeout.saturating_sub(start.elapsed()))
+                    .map_err(|_| "Pi model catalog command timed out".to_string())?;
+                if !status.success() { return Err("Pi model catalog command failed".into()); }
+                result.map_err(|_| "Pi model catalog could not be read".to_string())?;
+                if bytes.len() as u64 > max_bytes { return Err("Pi model catalog exceeds the bounded output limit".into()); }
+                return Ok(bytes);
+            }
+            Ok(None) if start.elapsed() < timeout => std::thread::sleep(Duration::from_millis(20)),
+            Ok(None) => {
+                let _ = child.kill();
+                let _ = child.wait();
+                return Err("Pi model catalog command timed out".into());
+            }
+            Err(_) => {
+                let _ = child.kill();
+                let _ = child.wait();
+                return Err("Pi model catalog command could not be observed".into());
+            }
+        }
+    }
+}
+
+pub(crate) fn pi_model_candidates(requested: &str) -> Result<Vec<String>, ProviderError> {
+    let path = std::env::var_os("PATH")
+        .ok_or_else(|| ProviderError::Command("PATH is not set".to_string()))?;
+    let executable = std::env::split_paths(&path)
+        .map(|directory| directory.join("pi"))
+        .find(|candidate| candidate.is_file())
+        .ok_or_else(|| ProviderError::Command("Pi executable not found on PATH".to_string()))?;
+    let catalog = run_pi_catalog(&executable, Duration::from_secs(10), 1024 * 1024)
+        .map_err(ProviderError::Command)?;
+    let models = parse_pi_list_models_table(&catalog)?;
+    Ok(models
+        .into_iter()
+        .filter(|model| {
+            model
+                .rsplit_once('/')
+                .is_some_and(|(_, name)| name == requested)
+        })
+        .collect())
+}
+
 fn pi_path_entries() -> Result<Vec<PathBuf>, ProviderError> {
     let path = std::env::var_os("PATH")
         .ok_or_else(|| ProviderError::Command("PATH is not set".to_string()))?;