@team-agent/installer 0.5.113 → 0.5.115

package/crates/team-agent/src/contract_runtime/commands.rs

@@ -0,0 +1,245 @@
+//! Public lifecycle dispatch for contract seats. A private native pane is never
+//! operated through the legacy workspace socket or provider-enum fallback.
+use std::path::Path;
+
+use serde_json::{json, Value};
+use team_agent_contract::contract::types::SeatId;
+use team_agent_contract::orchestration::store::{Outcome, SeatStatus};
+use team_agent_contract::host::process::{sample_process, ProcessState};
+
+use crate::cli::CliError;
+use crate::lifecycle::lock::{acquire_agent_lifecycle_lock, LifecycleLockRequest};
+use crate::model::ids::AgentId;
+use crate::state::repository::{StateRepository, StateWriteIntent};
+use crate::state::selector::{resolve_active_team_readonly, SelectedTeam, SelectorMode};
+
+use super::{backend::{self, Backend, BackendError}, config, framework};
+
+fn error(error: impl std::fmt::Display) -> CliError {
+    CliError::Runtime(error.to_string())
+}
+
+/// None delegates only a non-contract selection. Once selected, any identity,
+/// ownership, state or physical error stays on this route and cannot fall back.
+fn with_agent(
+    workspace: &Path,
+    team: Option<&str>,
+    agent: &str,
+    operation: &'static str,
+    apply: impl FnOnce(&SelectedTeam, &SeatId) -> Result<Value, CliError>,
+) -> Result<Option<Value>, CliError> {
+    let Ok(selected) = resolve_active_team_readonly(workspace, team, SelectorMode::RuntimeOnly) else {
+        return Ok(None);
+    };
+    if !selected.state.get("agents").and_then(|agents| agents.get(agent)).is_some_and(framework::is_contract) {
+        return Ok(None);
+    }
+    let agent_id = AgentId::new(agent);
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &selected.run_workspace,
+        operation,
+        team: Some(&selected.team_key),
+        agent_id: Some(&agent_id),
+    }).map_err(error)?;
+    let latest = resolve_active_team_readonly(
+        &selected.run_workspace, Some(&selected.team_key), SelectorMode::RuntimeOnly,
+    ).map_err(error)?;
+    crate::lifecycle::launch::ensure_owner_allowed_for_state(&latest.state, Some(&agent_id)).map_err(error)?;
+    if !latest.state.get("agents").and_then(|agents| agents.get(agent)).is_some_and(framework::is_contract) {
+        return Err(CliError::Runtime("contract seat changed while acquiring lifecycle ownership".into()));
+    }
+    apply(&latest, &SeatId::new(agent).map_err(error)?).map(Some)
+}
+
+fn publish(selected: &SelectedTeam, id: &SeatId) -> Result<Value, CliError> {
+    publish_at(&selected.run_workspace, &selected.team_key, id)
+}
+fn publish_at(workspace: &Path, team: &str, id: &SeatId) -> Result<Value, CliError> {
+    let projected = framework::project_seat(workspace, team, id.as_str()).map_err(error)?;
+    StateRepository::new(workspace).commit(
+        StateWriteIntent::StartAgent { team_key: team, agent_id: id.as_str() },
+        |state| {
+            if let Some(row) = state.get_mut("agents").and_then(|agents| agents.get_mut(id.as_str())).and_then(Value::as_object_mut) {
+                for (key, value) in projected.as_object().expect("native projection object") {
+                    row.insert(key.clone(), value.clone());
+                }
+                row.insert("paused".into(), Value::Bool(false));
+            }
+        },
+    ).map_err(error)?;
+    Ok(projected)
+}
+
+fn check_record(receipt: &team_agent_contract::orchestration::store::OperationRecord) -> Result<(), CliError> {
+    if receipt.outcome != Outcome::Committed {
+        return Err(error(BackendError::Shutdown {
+            operation: receipt.id.clone(), phase: receipt.phase, outcome: receipt.outcome, failure: receipt.failure.clone(),
+        }));
+    }
+    Ok(())
+}
+
+pub fn start_agent(
+    workspace: &Path,
+    team: Option<&str>,
+    agent: &str,
+    patch: &crate::lifecycle::role_config::RoleConfigPatch,
+) -> Result<Option<Value>, CliError> {
+    with_agent(workspace, team, agent, "start-agent", |selected, id| {
+        let args = crate::cli::QuickStartArgs {
+            workspace: selected.run_workspace.clone(), agents_dir: selected.team_dir.clone(),
+            name: None, team_id: Some(selected.team_key.clone()), yes: false, json: false,
+            detail: false, backend: Some("tmux".into()),
+        };
+        // Contract configuration, not a stale legacy dynamic_role_file, is the
+        // authoritative source. Never patch an unrelated external role file.
+        let original = config::read_team(&args).map_err(error)?.ok_or(BackendError::Metadata).map_err(error)?;
+        let source = original.roles.iter().find(|role| &role.id == id)
+            .ok_or(BackendError::Metadata).map_err(error)?.source.clone();
+        let previous = std::fs::read_to_string(&source).map_err(error)?;
+        let next = crate::lifecycle::role_config::patched_role(&previous, &AgentId::new(agent), patch, false).map_err(error)?;
+        let config = config::read_team_with_role_override(&args, &source, &next).map_err(error)?.ok_or(BackendError::Metadata).map_err(error)?;
+        let role = config.roles.iter().find(|role| &role.id == id).ok_or(BackendError::Metadata).map_err(error)?;
+        let row = selected.state.get("agents").and_then(|agents| agents.get(agent)).ok_or(BackendError::Metadata).map_err(error)?;
+        if row.get("provider").and_then(Value::as_str) != Some(role.provider.as_str()) {
+            return Err(error("provider change requires a new seat identity"));
+        }
+        if role.paused {
+            return Ok(json!({"ok":false,"agent_id":agent,"status":"paused","reason":"agent_paused"}));
+        }
+        let unstarted = framework::is_paused_unstarted(row);
+        let prepared = if unstarted {
+            // Full pure team admission precedes native allocation or role writes.
+            backend::preflight(&config).map_err(error)?;
+            None
+        } else {
+            let backend = Backend::open_readonly(&selected.run_workspace, &selected.team_key).map_err(error)?;
+            let seat = backend.store.seat(id).map_err(error)?.ok_or(BackendError::Metadata).map_err(error)?;
+            if seat.status == SeatStatus::Unknown {
+                return Err(error("native seat state is unknown; explicit reconciliation required"));
+            }
+            if seat.status != SeatStatus::Stopped && seat.physical.as_ref().is_some_and(|target| sample_process(&target.process) == ProcessState::Alive) {
+                return Err(error("native seat is already running; use stop-agent first"));
+            }
+            Some(backend::prepare_resume(&selected.run_workspace, &selected.team_key, id, Some(role)).map_err(error)?)
+        };
+        crate::lifecycle::role_config::commit_contract_role(&source, &previous, &next).map_err(error)?;
+        let receipt = match prepared {
+            Some(prepared) => backend::resume(prepared).map_err(error)?,
+            None => backend::start(&selected.run_workspace, &selected.team_key, role, &config.members).map_err(error)?.1,
+        };
+        // An uncertain operation never rolls the authoritative native store back
+        // to the old generation. The receipt remains available for recovery.
+        let projection = publish(selected, id)?;
+        check_record(&receipt)?;
+        let coordinator = crate::coordinator::start_coordinator_with_team(
+            &crate::coordinator::WorkspacePath::new(selected.run_workspace.clone()), Some(&selected.team_key),
+        ).map_err(error)?;
+        Ok(json!({"ok":coordinator.ok,"agent_id":agent,"status":"running","runtime":"contract",
+            "start_mode":if unstarted {"fresh"} else {"resumed"}, "operation":receipt.id,
+            "session_id":projection.get("session_id"),"generation":projection.get("generation"),
+            "coordinator":crate::lifecycle::coordinator_start_summary_value(
+                &crate::lifecycle::CoordinatorStartSummary::from_start_report(&coordinator))}))
+    })
+}
+
+pub(crate) struct NativeRestartResult {
+    pub agent_id: String,
+    pub session_id: Option<String>,
+    pub outcome: Result<(), String>,
+}
+
+/// Called with the ordinary workspace lifecycle lock already held. Native
+/// panes never enter legacy transport spawn, backing scan or shared teardown.
+pub(crate) fn restart_prepared(
+    workspace: &Path,
+    team: &str,
+    state: &mut Value,
+    prepared: Vec<backend::PreparedResume>,
+) -> Vec<NativeRestartResult> {
+    prepared.into_iter().map(|prepared| {
+        let id = prepared.seat().clone();
+        let session_id = prepared.session().map(str::to_owned);
+        let outcome = (|| {
+            let receipt = backend::resume(prepared).map_err(error)?;
+            let projection = publish_at(workspace, team, &id)?;
+            if let Some(row) = state.get_mut("agents").and_then(|agents| agents.get_mut(id.as_str())).and_then(Value::as_object_mut) {
+                for (key, value) in projection.as_object().expect("native projection object") {
+                    row.insert(key.clone(), value.clone());
+                }
+            }
+            check_record(&receipt)
+        })().map_err(|error| error.to_string());
+        NativeRestartResult { agent_id: id.as_str().into(), session_id, outcome }
+    }).collect()
+}
+
+pub fn restart(workspace: &Path, team: Option<&str>) -> Result<Option<Value>, CliError> {
+    let Ok(selected) = resolve_active_team_readonly(workspace, team, SelectorMode::RuntimeOnly) else {
+        return Ok(None);
+    };
+    if !framework::only_contract(&selected.state) { return Ok(None); }
+    let _lock = acquire_agent_lifecycle_lock(LifecycleLockRequest {
+        workspace: &selected.run_workspace, operation: "restart",
+        team: Some(&selected.team_key), agent_id: None,
+    }).map_err(error)?;
+    let latest = resolve_active_team_readonly(&selected.run_workspace, Some(&selected.team_key), SelectorMode::RuntimeOnly).map_err(error)?;
+    crate::lifecycle::launch::ensure_owner_allowed_for_state(&latest.state, None).map_err(error)?;
+    if !framework::only_contract(&latest.state) { return Err(error("native team changed while acquiring lifecycle ownership")); }
+    let prepared = backend::prepare_restart(&latest.run_workspace, &latest.team_key, &latest.team_dir, &latest.state).map_err(error)?;
+    let mut state = latest.state.clone();
+    let results = restart_prepared(&latest.run_workspace, &latest.team_key, &mut state, prepared);
+    let succeeded: Vec<_> = results.iter().filter(|result| result.outcome.is_ok()).map(|result| json!({
+        "agent_id":result.agent_id,"restart_mode":"resumed","session_id":result.session_id,
+    })).collect();
+    let failed: Vec<_> = results.iter().filter_map(|result| result.outcome.as_ref().err().map(|error| json!({
+        "agent_id":result.agent_id,"phase":"native_resume","error":error,
+    }))).collect();
+    let coordinator = crate::coordinator::start_coordinator_with_team(
+        &crate::coordinator::WorkspacePath::new(latest.run_workspace.clone()), Some(&latest.team_key),
+    ).map_err(error)?;
+    Ok(Some(json!({"ok":failed.is_empty() && coordinator.ok,"runtime":"contract",
+        "status":if failed.is_empty() {"restarted"} else if succeeded.is_empty() {"failed"} else {"partial"},
+        "team_id":latest.team_key,"agents":succeeded,"failed_agents":failed,
+        "coordinator":crate::lifecycle::coordinator_start_summary_value(
+            &crate::lifecycle::CoordinatorStartSummary::from_start_report(&coordinator))})))
+}
+
+pub fn stop_agent(
+    workspace: &Path,
+    team: Option<&str>,
+    agent: &str,
+) -> Result<Option<Value>, CliError> {
+    with_agent(workspace, team, agent, "stop-agent", |selected, id| {
+        if selected.state.get("agents").and_then(|agents| agents.get(agent)).is_some_and(framework::is_paused_unstarted) {
+            return Ok(json!({"ok":true,"agent_id":agent,"stopped":false,"status":"paused","runtime":"contract"}));
+        }
+        let backend = Backend::open_readonly(&selected.run_workspace, &selected.team_key).map_err(error)?;
+        let seat = backend.store.seat(id).map_err(error)?.ok_or(BackendError::Metadata).map_err(error)?;
+        let already_stopped = seat.status == SeatStatus::Stopped;
+        drop(backend);
+        let operation = if already_stopped {
+            None
+        } else {
+            let receipt = backend::stop(&selected.run_workspace, &selected.team_key, id).map_err(error)?;
+            if receipt.outcome != Outcome::Committed {
+                return Err(error(BackendError::Shutdown {
+                    operation: receipt.id, phase: receipt.phase, outcome: receipt.outcome, failure: receipt.failure,
+                }));
+            }
+            Some(receipt.id)
+        };
+        let projected = framework::project_seat(&selected.run_workspace, &selected.team_key, id.as_str()).map_err(error)?;
+        let mut state = selected.state.clone();
+        let row = state.get_mut("agents").and_then(|agents| agents.get_mut(agent)).and_then(Value::as_object_mut).ok_or(BackendError::Metadata).map_err(error)?;
+        for (key, value) in projected.as_object().expect("native projection object") {
+            row.insert(key.clone(), value.clone());
+        }
+        StateRepository::new(&selected.run_workspace).save(
+            StateWriteIntent::StopAgent { team_key: &selected.team_key, agent_id: agent }, &state,
+        ).map_err(error)?;
+        Ok(json!({"ok":true,"agent_id":agent,"stopped":!already_stopped,
+            "status":if already_stopped {"already_stopped"} else {"stopped"},
+            "runtime":"contract","operation":operation}))
+    })
+}

package/crates/team-agent/src/contract_runtime/config.rs

@@ -0,0 +1,340 @@
+//! Read-only per-agent routing/preflight. Contract roles opt in independently;
+//! other roles keep the legacy engine, including in the same logical team.
+#[cfg(test)]
+#[path = "config_tests.rs"]
+mod tests;
+use std::collections::BTreeSet;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use team_agent_contract::contract::{
+    session::CwdIdentity,
+    types::{ProviderId, ScopeId, SeatId},
+};
+use team_agent_contract::host::{digest, digest_hex, process::resolve_cwd};
+use thiserror::Error;
+
+use super::prompt::{self, Prompt, Source};
+use crate::cli::QuickStartArgs;
+use crate::communication_mode::CommunicationMode;
+use crate::compiler::split_front_matter;
+use crate::model::yaml::Value;
+
+#[derive(Debug, Error)]
+pub enum ConfigError {
+    #[error("invalid contract configuration field {field} in {path:?}")]
+    Invalid { path: PathBuf, field: &'static str },
+    #[error("contract runtime capability is not available: {0}")]
+    Unsupported(&'static str),
+    #[error("contract configuration I/O: {0}")]
+    Io(#[from] std::io::Error),
+}
+
+// Prompts intentionally have no Debug implementation and are never diagnostics.
+#[derive(Clone, Serialize, Deserialize)]
+pub struct RoleConfig {
+    pub id: SeatId,
+    pub provider: ProviderId,
+    pub source: PathBuf,
+    pub role: String,
+    pub model: String,
+    pub effort: Option<String>,
+    pub bypass: bool,
+    #[serde(default)]
+    pub paused: bool,
+    pub body: String,
+    pub prompt: Prompt,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum RuntimeFamily {
+    Legacy,
+    Contract,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MemberRoute {
+    pub id: String,
+    pub provider: String,
+    pub source: PathBuf,
+    pub runtime: RuntimeFamily,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct TeamConfig {
+    pub selector: String,
+    pub label: String,
+    pub scope: ScopeId,
+    pub team_dir: PathBuf,
+    pub workspace: CwdIdentity,
+    pub objective: String,
+    pub members: Vec<MemberRoute>,
+    /// Only contract roles; the legacy member definitions are not rewritten.
+    pub roles: Vec<RoleConfig>,
+}
+
+fn invalid(path: &Path, field: &'static str) -> ConfigError {
+    ConfigError::Invalid {
+        path: path.into(),
+        field,
+    }
+}
+fn text(meta: &Value, field: &'static str, path: &Path) -> Result<Option<String>, ConfigError> {
+    match meta.get(field) {
+        None | Some(Value::Null) => Ok(None),
+        Some(Value::Str(value)) if !value.trim().is_empty() && !value.contains('\0') => {
+            Ok(Some(value.clone()))
+        }
+        _ => Err(invalid(path, field)),
+    }
+}
+fn required(meta: &Value, field: &'static str, path: &Path) -> Result<String, ConfigError> {
+    text(meta, field, path)?.ok_or_else(|| invalid(path, field))
+}
+fn mode(meta: &Value, path: &Path) -> Result<Option<CommunicationMode>, ConfigError> {
+    text(meta, "communication_mode", path)?
+        .map(|value| {
+            CommunicationMode::parse(&value).ok_or_else(|| invalid(path, "communication_mode"))
+        })
+        .transpose()
+}
+
+/// A malformed explicit contract header cannot fall back to the default Pi worker.
+fn malformed_contract_header(body: &str) -> bool {
+    body.strip_prefix("---\n").is_some_and(|header| {
+        header
+            .lines()
+            .take_while(|line| *line != "---")
+            .any(|line| {
+                line.split_once(':').is_some_and(|(key, value)| {
+                    key.trim() == "provider"
+                        && super::registry::recognizes(
+                            value
+                                .split('#')
+                                .next()
+                                .unwrap_or("")
+                                .trim()
+                                .trim_matches(['\'', '"']),
+                        )
+                })
+            })
+    })
+}
+
+/// None delegates exactly to the existing legacy/leader-only path. No native
+/// command, model probe, config write or process is created by this selection.
+pub fn read_team(args: &QuickStartArgs) -> Result<Option<TeamConfig>, ConfigError> {
+    read_team_with_user_source(args, prompt::user_source)
+}
+
+/// A unified framework user-policy source can be injected without making the
+/// provider know its storage location. Tests use this port instead of real HOME.
+pub fn read_team_with_user_source(
+    args: &QuickStartArgs,
+    user_source: impl FnOnce() -> Result<Option<Source>, ConfigError>,
+) -> Result<Option<TeamConfig>, ConfigError> {
+    read_team_inner(args, user_source, None)
+}
+
+/// Compile an admitted role-document change without first writing any file.
+pub(crate) fn read_team_with_role_override(
+    args: &QuickStartArgs,
+    path: &Path,
+    contents: &str,
+) -> Result<Option<TeamConfig>, ConfigError> {
+    read_team_inner(args, prompt::user_source, Some((path, contents)))
+}
+
+fn read_team_inner(
+    args: &QuickStartArgs,
+    user_source: impl FnOnce() -> Result<Option<Source>, ConfigError>,
+    role_override: Option<(&Path, &str)>,
+) -> Result<Option<TeamConfig>, ConfigError> {
+    let agents = args.agents_dir.join("agents");
+    let entries = match std::fs::read_dir(&agents) {
+        Ok(entries) => entries,
+        Err(_) => return Ok(None),
+    };
+    let mut paths = Vec::new();
+    for entry in entries {
+        let entry = entry?;
+        let path = entry.path();
+        if path.extension().and_then(|s| s.to_str()) == Some("md") {
+            paths.push(path);
+        }
+    }
+    paths.sort();
+    let mut roles = Vec::new();
+    let mut selected = false;
+    for path in paths {
+        let raw = match role_override.filter(|(source, _)| path.canonicalize().ok().as_deref() == Some(*source)) {
+            Some((_, contents)) => contents.to_owned(),
+            None => match std::fs::read_to_string(&path) {
+            Ok(raw) => raw,
+            Err(error) if selected => return Err(error.into()),
+            Err(_) => return Ok(None), // let the legacy compiler report its existing I/O error
+            },
+        };
+        let (meta, body) = split_front_matter(&raw);
+        let normalized = raw.replace("\r\n", "\n").replace('\r', "\n");
+        if meta.get("provider").is_none() && malformed_contract_header(&normalized) {
+            return Err(invalid(&path, "front matter"));
+        }
+        if meta
+            .get("provider")
+            .and_then(Value::as_str)
+            .is_some_and(super::registry::recognizes)
+        {
+            selected = true;
+        }
+        roles.push((path, raw, meta, body));
+    }
+    if !selected {
+        return Ok(None);
+    }
+    if args
+        .backend
+        .as_deref()
+        .is_some_and(|backend| backend != "tmux")
+    {
+        return Err(ConfigError::Unsupported(
+            "contract native transport requires tmux",
+        ));
+    }
+    let team_dir = args.agents_dir.canonicalize()?;
+    let team_path = team_dir.join("TEAM.md");
+    let team_source = Source::read(&team_path)?;
+    let (team_meta, team_body) = split_front_matter(&team_source.contents);
+    let label = args
+        .name
+        .clone()
+        .or(text(&team_meta, "name", &team_path)?)
+        .or_else(|| {
+            team_dir
+                .file_name()
+                .and_then(|s| s.to_str())
+                .map(str::to_owned)
+        })
+        .ok_or_else(|| invalid(&team_path, "name"))?;
+    let selector = args.team_id.clone().unwrap_or_else(|| label.clone());
+    if selector.trim().is_empty() || selector.chars().any(char::is_control) {
+        return Err(invalid(&team_path, "team selector"));
+    }
+    let workspace =
+        resolve_cwd(&args.workspace).map_err(|_| invalid(&args.workspace, "workspace identity"))?;
+    let key =
+        serde_json::to_vec(&(&workspace, &selector)).map_err(|_| invalid(&team_path, "scope"))?;
+    let scope = ScopeId::new(format!("contract-{}", &digest_hex(digest(&key))[..32]))
+        .map_err(|_| invalid(&team_path, "scope"))?;
+    let objective = text(&team_meta, "objective", &team_path)?.unwrap_or(team_body);
+    let user = user_source()?;
+    let project = prompt::project_source(&workspace.path)?;
+    let team_instructions = prompt::team_sources(&team_source, &team_meta)?;
+    let team_mode = mode(&team_meta, &team_path)?.unwrap_or_default();
+    let mut ids = BTreeSet::new();
+    let mut compiled = Vec::new();
+    let mut members = Vec::new();
+    for (source, raw, meta, body) in roles {
+        let id = text(&meta, "agent_id", &source)?
+            .or(text(&meta, "name", &source)?)
+            .or_else(|| {
+                source
+                    .file_stem()
+                    .and_then(|s| s.to_str())
+                    .map(str::to_owned)
+            })
+            .ok_or_else(|| invalid(&source, "agent id"))?;
+        if !ids.insert(id.clone()) {
+            return Err(invalid(&source, "duplicate agent id"));
+        }
+        let provider = text(&meta, "provider", &source)?.unwrap_or_else(|| "pi".into());
+        let registration = super::registry::descriptor(&provider);
+        if registration.is_none() && super::registry::recognizes(&provider) {
+            return Err(invalid(&source, "provider"));
+        }
+        let runtime = if registration.is_some() {
+            RuntimeFamily::Contract
+        } else {
+            RuntimeFamily::Legacy
+        };
+        members.push(MemberRoute {
+            id: id.clone(),
+            provider: registration.map_or(provider, |descriptor| descriptor.identity.id.into()),
+            source: source.canonicalize()?,
+            runtime,
+        });
+        let Some(registration) = registration else {
+            continue;
+        };
+        let provider =
+            ProviderId::new(registration.identity.id).map_err(|_| invalid(&source, "provider"))?;
+        let id = SeatId::new(id).map_err(|_| invalid(&source, "agent id"))?;
+        if id.as_str() == "leader" {
+            return Err(invalid(&source, "reserved worker id"));
+        }
+        if text(&meta, "auth_mode", &source)?.is_some_and(|value| value != "subscription")
+            || text(&meta, "profile", &source)?.is_some()
+        {
+            return Err(ConfigError::Unsupported(
+                "contract native providers use an existing subscription; API/profile mappings are unavailable",
+            ));
+        }
+        let bypass = match meta.get("dangerously_skip_permissions") {
+            None => false,
+            Some(Value::Bool(value)) => *value,
+            _ => return Err(invalid(&source, "dangerously_skip_permissions")),
+        };
+        let paused = match meta.get("paused") {
+            None => false,
+            Some(Value::Bool(value)) => *value,
+            _ => return Err(invalid(&source, "paused")),
+        };
+        if body.trim().is_empty() || body.contains('\0') {
+            return Err(invalid(&source, "role body"));
+        }
+        if ["args", "cli_args"]
+            .iter()
+            .any(|field| meta.get(field).is_some())
+        {
+            return Err(ConfigError::Unsupported(
+                "unregistered native arguments cannot override the managed launch plan",
+            ));
+        }
+        let role = text(&meta, "role", &source)?.unwrap_or_else(|| id.as_str().into());
+        let document = Source {
+            path: source.canonicalize()?,
+            contents: raw,
+        };
+        let prompt = prompt::assemble(
+            id.as_str(),
+            &role,
+            mode(&meta, &source)?.unwrap_or(team_mode),
+            user.as_ref(),
+            project.as_ref(),
+            &document,
+            &team_instructions,
+        )?;
+        compiled.push(RoleConfig {
+            id,
+            provider,
+            source: document.path,
+            role,
+            model: required(&meta, "model", &source)?,
+            effort: text(&meta, "effort", &source)?,
+            bypass,
+            paused,
+            body,
+            prompt,
+        });
+    }
+    Ok(Some(TeamConfig {
+        selector,
+        label,
+        scope,
+        team_dir,
+        workspace,
+        objective,
+        members,
+        roles: compiled,
+    }))
+}

package/crates/team-agent/src/contract_runtime/config_tests.rs

@@ -0,0 +1,56 @@
+use super::*;
+use std::os::unix::fs::DirBuilderExt;
+
+struct Fixture { root: PathBuf, args: QuickStartArgs, role: PathBuf }
+impl Fixture {
+    fn new() -> Self {
+        let root = std::env::temp_dir().join(format!("contract-override-{}-{}", std::process::id(),
+            std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()));
+        std::fs::DirBuilder::new().mode(0o700).create(&root).unwrap();
+        let directory = root.join("roles");
+        std::fs::create_dir_all(directory.join("agents")).unwrap();
+        std::fs::write(directory.join("TEAM.md"), "---\nname: test\n---\nBounded fixture\n").unwrap();
+        let role = directory.join("agents/worker.md");
+        std::fs::write(&role, "---\nprovider: cursor\nmodel: old-model\n---\nOld instructions\n").unwrap();
+        let args = QuickStartArgs { workspace: root.clone(), agents_dir: directory, name: None,
+            team_id: None, yes: false, json: false, detail: false, backend: Some("tmux".into()) };
+        Self { root, args, role }
+    }
+}
+impl Drop for Fixture { fn drop(&mut self) { let _ = std::fs::remove_dir_all(&self.root); } }
+
+#[test]
+fn virtual_role_change_is_readonly_and_binds_new_instruction_digest() {
+    let fixture = Fixture::new();
+    let before = std::fs::read(&fixture.role).unwrap();
+    let path = fixture.role.canonicalize().unwrap();
+    let contents = "---\nprovider: cursor\nmodel: new-model\n---\nNew instructions\n";
+    let original = read_team_inner(&fixture.args, || Ok(None), None).unwrap().unwrap();
+    let changed = read_team_inner(&fixture.args, || Ok(None), Some((&path, contents))).unwrap().unwrap();
+    assert_eq!(changed.roles[0].model, "new-model");
+    assert_eq!(changed.roles[0].body, "New instructions\n");
+    assert_ne!(changed.roles[0].prompt.sha256, original.roles[0].prompt.sha256);
+    assert_eq!(std::fs::read(&fixture.role).unwrap(), before);
+    assert!(!fixture.root.join(".team").exists());
+    assert!(!fixture.root.join(".cursor").exists());
+}
+
+#[test]
+fn virtual_api_profile_is_refused_without_file_effects() {
+    let fixture = Fixture::new();
+    let before = std::fs::read(&fixture.role).unwrap();
+    let path = fixture.role.canonicalize().unwrap();
+    let contents = "---\nprovider: cursor\nmodel: new-model\nprofile: unsupported\n---\nInstructions\n";
+    assert!(matches!(read_team_inner(&fixture.args, || Ok(None), Some((&path, contents))), Err(ConfigError::Unsupported(_))));
+    assert_eq!(std::fs::read(&fixture.role).unwrap(), before);
+    assert!(!fixture.root.join(".team").exists());
+}
+
+#[test]
+fn virtual_role_override_cannot_match_a_different_source() {
+    let fixture = Fixture::new();
+    let other = fixture.root.join("other.md");
+    let contents = "---\nprovider: cursor\nmodel: wrong-model\n---\nOther\n";
+    let config = read_team_inner(&fixture.args, || Ok(None), Some((&other, contents))).unwrap().unwrap();
+    assert_eq!(config.roles[0].model, "old-model");
+}