@team-agent/installer 0.2.11 → 0.3.1

package/crates/team-agent/src/lifecycle/mod.rs

@@ -0,0 +1,62 @@
+//! step 13 · lifecycle — team 进程级生命周期编排器(ROUND-0.5 骨架)。
+//!
+//! 真相源 `team-agent-public` @ v0.2.11 (439bef8),只读。Card:
+//! `docs/phase0/subsystems/13-lifecycle.md`。
+//!
+//! Python 源:
+//! - `launch/core.py`(`launch`)、`launch/bootstrap.py`/`config.py`/`requirements.py`。
+//! - `lifecycle/start.py`(`start_agent`)、`lifecycle/operations.py`
+//!   (`stop_agent`/`reset_agent`/`add_agent`/`fork_agent`)、`lifecycle/agents.py`
+//!   (`remove_agent` + `_RemoveRollback`)、`lifecycle/paste_buffer_hygiene.py`。
+//! - `restart/orchestration.py`(`restart` Route B)、`restart/selection.py`、`restart/snapshot.py`。
+//! - `display/backend.py`/`adaptive.py`/`tiling.py`/`workspace.py`/`worker_window.py`/
+//!   `ghostty.py`/`close.py`/`rebuild.py`。
+//! - `orchestrator/__init__.py`/`plan.py`/`state.py`(plan 多 stage 状态机)。
+//! - `diagnose/quick_start.py`(`quick_start`/`prepare_quick_start_team`/`wait_ready`)。
+//!
+//! 价值:把下层原语(transport step9 / provider step8 / leader step10 / messaging step11 /
+//! state step5 / coordinator step12 / compiler step6)编排成**原子的、可回滚的、可审计的**
+//! 用户级动作。本 module 不拥有底层原语,只**调用**它们。
+//!
+//! § 锁(机械化,leader 集成时上 `#![deny(unwrap/expect/panic)]`):本 module 调
+//! `save_runtime_state`/`save_team_runtime_snapshot`/`save_plan_state`(`os.replace` 路径,
+//! bug-084 高危)—— 所有写路径强制 `Result`,`EACCES/EPERM/EBUSY` 退避重试,绝不 unwrap。
+//! § lifecycle **构造** provider 命令字符串经 step8 `ProviderAdapter` trait,**绝不**链接
+//! provider client crate(anthropic/openai SDK)。
+//!
+//! ROUND-0.5:数据类型 + 行为入口 fn 签名齐备,body = `unimplemented!("step13 port: ...")`。
+//! contracts blitz 可 NAME 这些类型并 CALL 这些 fn、断言其 rich return。
+
+// ROUND-0 skeleton:fn body 全 unimplemented!() → import/field/param/大 Err 暂未落地;P2 porter 实现时移除。
+#![allow(dead_code, unused_imports, unused_variables, clippy::result_large_err, clippy::doc_overindented_list_items, clippy::doc_lazy_continuation, clippy::io_other_error)]
+// §10:lifecycle 写路径(save_runtime_state/snapshot/plan_state,bug-084 高危)实现层禁 unwrap/expect/panic
+// (unimplemented!() stub 不被拦);tests 子模块各自 allow。
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+pub mod display;
+pub mod helpers;
+pub mod launch;
+pub mod restart;
+pub mod types;
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use crate::model::ids::AgentId;
+use crate::provider::{RolloutPath, SessionId};
+use crate::transport::{PaneId, SessionName, WindowName};
+
+// 复用既有 enum(model::enums)。`DisplayBackend` 已在 step2 定义并带 `has_worker_views()`。
+pub use crate::model::enums::DisplayBackend;
+
+pub use types::*;
+
+pub use display::*;
+pub use launch::*;
+pub use restart::*;
+
+pub use helpers::save_team_runtime_snapshot;
+pub(crate) use helpers::{plan_lock_path, plan_state_path, read_plan_state, save_plan_state};
+
+#[cfg(test)]
+mod tests;

package/crates/team-agent/src/lifecycle/restart/agent.rs

@@ -0,0 +1,533 @@
+use super::*;
+use super::common::*;
+use super::selection::decide_start_mode;
+use super::team_state::write_team_state;
+
+/// `start_agent(workspace, agent_id, force, open_display, allow_fresh, team)`
+/// (`lifecycle/start.py:72`)。`_runtime_lock("start-agent")` 下串行:resume-or-fresh
+/// 决策、resume 窗口退出回退 fresh、起后投递 pending message、起 coordinator。
+/// bug-085:`(session_id, rollout_path)` 四象限穷尽 match,缺 rollout 的 codex 仅在
+/// allow_fresh 时回退 fresh。
+pub fn start_agent(
+    workspace: &Path,
+    agent_id: &AgentId,
+    force: bool,
+    open_display: bool,
+    allow_fresh: bool,
+    team: Option<&str>,
+) -> Result<StartAgentOutcome, LifecycleError> {
+    let paths = lifecycle_paths(workspace, team)?;
+    start_agent_at_paths(
+        &paths.run_workspace,
+        &paths.spec_workspace,
+        agent_id,
+        force,
+        open_display,
+        allow_fresh,
+        team,
+        &crate::tmux_backend::TmuxBackend::for_workspace(&paths.run_workspace),
+    )
+}
+
+/// `start_agent` with an injected transport — wires the single-worker resume/fresh spawn +
+/// start_coordinator (rt-host-a sweep: was a stub returning RequirementUnmet at the spawn boundary).
+#[allow(clippy::too_many_arguments)]
+pub fn start_agent_with_transport(
+    workspace: &Path,
+    agent_id: &AgentId,
+    force: bool,
+    open_display: bool,
+    allow_fresh: bool,
+    team: Option<&str>,
+    transport: &dyn crate::transport::Transport,
+) -> Result<StartAgentOutcome, LifecycleError> {
+    start_agent_at_paths(
+        workspace,
+        workspace,
+        agent_id,
+        force,
+        open_display,
+        allow_fresh,
+        team,
+        transport,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn start_agent_at_paths(
+    workspace: &Path,
+    spec_workspace: &Path,
+    agent_id: &AgentId,
+    force: bool,
+    open_display: bool,
+    allow_fresh: bool,
+    team: Option<&str>,
+    transport: &dyn crate::transport::Transport,
+) -> Result<StartAgentOutcome, LifecycleError> {
+    let _ = open_display;
+    let mut state = if team.is_some() {
+        resolve_team_scoped_state_or_refuse(workspace, team)?
+    } else {
+        crate::state::persist::load_runtime_state(workspace)
+            .map_err(|e| LifecycleError::StatePersist(e.to_string()))?
+    };
+    crate::lifecycle::launch::ensure_owner_allowed_for_state(&state, Some(agent_id))?;
+    let agent = state
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .ok_or_else(|| LifecycleError::RequirementUnmet(format!("agent {agent_id} not found")))?;
+    if agent
+        .get("paused")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false)
+    {
+        return Ok(StartAgentOutcome::Paused { agent_id: agent_id.clone() });
+    }
+    let session_name = state_session_name(&state);
+    let window = agent_window(agent, agent_id);
+    if !force && window_exists(transport, &session_name, &window) {
+        mark_agent_running_noop(&mut state, agent_id, &session_name, &window)?;
+        crate::state::projection::save_team_scoped_state(workspace, &state)
+            .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+        if let Ok(spec) = load_team_spec(spec_workspace) {
+            write_team_state(spec_workspace, &spec, &state)?;
+        }
+        let coordinator_started = start_coordinator_for_workspace(workspace)?;
+        let target = format!("{}:{window}", session_name.as_str());
+        write_start_agent_noop_event(workspace, agent_id, &target, coordinator_started)?;
+        return Ok(StartAgentOutcome::Noop {
+            env: AgentActionEnvelope {
+                agent_id: agent_id.clone(),
+                state_file: crate::state::persist::runtime_state_path(workspace),
+                coordinator_started,
+            },
+            target,
+        });
+    }
+    let provider = agent_provider(agent);
+    let session_id = agent_session_id(agent);
+    let rollout_path = agent_rollout_path(agent);
+    let rollout_exists = rollout_path
+        .as_ref()
+        .map(|p| p.as_path().exists())
+        .unwrap_or(false);
+    let start_mode = decide_start_mode(
+        provider_wire(provider),
+        session_id.as_ref(),
+        rollout_path.as_ref(),
+        rollout_exists,
+        allow_fresh,
+    );
+    let spawn_session_id = if matches!(start_mode, StartMode::Resumed) {
+        session_id.as_ref()
+    } else {
+        None
+    };
+    let into_existing_session =
+        session_live_or_default(transport, &session_name, session_name_present(&state));
+    let spawn = spawn_agent_window(
+        workspace,
+        &session_name,
+        agent_id,
+        agent,
+        spawn_session_id,
+        into_existing_session,
+        transport,
+        None,
+    )?;
+    write_start_agent_start_event(
+        workspace,
+        agent_id,
+        agent,
+        provider,
+        start_mode,
+        &session_name,
+        &window,
+        spawn_session_id,
+        into_existing_session,
+    )?;
+    let coordinator_started = start_coordinator_for_workspace(workspace)?;
+    Ok(StartAgentOutcome::Running {
+        env: AgentActionEnvelope {
+            agent_id: agent_id.clone(),
+            state_file: crate::state::persist::runtime_state_path(workspace),
+            coordinator_started,
+        },
+        start_mode,
+        target: spawn.pane_id.as_str().to_string(),
+        session_id,
+        rollout_path,
+    })
+}
+
+/// `stop_agent(workspace, agent_id, team)`(`lifecycle/operations.py:62`)。
+/// owner-gate → kill window → **同时关显示** → 写 state。
+pub fn stop_agent(
+    workspace: &Path,
+    agent_id: &AgentId,
+    team: Option<&str>,
+) -> Result<StopAgentReport, LifecycleError> {
+    stop_agent_with_transport(
+        workspace,
+        agent_id,
+        team,
+        &crate::tmux_backend::TmuxBackend::for_workspace(&lifecycle_run_workspace(workspace)?),
+    )
+}
+
+pub fn stop_agent_with_transport(
+    workspace: &Path,
+    agent_id: &AgentId,
+    team: Option<&str>,
+    transport: &dyn crate::transport::Transport,
+) -> Result<StopAgentReport, LifecycleError> {
+    let paths = lifecycle_paths(workspace, team)?;
+    stop_agent_at_paths(
+        &paths.run_workspace,
+        &paths.spec_workspace,
+        agent_id,
+        team,
+        transport,
+    )
+}
+
+pub(super) fn stop_agent_at_paths(
+    workspace: &Path,
+    spec_workspace: &Path,
+    agent_id: &AgentId,
+    team: Option<&str>,
+    transport: &dyn crate::transport::Transport,
+) -> Result<StopAgentReport, LifecycleError> {
+    // golden operations.py:64-66: resolve_team_scoped_state -> owner gate, BEFORE the unknown-worker raise.
+    let mut state = resolve_team_scoped_state_or_refuse(workspace, team)?;
+    crate::lifecycle::launch::ensure_owner_allowed_for_state(&state, Some(agent_id))?;
+    let spec = load_team_spec(spec_workspace)?;
+    let agent = find_spec_agent(&spec, agent_id)
+        .ok_or_else(|| unknown_worker(agent_id))?;
+    let session_name = state_session_name_from_spec(&state, &spec);
+    let window = state
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("window"))
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty())
+        .unwrap_or_else(|| agent_id.as_str())
+        .to_string();
+    let target_str = format!("{}:{window}", session_name.as_str());
+    let stopped = window_exists(transport, &session_name, &window);
+    if stopped {
+        let target = Target::SessionWindow {
+            session: session_name.clone(),
+            window: WindowName::new(&window),
+        };
+        // golden operations.py:84-86: a non-zero kill-window raises
+        // RuntimeError(f"failed to stop agent {agent_id}: {proc.stderr.strip()}").
+        if let Err(e) = transport.kill_window(&target) {
+            let stderr = match &e {
+                crate::transport::TransportError::Subprocess { stderr, .. } => stderr.trim().to_string(),
+                other => other.to_string(),
+            };
+            let _ = write_stop_window_failed_event(workspace, agent_id, &target_str, &stderr);
+            return Err(LifecycleError::Transport(format!("failed to stop agent {agent_id}: {stderr}")));
+        }
+    }
+    close_agent_display(&mut state, agent_id);
+    mark_agent_stopped(&mut state, agent_id, agent, &window)?;
+    // golden operations.py:95: save_team_scoped_state (team projection) — NOT a raw save, so a
+    // multi-team workspace keeps the other teams' persisted runtime state instead of being clobbered.
+    crate::state::projection::save_team_scoped_state(workspace, &state)
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    // golden operations.py:96-99: snapshot (side-effect), then state_file = write_team_state path.
+    // snapshot.py:19-21 returns None silently when session_name is falsy — mirror that no-op here so
+    // a workspace whose persisted state lacks session_name proceeds to write team_state and return ok
+    // (do NOT swallow OTHER snapshot errors). The stop/reset/remove-force paths all inherit this guard.
+    if session_name_present(&state) {
+        crate::lifecycle::helpers::save_team_runtime_snapshot(workspace, &state)?;
+    }
+    let state_file = write_team_state(spec_workspace, &spec, &state)?;
+    write_stop_complete_event(workspace, agent_id, &target_str, stopped)?;
+    Ok(StopAgentReport {
+        agent_id: agent_id.clone(),
+        target: target_str,
+        stopped,
+        display_closed: true,
+        state_file,
+    })
+}
+
+/// golden `resolve_team_scoped_state` (state.py:243): returns the team-scoped projected state, or
+/// surfaces the refusal dict (`team_target_ambiguous` / `team_target_unresolved`) as a typed error
+/// BEFORE the owner gate / unknown-worker raise (operations.py:64-66). The lifecycle return types are
+/// typed structs with no refusal-Value variant, so the observable refusal is carried in
+/// `LifecycleError::TeamSelect`'s message (reason + error), which is the closest byte-faithful surface.
+pub(super) fn resolve_team_scoped_state_or_refuse(
+    workspace: &Path,
+    team: Option<&str>,
+) -> Result<serde_json::Value, LifecycleError> {
+    let (state, refusal) = crate::state::projection::resolve_team_scoped_state(workspace, team)
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    if let Some(refusal) = refusal {
+        let reason = refusal
+            .get("reason")
+            .and_then(|v| v.as_str())
+            .unwrap_or("team_target_unresolved");
+        let detail = refusal
+            .get("error")
+            .or_else(|| refusal.get("message"))
+            .and_then(|v| v.as_str())
+            .unwrap_or("");
+        return Err(LifecycleError::TeamSelect(format!("{reason}: {detail}")));
+    }
+    state.ok_or_else(|| LifecycleError::StatePersist("resolve_team_scoped_state returned no state".to_string()))
+}
+
+/// `reset_agent(workspace, agent_id, discard_session, open_display, team)`
+/// (`lifecycle/operations.py:102`)。discard + 重起;**未传 discard_session → 拒绝**。
+pub fn reset_agent(
+    workspace: &Path,
+    agent_id: &AgentId,
+    discard_session: bool,
+    open_display: bool,
+    team: Option<&str>,
+) -> Result<ResetAgentOutcome, LifecycleError> {
+    reset_agent_with_transport(
+        workspace,
+        agent_id,
+        discard_session,
+        open_display,
+        team,
+        &crate::tmux_backend::TmuxBackend::for_workspace(&lifecycle_run_workspace(workspace)?),
+    )
+}
+
+pub fn reset_agent_with_transport(
+    workspace: &Path,
+    agent_id: &AgentId,
+    discard_session: bool,
+    open_display: bool,
+    team: Option<&str>,
+    transport: &dyn crate::transport::Transport,
+) -> Result<ResetAgentOutcome, LifecycleError> {
+    if !discard_session {
+        return Ok(ResetAgentOutcome::Refused {
+            reason: ResetRefusal::DiscardSessionRequired,
+        });
+    }
+    let paths = lifecycle_paths(workspace, team)?;
+    reset_agent_at_paths(
+        &paths.run_workspace,
+        &paths.spec_workspace,
+        agent_id,
+        discard_session,
+        open_display,
+        team,
+        transport,
+    )
+}
+
+fn reset_agent_at_paths(
+    workspace: &Path,
+    spec_workspace: &Path,
+    agent_id: &AgentId,
+    discard_session: bool,
+    open_display: bool,
+    team: Option<&str>,
+    transport: &dyn crate::transport::Transport,
+) -> Result<ResetAgentOutcome, LifecycleError> {
+    if !discard_session {
+        return Ok(ResetAgentOutcome::Refused {
+            reason: ResetRefusal::DiscardSessionRequired,
+        });
+    }
+    // golden operations.py:105-110: team-scope resolve + owner gate BEFORE the nested stop.
+    let state_before_stop = resolve_team_scoped_state_or_refuse(workspace, team)?;
+    let discarded_session_id = state_before_stop
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("session_id"))
+        .and_then(|v| v.as_str())
+        .unwrap_or("")
+        .to_string();
+    crate::lifecycle::launch::ensure_owner_allowed_for_state(&state_before_stop, Some(agent_id))?;
+    let stop = stop_agent_at_paths(workspace, spec_workspace, agent_id, team, transport)?;
+    let mut state = resolve_team_scoped_state_or_refuse(workspace, team)?;
+    let spec = load_team_spec(spec_workspace)?;
+    discard_agent_session_fields(&mut state, agent_id)?;
+    // golden operations.py (reset): save_team_scoped_state on the team projection — same multi-team
+    // preservation as stop, not a raw save_runtime_state.
+    crate::state::projection::save_team_scoped_state(workspace, &state)
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    // golden operations.py:125: write_team_state after the discard-save (the intermediate stopped snapshot).
+    write_team_state(spec_workspace, &spec, &state)?;
+    write_reset_tombstone_event(workspace, agent_id, &discarded_session_id)?;
+    let start = start_agent_at_paths(
+        workspace,
+        spec_workspace,
+        agent_id,
+        true,
+        open_display,
+        true,
+        team,
+        transport,
+    )?;
+    let started = matches!(start, StartAgentOutcome::Running { .. });
+    write_reset_complete_event(workspace, agent_id, stop.stopped, started)?;
+    match start {
+        StartAgentOutcome::Running {
+            env, start_mode, ..
+        } => Ok(ResetAgentOutcome::Reset { env, start_mode }),
+        StartAgentOutcome::Noop { env, .. } => Ok(ResetAgentOutcome::Reset {
+            env,
+            start_mode: StartMode::Noop,
+        }),
+        StartAgentOutcome::Paused { .. } => Ok(ResetAgentOutcome::Reset {
+            env: AgentActionEnvelope {
+                agent_id: agent_id.clone(),
+                state_file: crate::state::persist::runtime_state_path(workspace),
+                coordinator_started: false,
+            },
+            start_mode: StartMode::Noop,
+        }),
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn write_start_agent_start_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    agent: &serde_json::Value,
+    provider: crate::provider::Provider,
+    start_mode: StartMode,
+    session_name: &SessionName,
+    window: &str,
+    session_id: Option<&SessionId>,
+    into_existing_session: bool,
+) -> Result<(), LifecycleError> {
+    let auth_mode = agent_auth_mode(agent);
+    let model = agent.get("model").and_then(|v| v.as_str());
+    let adapter = crate::provider::get_adapter(provider);
+    // Contract C / F6.4: event log must record the same context-aware argv that the
+    // actual spawn used — so the role/tools/MCP context appears in `start_agent.agent_start`.
+    let role = agent.get("role").and_then(|v| v.as_str());
+    let safety = crate::lifecycle::launch::effective_runtime_config_for_worker_spawn()?;
+    let tools = crate::lifecycle::launch::worker_tool_refs(agent_tool_strings(agent), &safety);
+    let tool_refs: Vec<&str> = tools.iter().map(String::as_str).collect();
+    let mcp_config = adapter
+        .mcp_config(auth_mode)
+        .map_err(|e| LifecycleError::Provider(e.to_string()))?;
+    let mut argv = match session_id {
+        Some(session_id) => adapter
+            .build_resume_command_with_context(
+                Some(session_id),
+                auth_mode,
+                Some(&mcp_config),
+                role,
+                model,
+                &tool_refs,
+            )
+            .map_err(|e| LifecycleError::Provider(e.to_string()))?,
+        None => adapter
+            .build_command_with_tools(auth_mode, Some(&mcp_config), role, model, &tool_refs)
+            .map_err(|e| LifecycleError::Provider(e.to_string()))?,
+    };
+    let team_id = agent
+        .get("owner_team_id")
+        .and_then(|v| v.as_str());
+    crate::lifecycle::launch::fill_spawn_placeholders_full(&mut argv, workspace, agent_id.as_str(), team_id);
+    let tmux_start_mode = if into_existing_session {
+        "new-window"
+    } else {
+        "new-session"
+    };
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "start_agent.agent_start",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "provider": provider_wire(provider),
+                "start_mode": start_mode,
+                "session_id": session_id.map(|s| s.as_str()),
+                "session": session_name.as_str(),
+                "window": window,
+                "tmux_start_mode": tmux_start_mode,
+                "command": argv,
+                "mcp_config": agent.get("mcp_config").cloned().unwrap_or(serde_json::Value::Null),
+            }),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}
+
+fn write_stop_complete_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    target: &str,
+    stopped: bool,
+) -> Result<(), LifecycleError> {
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "stop_agent.complete",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "target": target,
+                "stopped": stopped,
+            }),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}
+
+fn write_stop_window_failed_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    target: &str,
+    stderr: &str,
+) -> Result<(), LifecycleError> {
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "stop_agent.window_stop_failed",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "target": target,
+                "stderr": stderr,
+            }),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}
+
+fn write_reset_tombstone_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    discarded_session_id: &str,
+) -> Result<(), LifecycleError> {
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "discard.session_tombstone",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "discarded_session_id": discarded_session_id,
+            }),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}
+
+fn write_reset_complete_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    stopped: bool,
+    started: bool,
+) -> Result<(), LifecycleError> {
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "reset_agent.complete",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "stopped": stopped,
+                "started": started,
+            }),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}