@team-agent/installer 0.5.71 → 0.5.72

package/crates/team-agent/src/cli/models.rs

@@ -0,0 +1,443 @@
+//! Read-only Pi model catalog discovery for `team-agent models`.
+use super::{CliError, CmdOutput, CmdResult, ExitCode, ModelsArgs};
+use serde_json::{json, Value};
+use std::path::Path;
+use std::process::Command;
+use std::time::Duration;
+const CATALOG_TIMEOUT: Duration = Duration::from_secs(10);
+const MAX_CATALOG_BYTES: u64 = 1024 * 1024;
+
+pub fn cmd_models(args: &ModelsArgs) -> Result<CmdResult, CliError> {
+    cmd_models_with(args, Path::new("pi"), CATALOG_TIMEOUT, MAX_CATALOG_BYTES)
+}
+
+fn cmd_models_with(
+    args: &ModelsArgs,
+    program: &Path,
+    timeout: Duration,
+    max_bytes: u64,
+) -> Result<CmdResult, CliError> {
+    let bytes = match run_catalog(program, timeout, max_bytes) {
+        Ok(bytes) => bytes,
+        Err(message) => return Ok(failure(args, &message)),
+    };
+    let all = match crate::lifecycle::launch::pi_mcp::parse_pi_list_models_table(&bytes) {
+        Ok(models) => models,
+        Err(error) => return Ok(failure(args, &safe_catalog_error(error))),
+    };
+    let visible = args.search.as_deref().map_or_else(
+        || all.clone(),
+        |search| {
+            all.iter()
+                .filter(|model| model.contains(search))
+                .cloned()
+                .collect::<Vec<_>>()
+        },
+    );
+    let current = current_role_model(&all);
+    let entries: Vec<Value> = visible
+        .iter()
+        .map(|model| {
+            json!({
+                "role_model": model,
+                "current": current.as_deref() == Some(model.as_str()),
+            })
+        })
+        .collect();
+    let value = json!({
+        "schema_version": "models.v1", "ok": true, "provider": "pi", "models": entries,
+        "auth": "ok", "auth_basis": "catalog_visibility", "current_role_model": current, "search": args.search,
+    });
+    if args.json {
+        let text = serde_json::to_string_pretty(&value)?;
+        Ok(CmdResult {
+            output: CmdOutput::Human(text),
+            exit: ExitCode::Ok,
+            as_json: false,
+            preserve_json_order: true,
+        })
+    } else {
+        let mut lines = vec!["models.v1 | Pi models (copyable role_model):".to_string()];
+        lines.extend(visible.iter().map(|model| {
+            format!(
+                "role_model: {model} current={}",
+                current.as_deref() == Some(model.as_str())
+            )
+        }));
+        lines.push(format!(
+            "auth: ok (catalog_visibility); {} model(s)",
+            visible.len()
+        ));
+        if visible.is_empty() {
+            lines.push("No models matched --search.".to_string());
+        }
+        Ok(CmdResult::human(lines.join("\n")))
+    }
+}
+
+fn failure(args: &ModelsArgs, message: &str) -> CmdResult {
+    let value = json!({ "schema_version": "models.v1", "ok": false, "provider": "pi", "auth": "not_ready", "auth_basis": "catalog_visibility", "models": Value::Array(Vec::new()), "current_role_model": Value::Null, "error": message, "action": "install or repair the PATH-first `pi` executable, then retry `team-agent models --provider pi`" });
+    if args.json {
+        let text = serde_json::to_string_pretty(&value)
+            .unwrap_or_else(|_| "{\"schema_version\":\"models.v1\",\"ok\":false}".to_string());
+        CmdResult {
+            output: CmdOutput::Human(text),
+            exit: ExitCode::Error,
+            as_json: false,
+            preserve_json_order: true,
+        }
+    } else {
+        CmdResult { output: CmdOutput::Human(format!("models.v1 | error: {message}\naction: install or repair the PATH-first `pi` executable, then retry `team-agent models --provider pi`\nauth: not_ready (catalog_visibility)")), exit: ExitCode::Error, as_json: false, preserve_json_order: false }
+    }
+}
+
+fn safe_catalog_error(error: crate::provider::ProviderError) -> String {
+    let text = error.to_string();
+    if text.contains("not UTF-8") {
+        "Pi model catalog is not valid UTF-8".into()
+    } else if text.contains("duplicate") {
+        "Pi model catalog contains duplicate model ids".into()
+    } else if text.contains("header") {
+        "Pi model catalog has an unexpected header".into()
+    } else if text.contains("row") {
+        "Pi model catalog contains a malformed row".into()
+    } else if text.contains("empty") || text.contains("no models") {
+        "Pi model catalog is empty".into()
+    } else {
+        "Pi model catalog is invalid".into()
+    }
+}
+fn current_role_model(models: &[String]) -> Option<String> {
+    current_role_model_from(
+        models,
+        std::env::var("PI_PROVIDER").ok().as_deref(),
+        std::env::var("PI_MODEL").ok().as_deref(),
+    )
+}
+fn current_role_model_from(
+    models: &[String],
+    provider: Option<&str>,
+    model: Option<&str>,
+) -> Option<String> {
+    let exact = format!("{}/{}", provider?, model?);
+    models
+        .iter()
+        .any(|candidate| candidate == &exact)
+        .then_some(exact)
+}
+
+/// Injectable executable, deadline, and byte-limit boundary for deterministic tests.
+fn run_catalog(program: &Path, timeout: Duration, max_bytes: u64) -> Result<Vec<u8>, String> {
+    crate::lifecycle::launch::pi_mcp::run_pi_catalog(program, timeout, max_bytes)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::Instant;
+
+    #[cfg(unix)]
+    #[test]
+    fn real_dispatcher_child_helper() {
+        if std::env::var_os("TEAM_AGENT_MODELS_CHILD").is_none() {
+            return;
+        }
+        let args: Vec<String> =
+            serde_json::from_str(&std::env::var("TEAM_AGENT_MODELS_ARGS").unwrap()).unwrap();
+        print!("__TEAM_AGENT_MODELS_CLI_OUTPUT_v1__\n");
+        use std::io::Write;
+        std::io::stdout().flush().unwrap();
+        let exit = crate::cli::emit::run(&args, Path::new("/tmp"));
+        std::process::exit(exit.code());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn real_dispatcher_isolated_success_json_human_and_no_match() {
+        let pi = fixture("printf 'provider model\\nopenai-codex gpt-5.6-sol\\n'");
+        let dir = pi.parent().unwrap().to_path_buf();
+        let run_child = |args: &[&str], model: &str| {
+            std::process::Command::new(std::env::current_exe().unwrap())
+                .args([
+                    "--exact",
+                    "cli::models::tests::real_dispatcher_child_helper",
+                    "--nocapture",
+                ])
+                .env("TEAM_AGENT_MODELS_CHILD", "1")
+                .env(
+                    "TEAM_AGENT_MODELS_ARGS",
+                    serde_json::to_string(args).unwrap(),
+                )
+                .env("PATH", &dir)
+                .env("PI_PROVIDER", "openai-codex")
+                .env("PI_MODEL", model)
+                .output()
+                .unwrap()
+        };
+        let json = run_child(&["models", "--provider", "pi", "--json"], "gpt-5.6-sol");
+        assert!(json.status.success());
+        let output = String::from_utf8(json.stdout).unwrap();
+        let cli_output = output
+            .split("__TEAM_AGENT_MODELS_CLI_OUTPUT_v1__\n")
+            .nth(1)
+            .unwrap();
+        let value: Value = serde_json::from_str(cli_output.trim()).unwrap();
+        assert_eq!(value["schema_version"], "models.v1");
+        assert_eq!(value["models"][0]["role_model"], "openai-codex/gpt-5.6-sol");
+        assert_eq!(value["models"][0]["current"], true);
+        let human = run_child(
+            &["models", "--provider", "pi", "--search", "absent"],
+            "missing",
+        );
+        assert!(human.status.success());
+        let human_output = String::from_utf8(human.stdout).unwrap();
+        let text = human_output
+            .split("__TEAM_AGENT_MODELS_CLI_OUTPUT_v1__\n")
+            .nth(1)
+            .unwrap();
+        assert!(text.contains("No models matched --search") && text.contains("auth: ok"));
+        let null = run_child(&["models", "--provider", "pi", "--json"], "missing");
+        let null_output = String::from_utf8(null.stdout).unwrap();
+        let null_cli = null_output
+            .split("__TEAM_AGENT_MODELS_CLI_OUTPUT_v1__\n")
+            .nth(1)
+            .unwrap();
+        let null_value: Value = serde_json::from_str(null_cli.trim()).unwrap();
+        assert!(null.status.success() && null_value["current_role_model"].is_null());
+        std::fs::write(&pi, "#!/bin/sh\nprintf 'sensitive-stderr' >&2\nexit 7\n").unwrap();
+        let failed = run_child(&["models", "--provider", "pi", "--json"], "missing");
+        assert!(!failed.status.success());
+        let failed_output = String::from_utf8(failed.stdout).unwrap();
+        let failed_cli = failed_output
+            .split("__TEAM_AGENT_MODELS_CLI_OUTPUT_v1__\n")
+            .nth(1)
+            .unwrap();
+        assert!(!failed_cli.contains("sensitive-stderr"));
+        assert_eq!(
+            std::fs::read_to_string(pi.with_extension("count"))
+                .unwrap()
+                .lines()
+                .count(),
+            3
+        );
+        cleanup_fixture(&pi);
+    }
+
+    #[test]
+    fn current_model_is_deterministic() {
+        let models = vec!["openai-codex/gpt-5.6-sol".into()];
+        assert_eq!(
+            current_role_model_from(&models, Some("openai-codex"), Some("gpt-5.6-sol")),
+            Some("openai-codex/gpt-5.6-sol".into())
+        );
+        assert_eq!(
+            current_role_model_from(&models, Some("openai-codex"), Some("other")),
+            None
+        );
+        assert_eq!(
+            current_role_model_from(&models, None, Some("gpt-5.6-sol")),
+            None
+        );
+    }
+    #[cfg(unix)]
+    fn fixture(body: &str) -> std::path::PathBuf {
+        use std::os::unix::fs::PermissionsExt;
+        let root = std::env::current_exe()
+            .unwrap()
+            .parent()
+            .unwrap()
+            .join(format!(
+                "team-agent-pi-fixture-{}-{}",
+                std::process::id(),
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .unwrap()
+                    .as_nanos()
+            ));
+        std::fs::create_dir(&root).unwrap();
+        let path = root.join("pi");
+        std::fs::write(
+            &path,
+            format!("#!/bin/sh\nprintf '%s\\n' \"$#:$1\" >> \"$0.count\"\n{body}\n"),
+        )
+        .unwrap();
+        let mut permissions = std::fs::metadata(&path).unwrap().permissions();
+        permissions.set_mode(0o700);
+        std::fs::set_permissions(&path, permissions).unwrap();
+        path
+    }
+
+    #[cfg(unix)]
+    fn cleanup_fixture(path: &Path) {
+        let _ = std::fs::remove_dir_all(path.parent().unwrap());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn runner_invokes_exact_argv_once_and_drains() {
+        let path = fixture(
+            "test \"$1\" = --list-models && echo provider model && echo openai-codex gpt-5.6-sol",
+        );
+        assert!(run_catalog(&path, Duration::from_secs(1), 1024)
+            .unwrap()
+            .starts_with(b"provider model"));
+        assert_eq!(
+            std::fs::read_to_string(path.with_extension("count")).unwrap(),
+            "1:--list-models\n"
+        );
+        cleanup_fixture(&path);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn runner_timeout_is_bounded_when_descendant_keeps_stdout() {
+        let path = fixture("sleep 2 & exit 0");
+        let started = Instant::now();
+        let result = run_catalog(&path, Duration::from_millis(40), 1024);
+        assert!(started.elapsed() < Duration::from_millis(500));
+        assert!(result.unwrap_err().contains("timed out"));
+        cleanup_fixture(&path);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn command_boundary_connects_runner_parser_search_and_contract() {
+        let path = fixture(
+            "printf 'provider model\\nopenai-codex gpt-5.6-sol\\nopenai-codex gpt-5.6-luna\\n'",
+        );
+        let args = ModelsArgs {
+            provider: "pi".into(),
+            search: Some("sol".into()),
+            json: true,
+        };
+        let result = cmd_models_with(&args, &path, Duration::from_secs(1), 1024).unwrap();
+        let CmdOutput::Human(text) = result.output else {
+            panic!("expected JSON projection")
+        };
+        let value: Value = serde_json::from_str(&text).unwrap();
+        assert_eq!(value["schema_version"], "models.v1");
+        assert_eq!(value["models"][0]["role_model"], "openai-codex/gpt-5.6-sol");
+        assert_eq!(value["models"][0]["current"], false);
+        assert_eq!(value["auth"], "ok");
+        assert_eq!(value["models"].as_array().unwrap().len(), 1);
+        let human = cmd_models_with(
+            &ModelsArgs {
+                provider: "pi".into(),
+                search: Some("absent".into()),
+                json: false,
+            },
+            &path,
+            Duration::from_secs(1),
+            1024,
+        )
+        .unwrap();
+        let CmdOutput::Human(text) = human.output else {
+            panic!("expected human projection")
+        };
+        assert!(text.contains("No models matched --search") && text.contains("auth: ok"));
+        let refusal = crate::cli::emit::__test_dispatch(
+            "models",
+            &["--provider".into(), "codex".into()],
+            Path::new("/tmp"),
+        );
+        match refusal {
+            Err(CliError::Usage(message)) => {
+                assert_eq!(message, "models supports only --provider pi, got \"codex\"")
+            }
+            other => panic!("expected provider refusal, got {other:?}"),
+        }
+        cleanup_fixture(&path);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn runner_fails_closed_for_nonzero_oversize_timeout_and_unavailable() {
+        let fail = fixture("echo sensitive-token >&2; exit 7");
+        assert_eq!(
+            run_catalog(&fail, Duration::from_secs(1), 1024).unwrap_err(),
+            "Pi model catalog command failed"
+        );
+        let failed = cmd_models_with(
+            &ModelsArgs {
+                provider: "pi".into(),
+                search: None,
+                json: false,
+            },
+            &fail,
+            Duration::from_secs(1),
+            1024,
+        )
+        .unwrap();
+        let CmdOutput::Human(text) = failed.output else {
+            panic!("expected failure projection")
+        };
+        assert_eq!(failed.exit, ExitCode::Error);
+        assert!(!text.contains("sensitive-token"));
+        let big = fixture("head -c 64 /dev/zero");
+        assert!(run_catalog(&big, Duration::from_secs(1), 8)
+            .unwrap_err()
+            .contains("bounded output"));
+        let slow = fixture("sleep 2");
+        assert!(run_catalog(&slow, Duration::from_millis(20), 1024)
+            .unwrap_err()
+            .contains("timed out"));
+        assert!(run_catalog(
+            std::path::Path::new("/does/not/exist"),
+            Duration::from_secs(1),
+            1024
+        )
+        .unwrap_err()
+        .contains("unavailable"));
+        for path in [fail, big, slow] {
+            cleanup_fixture(&path);
+        }
+    }
+
+    #[test]
+    fn public_failure_and_help_contracts_are_versioned() {
+        let args = ModelsArgs {
+            provider: "pi".into(),
+            search: None,
+            json: true,
+        };
+        let result = failure(&args, "safe failure");
+        let CmdOutput::Human(text) = result.output else {
+            panic!("json contract must render")
+        };
+        let value: Value = serde_json::from_str(&text).unwrap();
+        assert_eq!(value["schema_version"], "models.v1");
+        assert_eq!(value["models"], Value::Array(vec![]));
+        assert_eq!(result.exit, ExitCode::Error);
+        assert!(crate::cli::emit::default_help().contains("models"));
+        assert_eq!(
+            crate::cli::run(&["models".into(), "--help".into()], Path::new("/tmp")),
+            ExitCode::Ok
+        );
+        assert_eq!(
+            crate::cli::run(
+                &["models".into(), "--provider".into(), "codex".into()],
+                Path::new("/tmp")
+            ),
+            ExitCode::Error
+        );
+        assert_eq!(
+            crate::cli::spec::command_spec("models").unwrap().usage,
+            "usage: team-agent models --provider pi [--search TEXT] [--json]"
+        );
+    }
+
+    #[test]
+    fn parser_contract_fixtures() {
+        let parse =
+            |input: &[u8]| crate::lifecycle::launch::pi_mcp::parse_pi_list_models_table(input);
+        assert_eq!(
+            parse(b"provider model\r\nopenai-codex gpt-5.6-sol\r\n").unwrap(),
+            vec!["openai-codex/gpt-5.6-sol"]
+        );
+        assert!(parse(b"provider model\n").is_err());
+        assert!(parse(b"provider model\na b\na b\n").is_err());
+        assert!(parse(b"wrong model\na b\n").is_err());
+        assert!(parse(b"provider model\na\n").is_err());
+        assert!(parse(&[b'p', b'r', 0xff]).is_err());
+    }
+}

package/crates/team-agent/src/cli/spec.rs

@@ -85,6 +85,7 @@ pub(crate) enum DispatchKind {
     E2e,
     Peek,
     Coordinator,
+    Models,
 }
 
 pub(crate) const ALL_DISPATCH_KINDS: &[DispatchKind] = &[
@@ -131,6 +132,7 @@ pub(crate) const ALL_DISPATCH_KINDS: &[DispatchKind] = &[
     DispatchKind::E2e,
     DispatchKind::Peek,
     DispatchKind::Coordinator,
+    DispatchKind::Models,
 ];
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -162,8 +164,9 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "quick-start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::QuickStart), summary: "start or attach a team from TEAM.md", usage: "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "persist a message for an in-team short name or fully-qualified logical recipient", usage: "usage: team-agent send TO MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--mailbox] [--json]\nTO forms are co-equal: an in-team short name (for example `team-agent send reviewer \"Review\"`) or `<workspace>::<team>/<agent>`.", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: Some("next compatibility release"), action: Some("use positional logical TO and the returned message id"), governance: None },
     CommandSpec { name: "status", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Status), summary: "show current team status", usage: "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "models", tier: CommandTier::Core, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Models), summary: "list exact provider model ids", usage: "usage: team-agent models --provider pi [--search TEXT] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "collect", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Collect), summary: "collect reported results", usage: "usage: team-agent collect [--workspace WORKSPACE] [--team TEAM] [--result-file FILE] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
-    CommandSpec { name: "results", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Results), summary: "read reported results for a case", usage: "usage: team-agent results --case CASE_ID [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "results", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Results), summary: "read reported results for a case", usage: "usage: team-agent results --case CASE_ID [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "wait", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Wait), summary: "block until a task result is stored", usage: "usage: team-agent wait --task TASK [--workspace WORKSPACE] [--json]", default_help: false, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "restart", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Restart), summary: "restart the selected team", usage: "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "shutdown", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Shutdown), summary: "stop the selected team", usage: "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },

package/crates/team-agent/src/cli/types.rs

@@ -638,6 +638,14 @@ pub struct LeadersArgs {
     pub json: bool,
 }
 
+/// Read-only Pi model catalog discovery.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ModelsArgs {
+    pub provider: String,
+    pub search: Option<String>,
+    pub json: bool,
+}
+
 /// `validate [spec=team.spec.yaml] --json`(`parser.py:120`)。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ValidateArgs {

package/crates/team-agent/src/compiler.rs

@@ -366,6 +366,114 @@ pub struct CompiledRole {
     pub agent: Value,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PiModelPreflightError {
+    pub requested: String,
+    pub candidates: Vec<String>,
+    pub action: String,
+    pub not_ready: bool,
+}
+
+impl std::fmt::Display for PiModelPreflightError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            formatter,
+            "Pi role model {:?} is not a qualified exact model",
+            self.requested
+        )
+    }
+}
+
+/// Shared admission gate: omitted and qualified models pass; only an
+/// unqualified present model causes one bounded catalog observation.
+pub fn preflight_pi_role_model(meta: &Value) -> Result<(), PiModelPreflightError> {
+    preflight_pi_role_model_with(meta, |requested| {
+        crate::lifecycle::launch::pi_mcp::pi_model_candidates(requested).map_err(|_| ())
+    })
+}
+
+pub fn preflight_pi_role_model_with<F>(
+    meta: &Value,
+    mut discover: F,
+) -> Result<(), PiModelPreflightError>
+where
+    F: FnMut(&str) -> Result<Vec<String>, ()>,
+{
+    if parse_canonical_provider(meta.get("provider").and_then(Value::as_str).unwrap_or(""))
+        != Some(Provider::Pi)
+    {
+        return Ok(());
+    }
+    let Some(model) = string_field(meta, "model").filter(|value| !value.trim().is_empty()) else {
+        return Ok(());
+    };
+    let requested = model.trim().to_string();
+    if requested.split_once('/').is_some_and(|(provider, name)| {
+        !provider.is_empty() && !name.is_empty() && !requested.contains('*')
+    }) {
+        return Ok(());
+    }
+    let (candidates, not_ready) = match discover(&requested) {
+        Ok(candidates) => (candidates, false),
+        Err(()) => (Vec::new(), true),
+    };
+    let action = if candidates.is_empty() {
+        format!("run `team-agent models --provider pi --search {requested}`")
+    } else {
+        format!("copy a candidate into the role, or run `team-agent models --provider pi --search {requested}`")
+    };
+    Err(PiModelPreflightError {
+        requested,
+        candidates,
+        action,
+        not_ready,
+    })
+}
+
+pub fn preflight_pi_models_in_team(team_dir: &Path) -> Result<(), PiModelPreflightError> {
+    preflight_pi_models_in_team_with(team_dir, |requested| {
+        crate::lifecycle::launch::pi_mcp::pi_model_candidates(requested).map_err(|_| ())
+    })
+}
+
+pub fn preflight_pi_models_in_team_with<F>(
+    team_dir: &Path,
+    mut discover: F,
+) -> Result<(), PiModelPreflightError>
+where
+    F: FnMut(&str) -> Result<Vec<String>, ()>,
+{
+    let agents_dir = team_dir.join("agents");
+    let entries = match std::fs::read_dir(&agents_dir) {
+        Ok(entries) => entries,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(_) => {
+            return Err(PiModelPreflightError {
+                requested: "<role directory>".into(),
+                candidates: Vec::new(),
+                action: "repair the role directory and retry".into(),
+                not_ready: true,
+            })
+        }
+    };
+    let mut paths = entries
+        .filter_map(Result::ok)
+        .map(|entry| entry.path())
+        .filter(|path| path.extension().and_then(|ext| ext.to_str()) == Some("md"))
+        .collect::<Vec<_>>();
+    paths.sort();
+    for path in paths {
+        let (meta, _) = read_front_matter(&path).map_err(|_| PiModelPreflightError {
+            requested: path.display().to_string(),
+            candidates: Vec::new(),
+            action: "repair the role document and retry".into(),
+            not_ready: true,
+        })?;
+        preflight_pi_role_model_with(&meta, &mut discover)?;
+    }
+    Ok(())
+}
+
 /// 把一份 role 文档编译成 agent spec 条目。`team_meta` 供 model/auth_mode 继承;
 /// `workspace_s` 是 working_directory。**纯读 `role_path`,无任何文件落地。**
 pub fn compile_role_agent(
@@ -696,6 +804,55 @@ fn int_field(meta: &Value, key: &str, default: i64) -> Value {
     }
 }
 
+#[cfg(test)]
+mod pi_preflight_tests {
+    use super::*;
+    use std::cell::Cell;
+
+    fn role(provider: &str, model: Option<&str>) -> Value {
+        let mut fields = vec![("provider".to_string(), Value::Str(provider.into()))];
+        if let Some(model) = model {
+            fields.push(("model".to_string(), Value::Str(model.into())));
+        }
+        Value::Map(fields)
+    }
+
+    #[test]
+    fn omitted_qualified_and_non_pi_do_not_discover() {
+        for meta in [role("pi", None), role("pi", Some("openai/gpt-5")), role("codex", Some("gpt-5"))] {
+            let calls = Cell::new(0);
+            assert!(preflight_pi_role_model_with(&meta, |_| {
+                calls.set(calls.get() + 1);
+                Ok(vec![])
+            }).is_ok());
+            assert_eq!(calls.get(), 0);
+        }
+    }
+
+    #[test]
+    fn unqualified_discovers_once_and_projects_candidates() {
+        let calls = Cell::new(0);
+        let error = preflight_pi_role_model_with(&role("pi", Some("gpt-5.6-sol")), |requested| {
+            calls.set(calls.get() + 1);
+            assert_eq!(requested, "gpt-5.6-sol");
+            Ok(vec!["openai-codex/gpt-5.6-sol".into(), "azure/gpt-5.6-sol".into()])
+        }).expect_err("unqualified model must fail closed");
+        assert_eq!(calls.get(), 1);
+        assert_eq!(error.candidates, vec!["openai-codex/gpt-5.6-sol", "azure/gpt-5.6-sol"]);
+        assert!(!error.not_ready);
+        assert!(error.action.contains("team-agent models --provider pi --search gpt-5.6-sol"));
+    }
+
+    #[test]
+    fn catalog_failure_is_not_ready_without_partial_candidates() {
+        let error = preflight_pi_role_model_with(&role("pi", Some("gpt-5.6-sol")), |_| Err(()))
+            .expect_err("catalog failure must reject");
+        assert!(error.not_ready);
+        assert!(error.candidates.is_empty());
+        assert!(!error.to_string().contains("stderr"));
+    }
+}
+
 fn py_int_value(value: &Value) -> Option<i64> {
     match value {
         Value::Bool(b) => Some(if *b { 1 } else { 0 }),