@team-agent/installer 0.5.0 → 0.5.2

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

@@ -2835,16 +2835,91 @@ pub fn quick_start_in_workspace_with_display(
     yes: bool,
     team_id: Option<&str>,
     open_display: bool,
+) -> Result<QuickStartReport, LifecycleError> {
+    // Legacy entrypoint: no `--backend` override. Preserves the exact
+    // tmux behavior we shipped in Phase 1c (byte-equivalent tmux path
+    // when no explicit backend is asked for).
+    quick_start_in_workspace_with_display_and_backend(
+        workspace,
+        agents_dir,
+        name,
+        yes,
+        team_id,
+        open_display,
+        None,
+    )
+}
+
+/// 0.5.x Phase 1d Batch 2: quick-start with an optional
+/// `--backend <tmux|conpty>` override. When `backend` is `None` or
+/// `Some("tmux")` the transport is the same one the legacy entrypoint
+/// built (byte-equivalent to Phase 1c), so tmux users see no
+/// behavioral change.
+///
+/// When `backend` is `Some("conpty")`, this call routes through the
+/// factory. On a host without a live shim client (i.e. every
+/// non-Windows host today), the resulting `ConPtyBackend` degrades
+/// its spawn/inject/capture calls to `TransportError::MuxUnavailable`
+/// honestly — MUST-NOT-13 + CR C-1 ①. Users see a real "conpty
+/// unavailable" error rather than a silent tmux fallback.
+pub fn quick_start_in_workspace_with_display_and_backend(
+    workspace: &Path,
+    agents_dir: &Path,
+    name: Option<&str>,
+    yes: bool,
+    team_id: Option<&str>,
+    open_display: bool,
+    backend: Option<&str>,
 ) -> Result<QuickStartReport, LifecycleError> {
     let workspace = explicit_quick_start_workspace(workspace);
-    let transport = quick_start_tmux_backend(&workspace);
+    // Default / `tmux` literal: preserve the existing tmux path
+    // BYTE-FOR-BYTE. This is the CR §Batch 2 Verification anchor:
+    // `quick-start` without `--backend` produces byte-equivalent tmux
+    // behavior.
+    let literal = backend.map(str::trim);
+    let is_tmux_or_default = matches!(literal, None | Some("") | Some("tmux") | Some("TMUX"));
+    if is_tmux_or_default {
+        let transport = quick_start_tmux_backend(&workspace);
+        return quick_start_with_transport_in_workspace_with_display(
+            &workspace,
+            agents_dir,
+            name,
+            yes,
+            team_id,
+            &transport,
+            open_display,
+        );
+    }
+    // Explicit non-tmux backend: route through the factory. Parse the
+    // literal, then delegate. On unsupported literals or refused
+    // preconditions we return `LifecycleError` — never silently pick
+    // tmux (CR C-1 ①/②).
+    let requested = crate::transport_factory::RequestedTransportBackend::parse_literal(
+        literal.unwrap_or_default(),
+    )
+    .ok_or_else(|| {
+        LifecycleError::TeamSelect(format!(
+            "unsupported --backend literal {literal:?}; expected `tmux` or `conpty` \
+             (Phase 1d does not auto-map `pty` to conpty — CR C-1 ②)"
+        ))
+    })?;
+    let team_key_for_factory = team_id;
+    let input = crate::transport_factory::TransportFactoryInput::new(
+        &workspace,
+        crate::transport_factory::TransportPurpose::Launch,
+    )
+    .with_team_key(team_key_for_factory)
+    .with_explicit_backend(Some(requested));
+    let resolved = crate::transport_factory::resolve_transport(input)
+        .map_err(|e| LifecycleError::TeamSelect(e.to_string()))?;
+    // Hand the boxed backend down as `&dyn Transport`.
     quick_start_with_transport_in_workspace_with_display(
         &workspace,
         agents_dir,
         name,
         yes,
         team_id,
-        &transport,
+        &*resolved.backend,
         open_display,
     )
 }
@@ -3068,7 +3143,16 @@ pub fn quick_start_with_transport_in_workspace_with_display(
     let resolved_spec_path =
         std::fs::canonicalize(&spec_path).unwrap_or_else(|_| spec_path.clone());
     let mut state = initial_runtime_state(&spec, &resolved_spec_path, &workspace, agents_dir);
-    annotate_runtime_tmux_endpoint(&mut state, transport, &workspace);
+    // 0.5.x Phase 1d hot-path 接线(裁决1 msg_76e1d98202b8): use the
+    // generic annotator that writes `state.transport = { kind, source }`
+    // for every backend AND (for tmux) preserves the existing
+    // `tmux_endpoint`/`tmux_socket`/`tmux_socket_source` fields via the
+    // inner `annotate_runtime_tmux_endpoint` call. Source is threaded
+    // from the caller-side factory selection when available; the
+    // legacy quick-start entrypoint currently passes `None` (defaults
+    // to "unknown" in the payload) — Phase 2 refactor will thread
+    // ResolvedTransport.source through the launch signature.
+    annotate_runtime_transport(&mut state, transport, &workspace, None);
     save_launched_team_state_for_key(&workspace, &state, Some(&state_team_key))?;
     annotate_persisted_team_depth(
         &workspace,
@@ -3164,6 +3248,46 @@ pub fn quick_start_with_transport_in_workspace_with_display(
 /// the persisted endpoint synchronized with the transport they actually used,
 /// closing the silent socket-drift gap** (single state-save path; no parallel
 /// "annotate after spawn" race with coordinator).
+/// 0.5.x Phase 1d Batch 2: generic runtime-transport annotator.
+///
+/// Writes `state.transport = { kind, source }` for every backend
+/// (kind = wire string `"tmux"` | `"conpty"`; source = wire string
+/// from `ResolvedTransport.source` when known, else `"unknown"`).
+///
+/// For tmux, ALSO forwards to `annotate_runtime_tmux_endpoint` so the
+/// existing `tmux_endpoint` / `tmux_socket` / `tmux_socket_source`
+/// fields remain populated byte-equivalent to today's shape.
+///
+/// The tmux-specific fields are NOT written for ConPTY (CR C-4: no
+/// tmux-only fields under a conpty state; keeps compact status
+/// stable). ConPTY discovery fields (`pipe_name`, `shim_pid`) are
+/// added in Batch 3 when the shim boot path lands; this function just
+/// pins the top-level `transport.kind`/`source`.
+pub fn annotate_runtime_transport(
+    state: &mut serde_json::Value,
+    transport: &dyn Transport,
+    workspace: &Path,
+    source: Option<&str>,
+) {
+    use crate::transport::BackendKind;
+    let kind_wire = match transport.kind() {
+        BackendKind::Tmux => "tmux",
+        BackendKind::WezTerm => "wezterm",
+        BackendKind::ConPty => "conpty",
+    };
+    if let Some(obj) = state.as_object_mut() {
+        let transport_block = serde_json::json!({
+            "kind": kind_wire,
+            "source": source.unwrap_or("unknown"),
+        });
+        obj.insert("transport".to_string(), transport_block);
+    }
+    // Tmux: preserve the existing tmux endpoint annotation shape.
+    if matches!(transport.kind(), BackendKind::Tmux) {
+        annotate_runtime_tmux_endpoint(state, transport, workspace);
+    }
+}
+
 pub(crate) fn annotate_runtime_tmux_endpoint(
     state: &mut serde_json::Value,
     transport: &dyn Transport,

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

@@ -467,6 +467,22 @@ pub(super) fn start_coordinator_for_workspace(workspace: &Path) -> Result<bool,
 /// only within `lifecycle::restart`. Sharing the resolver across the lifecycle
 /// module is the correct ownership: restart/add/fork all need the SAME socket
 /// the live team uses, and duplicating the lookup invited drift.**
+/// 0.5.x Phase 1d Batch 1: this legacy resolver stays tmux-only. It
+/// still returns a concrete `TmuxBackend` because the 6 caller sites
+/// (rebuild/agent/remove/launch) currently call `TmuxBackend`-specific
+/// methods (`.tmux_endpoint()`, `.for_workspace()`, etc.). But it now
+/// routes through the factory so its **selection semantics** match
+/// the new `lifecycle_worker_transport_for_selected_state` API:
+///
+/// - If `state.transport.kind` is `"conpty"`, this legacy tmux-typed
+///   resolver **fails-closed** with `TransportBackendKindMismatch`
+///   rather than silently returning a tmux backend that would
+///   spawn/inject into the wrong pane universe. That satisfies CR C-1
+///   fail-closed while the migration of caller sites to the generic
+///   `_transport_for_selected_state` API completes.
+/// - Otherwise (default/legacy tmux endpoint), behavior is preserved
+///   byte-for-byte through
+///   `tmux_backend_for_runtime_state_or_workspace`.
 pub(crate) fn lifecycle_worker_tmux_backend_for_selected_state(
     run_workspace: &Path,
     team: Option<&str>,
@@ -485,12 +501,66 @@ pub(crate) fn lifecycle_worker_tmux_backend_for_selected_state(
             .unwrap_or("");
         return Err(LifecycleError::TeamSelect(format!("{reason}: {detail}")));
     }
+    // CR C-1 fail-closed: state with `transport.kind=conpty` must NOT
+    // silently downgrade to a tmux backend just because the caller
+    // asked for the tmux-typed variant. Callers that see this refusal
+    // are expected to migrate to `lifecycle_worker_transport_for_selected_state`
+    // during Batch 2/3.
+    if let Some(state_ref) = state.as_ref() {
+        if let Some(kind) = state_ref.pointer("/transport/kind").and_then(|v| v.as_str()) {
+            if kind.eq_ignore_ascii_case("conpty") {
+                return Err(LifecycleError::TeamSelect(format!(
+                    "backend_kind_mismatch: state.transport.kind={kind:?} but the legacy \
+                     tmux-typed lifecycle resolver was invoked; caller must migrate to \
+                     `lifecycle_worker_transport_for_selected_state` (Phase 1d Batch 2/3)"
+                )));
+            }
+        }
+    }
     Ok(state
         .as_ref()
         .map(|state| lifecycle_worker_tmux_backend_for_state(run_workspace, state))
         .unwrap_or_else(|| crate::tmux_backend::TmuxBackend::for_workspace(run_workspace)))
 }
 
+/// 0.5.x Phase 1d Batch 1: new generic-typed lifecycle resolver.
+///
+/// Same team-selection semantics as the legacy tmux-typed variant, but
+/// returns a `ResolvedTransport` from the factory so callers that can
+/// hold `Box<dyn Transport>` (or the resolved `BackendKind`) work
+/// against both tmux AND conpty state. Caller migration to this API
+/// happens across Batch 2-5.
+///
+/// Fail-closed rules follow the factory (C-1 ×2, C-2 CLI-vs-state,
+/// C-3 N38 notices via `ResolvedTransport.notices`).
+pub(crate) fn lifecycle_worker_transport_for_selected_state(
+    run_workspace: &Path,
+    team: Option<&str>,
+) -> Result<crate::transport_factory::ResolvedTransport, LifecycleError> {
+    let (state, refusal) = crate::state::projection::resolve_team_scoped_state(run_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}")));
+    }
+    let input = crate::transport_factory::TransportFactoryInput::new(
+        run_workspace,
+        crate::transport_factory::TransportPurpose::LifecycleWorker,
+    )
+    .with_team_key(team)
+    .with_state(state.as_ref());
+    crate::transport_factory::resolve_transport(input)
+        .map_err(|e| LifecycleError::TeamSelect(e.to_string()))
+}
+
 pub(super) fn lifecycle_worker_tmux_backend_for_state(
     run_workspace: &Path,
     state: &serde_json::Value,

package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs

@@ -2693,6 +2693,13 @@ fn quick_start_state_seeds_spec_path_workspace_leader_display_backend() {
             "tasks",
             "display_backend",
             "is_external_leader",
+            // 0.5.x Phase 1d hot-path 接线 (裁决1 msg_76e1d98202b8):
+            // `transport = { kind, source }` inserted here by
+            // `annotate_runtime_transport`. Kind is `"tmux"` for the
+            // default tmux path (byte-equivalent behavior + new metadata
+            // field); source is `"unknown"` until Phase 2 threads
+            // `ResolvedTransport.source` through the launch call site.
+            "transport",
             // 0.4.0 refactor: `team_key` added as top-level topology marker
             // alongside active_team_key (refactor-modular-architecture). The
             // owner / leader_receiver / owner_epoch invariants below still

package/crates/team-agent/src/lifecycle/tests/phase_golden.rs

@@ -11,6 +11,20 @@ use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
 const ANCESTRY_ENV: &str = "TEAM_AGENT_TEST_PROCESS_ANCESTRY_ARGV_JSON";
+const CALLER_IDENTITY_ENVS: &[&str] = &[
+    "TMUX",
+    "TMUX_PANE",
+    "TEAM_AGENT_LEADER_PANE_ID",
+    "TEAM_AGENT_LEADER_SESSION_UUID",
+    "TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE",
+    "TEAM_AGENT_LEADER_PROVIDER",
+    "TEAM_AGENT_MACHINE_FINGERPRINT",
+    "TEAM_AGENT_WORKSPACE",
+    "TEAM_AGENT_TEAM_ID",
+    "TEAM_AGENT_OWNER_TEAM_ID",
+    "TEAM_AGENT_ACTIVE_TEAM",
+    "TEAM_AGENT_ID",
+];
 
 #[test]
 #[serial_test::serial(env)]
@@ -141,6 +155,10 @@ struct PhaseGolden {
 
 fn run_phase_golden(spec: PhaseGolden) -> Value {
     let _permission_mode = EnvVarGuard::set(ANCESTRY_ENV, "[]");
+    let _caller_identity = CALLER_IDENTITY_ENVS
+        .iter()
+        .map(|key| EnvVarGuard::unset(key))
+        .collect::<Vec<_>>();
     let team = two_worker_team_dir();
     let workspace = team.parent().expect("workspace").to_path_buf();
     seed_healthy_coordinator(&workspace);
@@ -186,6 +204,7 @@ fn run_phase_golden(spec: PhaseGolden) -> Value {
         json: true,
         message_id: Some("phase-golden-message".to_string()),
         pane: None,
+        to_name: None,
     });
     let collect = cmd_collect(&CollectArgs {
         workspace: workspace.clone(),
@@ -394,6 +413,14 @@ impl EnvVarGuard {
         }
         Self { key, previous }
     }
+
+    fn unset(key: &'static str) -> Self {
+        let previous = std::env::var(key).ok();
+        unsafe {
+            std::env::remove_var(key);
+        }
+        Self { key, previous }
+    }
 }
 
 impl Drop for EnvVarGuard {
@@ -531,6 +558,15 @@ fn normalize_path_string(text: &str, ctx: &NormalizeCtx) -> String {
 
 fn normalize_team_agent_binary_path(text: &str) -> String {
     let mut out = text.to_string();
+    // 0.5.0 hermetic 教训「环境路径类 token 化」的直接延伸
+    // (leader msg_6ee04cf5aee8):归一化改为结构判据,不绑路径前缀。
+    // 用户 CARGO_TARGET_DIR 可以指到任意目录(默认 `<repo>/target`,
+    // 全局改道时是 `/Volumes/nvme/cargo-target`,CI 时可能是别的)。
+    // 结构判据:任意绝对路径下的 `/deps/team_agent-<hex>`(可选 `.exe`)
+    // → `<TEAM_AGENT_BIN>`。同时保留旧 marker 兼容(处理旧固定字符串
+    // 出现在 output 里,以及 `debug/team-agent` / `release/team-agent`
+    // 这两个非 `/deps/` 分支)。
+    out = normalize_deps_team_agent_by_structure(&out);
     for marker in [
         "/target/debug/deps/team_agent-",
         "/target/debug/team-agent",
@@ -541,6 +577,60 @@ fn normalize_team_agent_binary_path(text: &str) -> String {
     out
 }
 
+/// Structural (path-prefix-independent) normalization for
+/// `/…/deps/team_agent-<hex>(.exe)?` occurrences. Scans the input for
+/// every `/deps/team_agent-` marker and rewrites the containing
+/// absolute path token to `<TEAM_AGENT_BIN>`, no matter which
+/// `CARGO_TARGET_DIR` produced it.
+fn normalize_deps_team_agent_by_structure(text: &str) -> String {
+    const MARKER: &str = "/deps/team_agent-";
+    let mut out = String::with_capacity(text.len());
+    let bytes = text.as_bytes();
+    let mut i = 0usize;
+    while i < bytes.len() {
+        let Some(rel) = text[i..].find(MARKER) else {
+            out.push_str(&text[i..]);
+            break;
+        };
+        let marker_idx = i + rel;
+        // Locate the start of the absolute path token: walk back from
+        // `marker_idx` while the byte is not one of a small set of
+        // delimiters (quote, whitespace, `[`, `(`, `,`, `:` after
+        // whitespace). The absolute-path anchor MUST also start with
+        // `/` — if the containing token is not absolute, skip
+        // rewriting so we don't eat unrelated text.
+        let path_start = text[..marker_idx]
+            .rfind(|c: char| matches!(c, '"' | '\'' | ' ' | '[' | '(' | ',' | '\n' | '\t'))
+            .map(|idx| idx + 1)
+            .unwrap_or(0);
+        // Confirm the token starts with `/` (absolute path).
+        if !text[path_start..].starts_with('/') {
+            // Not an absolute path — leave alone.
+            out.push_str(&text[i..marker_idx + MARKER.len()]);
+            i = marker_idx + MARKER.len();
+            continue;
+        }
+        // Extend the end past the hex hash + optional `.exe`. Same
+        // continuation rule as `replace_path_with_marker`: alnum + `-`
+        // + `_` + `.`.
+        let mut path_end = marker_idx + MARKER.len();
+        while path_end < text.len() {
+            let ch = text[path_end..].chars().next().expect("char at boundary");
+            if ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '.') {
+                path_end += ch.len_utf8();
+            } else {
+                break;
+            }
+        }
+        // Emit everything up to the path start, then the token, then
+        // continue past the eaten span.
+        out.push_str(&text[i..path_start]);
+        out.push_str("<TEAM_AGENT_BIN>");
+        i = path_end;
+    }
+    out
+}
+
 fn replace_path_with_marker(mut text: String, marker: &str, token: &str) -> String {
     let mut search_from = 0;
     while let Some(offset) = text[search_from..].find(marker) {