@team-agent/installer 0.5.2 → 0.5.3

package/crates/team-agent/src/state/persist.rs

@@ -146,7 +146,14 @@ fn errno_name(errno: Option<i32>) -> Option<&'static str> {
 }
 
 /// `runtime.py:_runtime_lock` 的 flock 版(RAII;Drop 释放)。state-save 不发锁事件。
-/// POSIX flock(unix);Windows 锁(LockFileEx)延平台层(step 9+)。
+///
+/// 0.5.x Windows portability Batch 2: migrated to
+/// `crate::platform::file_lock::{try_lock_once_nonblocking, unlock}` so
+/// the same polling loop + timeout + `StateError::Locked(name)` shape
+/// works on both Unix (`flock`) and Windows (`LockFileEx`) — 1:1
+/// semantic mapping. The Batch 0 non-Unix `not_yet_implemented`
+/// fallback is now removed (CR C-2 fallback burn-down; grep guard
+/// `platform_fallback_burndown_batch0.rs` flipped in this batch).
 struct RuntimeLock {
     #[allow(dead_code)]
     file: std::fs::File,
@@ -160,42 +167,37 @@ impl RuntimeLock {
         }
         let file = std::fs::OpenOptions::new()
             .create(true)
+            .read(true)
             .write(true)
             .truncate(false)
             .open(&lock_path)?;
-        #[cfg(unix)]
-        {
-            use std::os::unix::io::AsRawFd;
-            let fd = file.as_raw_fd();
-            let start = Instant::now();
-            loop {
-                // SAFETY: fd 来自打开的 lock_file,LOCK_EX|LOCK_NB 非阻塞。
-                let rc = unsafe { libc::flock(fd, libc::LOCK_EX | libc::LOCK_NB) };
-                if rc == 0 {
-                    return Ok(Self { file });
+        let start = Instant::now();
+        loop {
+            match crate::platform::file_lock::try_lock_once_nonblocking(&file) {
+                Ok(true) => return Ok(Self { file }),
+                Ok(false) => {
+                    if start.elapsed().as_secs_f64() >= timeout {
+                        return Err(StateError::Locked(name.to_string()));
+                    }
+                    std::thread::sleep(Duration::from_millis(50));
                 }
-                if start.elapsed().as_secs_f64() >= timeout {
-                    return Err(StateError::Locked(name.to_string()));
+                Err(e) => {
+                    // Byte-preserving: a real I/O error surfaces as a
+                    // `StateError::Io` (via `From<io::Error>`), same as
+                    // the current inline code would if `file.open()`
+                    // failed. The lock-would-block case took the
+                    // Ok(false) arm above.
+                    return Err(StateError::from(e));
                 }
-                std::thread::sleep(Duration::from_millis(50));
             }
         }
-        #[cfg(not(unix))]
-        {
-            let _ = timeout;
-            Err(StateError::Locked(format!(
-                "{name} (runtime lock not yet implemented on non-unix)"
-            )))
-        }
     }
 }
 
-#[cfg(unix)]
 impl Drop for RuntimeLock {
     fn drop(&mut self) {
-        use std::os::unix::io::AsRawFd;
-        // SAFETY: 释放本进程持有的 flock。
-        unsafe { libc::flock(self.file.as_raw_fd(), libc::LOCK_UN) };
+        // Best-effort unlock. OS releases on handle close if this fails.
+        let _ = crate::platform::file_lock::unlock(&self.file);
     }
 }
 
@@ -451,6 +453,18 @@ fn apply_persist_merge_contract(
         // teams.<key> entry-scoped preservation at :370 remains so legacy
         // teams.<key>.team_owner entries still survive a save that omits
         // them.
+
+        // 0.5.x Windows portability Batch 7 F6 (leader msg_700a016675d0):
+        // preserve `state.transport.shim` across saves. The coordinator
+        // writes this block when it spawns `windows-shim.exe` during
+        // quick-start (see `coordinator::conpty_shim::finalize`).
+        // Downstream saves inside the same quick-start (leader-persist,
+        // worker-persist) construct their `incoming` state from an
+        // in-memory copy that predates the shim-spawn, so without this
+        // preserve step the shim block is silently dropped. That
+        // clobber broke Batch 6 CHECK 6 (`shutdown` couldn't route to
+        // the shim pid because `state.transport.shim.pid` was gone).
+        preserve_transport_shim(incoming, latest);
     }
 
     let latest_teams = latest.get("teams").and_then(Value::as_object);
@@ -478,6 +492,47 @@ fn apply_persist_merge_contract(
     Ok(())
 }
 
+/// 0.5.x Windows portability Batch 7 F6: copy `latest.transport.shim`
+/// into `incoming` if the incoming save omitted it. The coordinator's
+/// `conpty_shim::finalize` writes `state.transport.shim = {pid,
+/// pipe_name, pipe_ready}` after Hello succeeds. If a subsequent save
+/// in the same quick-start starts from a stale in-memory `Value` that
+/// predates the finalize, this preserve step keeps the on-disk shim
+/// block alive.
+///
+/// Only runs when the top-level projection matches (same active team
+/// key + same session name) — no risk of leaking a shim block into
+/// an unrelated projection.
+///
+/// Windows-relevant behavior; on Unix `transport.shim` is never
+/// written, so this fn is a no-op (both branches see `None`).
+fn preserve_transport_shim(incoming: &mut Value, latest: &Value) {
+    // The shim block only matters when `latest` has one AND
+    // `incoming` doesn't (or `incoming.transport` doesn't exist).
+    let Some(latest_shim) = latest
+        .get("transport")
+        .and_then(|t| t.get("shim"))
+        .cloned()
+    else {
+        return;
+    };
+    let Some(incoming_obj) = incoming.as_object_mut() else {
+        return;
+    };
+    let transport = incoming_obj
+        .entry("transport".to_string())
+        .or_insert_with(|| serde_json::json!({}));
+    let Some(transport_obj) = transport.as_object_mut() else {
+        return;
+    };
+    // If the incoming already has a shim block, respect it (the
+    // caller has authoritative newer state — e.g. shim was rotated).
+    if transport_obj.contains_key("shim") {
+        return;
+    }
+    transport_obj.insert("shim".to_string(), latest_shim);
+}
+
 fn should_skip_capture_backfill(
     current_team_key: Option<&str>,
     skip_team_key: Option<&str>,
@@ -1696,6 +1751,131 @@ mod tests {
         );
     }
 
+    // 0.5.x Windows portability Batch 7 F6 (leader msg_700a016675d0):
+    // `state.transport.shim` must survive a downstream save whose
+    // `incoming` was constructed from a stale in-memory Value.
+    #[test]
+    fn transport_shim_block_is_preserved_across_merge() {
+        let ws = temp_ws();
+        // Disk state has the shim block (coordinator wrote it after
+        // Hello succeeded).
+        write_state(
+            &ws,
+            &json!({
+                "session_name": "team-a",
+                "active_team_key": "team-a",
+                "agents": {},
+                "transport": {
+                    "kind": "conpty",
+                    "shim": { "pid": 4242, "pipe_name": r"\\.\pipe\team-agent-conpty-abc-team-a", "pipe_ready": true }
+                }
+            }),
+        );
+        // Incoming save (leader-persist or worker-persist) doesn't
+        // know about the shim block.
+        let incoming = json!({
+            "session_name": "team-a",
+            "active_team_key": "team-a",
+            "agents": {},
+            "transport": {
+                "kind": "conpty"
+            }
+        });
+        save_runtime_state(&ws, &incoming).unwrap();
+        let saved = read_state(&ws);
+        // Shim block must survive the merge.
+        assert_eq!(
+            saved.pointer("/transport/shim/pid").and_then(Value::as_u64),
+            Some(4242),
+            "shim.pid must be preserved: {saved}"
+        );
+        assert_eq!(
+            saved
+                .pointer("/transport/shim/pipe_name")
+                .and_then(Value::as_str),
+            Some(r"\\.\pipe\team-agent-conpty-abc-team-a"),
+        );
+        assert_eq!(
+            saved
+                .pointer("/transport/shim/pipe_ready")
+                .and_then(Value::as_bool),
+            Some(true),
+        );
+        // And the incoming's `transport.kind` still wins.
+        assert_eq!(
+            saved.pointer("/transport/kind").and_then(Value::as_str),
+            Some("conpty"),
+        );
+    }
+
+    #[test]
+    fn transport_shim_incoming_authoritative_overrides_latest() {
+        // If the caller has a NEWER shim block (e.g. rotation), it
+        // wins — preserve_transport_shim only fills in the gap.
+        let ws = temp_ws();
+        write_state(
+            &ws,
+            &json!({
+                "session_name": "team-a",
+                "active_team_key": "team-a",
+                "agents": {},
+                "transport": {
+                    "kind": "conpty",
+                    "shim": { "pid": 1000, "pipe_name": "old", "pipe_ready": true }
+                }
+            }),
+        );
+        let incoming = json!({
+            "session_name": "team-a",
+            "active_team_key": "team-a",
+            "agents": {},
+            "transport": {
+                "kind": "conpty",
+                "shim": { "pid": 9999, "pipe_name": "new", "pipe_ready": true }
+            }
+        });
+        save_runtime_state(&ws, &incoming).unwrap();
+        let saved = read_state(&ws);
+        assert_eq!(
+            saved.pointer("/transport/shim/pid").and_then(Value::as_u64),
+            Some(9999),
+            "incoming shim block must win when both sides have one"
+        );
+        assert_eq!(
+            saved
+                .pointer("/transport/shim/pipe_name")
+                .and_then(Value::as_str),
+            Some("new"),
+        );
+    }
+
+    #[test]
+    fn transport_shim_no_leak_when_latest_lacks_block() {
+        // If disk has no shim block, save must not synthesize one.
+        let ws = temp_ws();
+        write_state(
+            &ws,
+            &json!({
+                "session_name": "team-a",
+                "active_team_key": "team-a",
+                "agents": {},
+                "transport": {"kind": "tmux"}
+            }),
+        );
+        let incoming = json!({
+            "session_name": "team-a",
+            "active_team_key": "team-a",
+            "agents": {},
+            "transport": {"kind": "tmux"}
+        });
+        save_runtime_state(&ws, &incoming).unwrap();
+        let saved = read_state(&ws);
+        assert!(
+            saved.pointer("/transport/shim").is_none(),
+            "shim must not appear when neither side had one: {saved}"
+        );
+    }
+
     #[test]
     fn projection_paths_do_not_cross_backfill_topology() {
         let ws = temp_ws();

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

@@ -18,6 +18,13 @@
 use std::collections::BTreeMap;
 use std::hash::{Hash, Hasher};
 use std::io::{Read, Write};
+// 0.5.x Windows portability Batch 1: gate the sole Unix API surface
+// in this concrete tmux backend (FileTypeExt::is_socket + libc::geteuid
+// tmux-socket-root derivation). The rest of the file is Command::new
+// "tmux" shellouts that compile on Windows but return runtime errors
+// honestly (tmux binary absent → typed subprocess error).
+// Truth source: `.team/artifacts/0.5.x-windows-portability-survey-design.md` §Batch 1.
+#[cfg(unix)]
 use std::os::unix::fs::FileTypeExt;
 use std::path::{Path, PathBuf};
 use std::process::Stdio;
@@ -489,10 +496,24 @@ pub(crate) fn socket_path_for_name(socket_name: &str) -> Option<PathBuf> {
     if let Some(existing) = existing_socket_path_for_name(socket_name) {
         return Some(existing);
     }
-    let uid = unsafe { libc::geteuid() };
-    let default_root = PathBuf::from(format!("/tmp/tmux-{uid}"));
-    let default_root = default_root.canonicalize().unwrap_or(default_root);
-    Some(default_root.join(socket_name))
+    // Batch 1: tmux uses `/tmp/tmux-<uid>/` on Unix; on Windows this
+    // helper is dead code (Command::new "tmux" fails at spawn time
+    // before this path is dereferenced). N38 typed unsupported honored
+    // at the shellout boundary.
+    #[cfg(unix)]
+    {
+        let uid = unsafe { libc::geteuid() };
+        let default_root = PathBuf::from(format!("/tmp/tmux-{uid}"));
+        let default_root = default_root.canonicalize().unwrap_or(default_root);
+        Some(default_root.join(socket_name))
+    }
+    #[cfg(not(unix))]
+    {
+        // Windows: tmux socket-root derivation is meaningless. Return
+        // None so the caller sees the honest "no such socket" branch.
+        let _ = socket_name;
+        None
+    }
 }
 
 fn existing_socket_path_for_name(socket_name: &str) -> Option<PathBuf> {
@@ -582,14 +603,25 @@ pub(crate) fn attach_commands_for_windows<'a>(
 }
 
 pub(crate) fn tmux_socket_roots() -> Vec<PathBuf> {
-    let uid = unsafe { libc::geteuid() };
-    let mut roots = vec![PathBuf::from(format!("/tmp/tmux-{uid}"))];
-    if let Some(tmpdir) = std::env::var_os("TMPDIR") {
-        roots.push(PathBuf::from(tmpdir).join(format!("tmux-{uid}")));
+    // Batch 1: `/tmp/tmux-<uid>` root enumeration is Unix-only tmux
+    // convention. On Windows return empty so the caller loops zero
+    // times (honest "no tmux socket roots" — tmux is not deployed on
+    // native Windows without WSL, and WSL is out of scope).
+    #[cfg(unix)]
+    {
+        let uid = unsafe { libc::geteuid() };
+        let mut roots = vec![PathBuf::from(format!("/tmp/tmux-{uid}"))];
+        if let Some(tmpdir) = std::env::var_os("TMPDIR") {
+            roots.push(PathBuf::from(tmpdir).join(format!("tmux-{uid}")));
+        }
+        roots.sort();
+        roots.dedup();
+        roots
+    }
+    #[cfg(not(unix))]
+    {
+        Vec::new()
     }
-    roots.sort();
-    roots.dedup();
-    roots
 }
 
 pub(crate) fn tmux_socket_endpoints() -> Vec<String> {
@@ -602,7 +634,20 @@ pub(crate) fn tmux_socket_endpoints() -> Vec<String> {
             let Ok(file_type) = entry.file_type() else {
                 continue;
             };
-            if !file_type.is_socket() {
+            // Batch 1: `FileTypeExt::is_socket` is Unix-only. Dead code
+            // on Windows because `tmux_socket_roots()` returns empty
+            // there (no /tmp/tmux-<uid> convention). We still cfg the
+            // method call so `cargo check --target x86_64-pc-windows-msvc`
+            // sees no `std::os::unix::fs::FileTypeExt` reference.
+            #[cfg(unix)]
+            {
+                if !file_type.is_socket() {
+                    continue;
+                }
+            }
+            #[cfg(not(unix))]
+            {
+                let _ = file_type;
                 continue;
             }
             let path = entry.path();
@@ -2249,5 +2294,10 @@ fn non_empty(raw: &str) -> Option<&str> {
     }
 }
 
-#[cfg(test)]
+// 0.5.x Windows portability Batch 5: the `tmux_backend/tests.rs`
+// module uses `std::os::unix::net::UnixListener` for its mock
+// runner + verifies Unix-specific socket-root derivation. Since the
+// tmux backend itself only functions on Unix (design § Route B —
+// tmux is a Unix concept), the test module stays Unix-only.
+#[cfg(all(test, unix))]
 mod tests;

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

@@ -351,12 +351,61 @@ fn build_conpty(
     // the same source of truth the tmux short-socket derivation uses,
     // so the shim + tmux socket see identical workspace identity.
     let workspace_hash = crate::tmux_backend::workspace_short_hash_pub(input.workspace);
-    // No pipe client is wired here (that's Batch 2/3 scope). Without
-    // a live client, `ConPtyBackend` degrades to `MuxUnavailable`
-    // honestly — which is exactly what C-1 requires when the caller
-    // asked for conpty on a host with no shim.
-    let backend = ConPtyBackend::new(workspace_hash, team_key);
+    // `mut` because the Windows branch below may reassign after a
+    // successful pipe connect + `with_pipe_client` handshake. On
+    // Unix the binding stays as-constructed.
+    #[cfg_attr(not(windows), allow(unused_mut))]
+    let mut backend = ConPtyBackend::new(workspace_hash.clone(), team_key);
     let mut notices = Vec::new();
+    // 0.5.x CR C-5 fix (leader msg_a89b5a03bbf0): factory returns to
+    // pure assembly. `build_conpty` used to call
+    // `NamedPipeClient::connect(_, 2000)` inline when
+    // `conpty_pipe_ready(input)` said state hinted the shim was up.
+    // That was a real CR C-5 violation — every `status`/`diagnose`
+    // resolve on Windows could block 2 seconds probing a
+    // non-existent pipe.
+    //
+    // Post-fix: the factory only STASHES the pipe hint via
+    // `ConPtyBackend::with_pipe_hint(pipe_name)`. The backend's
+    // `ensure_pipe_client` performs the connect + Hello lazily on
+    // the first Op that needs the pipe. Callers that don't need
+    // the pipe (status, resolve-only paths) never pay the connect
+    // cost.
+    //
+    // The Batch 6 direct-handoff path (`lifecycle/launch.rs`
+    // quick-start conpty) stays byte-compatible: it hands its
+    // Hello-connected client to `with_pipe_client` AFTER
+    // `resolve_transport` returns, and the client just becomes the
+    // backend's initial cache value so lazy connect is a no-op on
+    // the first Op.
+    #[cfg(windows)]
+    {
+        if let Some(state) = input.state {
+            if let Some(pipe_name) = state
+                .pointer("/transport/shim/pipe_name")
+                .and_then(|v| v.as_str())
+            {
+                backend = backend.with_pipe_hint(pipe_name);
+            }
+        }
+        // Non-state env override still respected (test/diagnostic
+        // path). When set, derive the hint from workspace_hash +
+        // team_key so `dispatch` can lazily connect the first Op.
+        if std::env::var("TEAM_AGENT_FORCE_CONPTY_PIPE_CONNECT")
+            .map(|v| v == "1")
+            .unwrap_or(false)
+            && backend.pipe_hint_ref().is_none()
+        {
+            let pipe_name = conpty_transport::pipe_name_for(&workspace_hash, team_key);
+            backend = backend.with_pipe_hint(pipe_name);
+        }
+    }
+    // Suppress unused warnings on Unix where the cfg(windows) block
+    // above compiles to nothing.
+    #[cfg(not(windows))]
+    {
+        let _ = &workspace_hash;
+    }
     // C-3: if state has BOTH `transport.kind=conpty` and a legacy
     // `tmux_endpoint`, tell the caller so they emit
     // `transport.legacy_tmux_endpoint_ignored`. Same shape for the
@@ -608,6 +657,76 @@ mod tests {
         assert!(resolved.notices.is_empty());
     }
 
+    // 0.5.x Windows portability Batch 5: pipe_ready gate — without a
+    // shim.pipe_ready hint (or the force-env override) the factory
+    // must NOT attempt a connect. Cross-platform test — the
+    // `conpty_pipe_ready` gate is only referenced inside cfg(windows)
+    // but the observable behavior (no notice, no wired client) is
+    // identical on Unix.
+    #[test]
+    fn conpty_without_pipe_ready_hint_emits_no_pipe_client_notice() {
+        let workspace = ws();
+        let state = serde_json::json!({ "transport": { "kind": "conpty" } });
+        let input = TransportFactoryInput::new(&workspace, TransportPurpose::LifecycleWorker)
+            .with_team_key(Some("team-a"))
+            .with_state(Some(&state));
+        let resolved = resolve_transport(input).expect("must succeed");
+        assert_eq!(resolved.kind, BackendKind::ConPty);
+        // No pipe-client notice must appear regardless of platform:
+        // on Unix the block is cfg'd out; on Windows the gate is
+        // closed because no `transport.shim.pipe_ready = true` in
+        // state.
+        for notice in &resolved.notices {
+            assert_ne!(
+                notice.event, "transport.conpty_pipe_client_unwired",
+                "no pipe-client notice without a pipe_ready hint"
+            );
+        }
+    }
+
+    // 0.5.x CR C-5 fix (leader msg_a89b5a03bbf0): factory returns to
+    // pure assembly. The `transport.conpty_pipe_client_unwired`
+    // notice is REMOVED from `build_conpty` — connect is deferred to
+    // the backend's `ensure_pipe_client` lazy path, which surfaces
+    // failures as `TransportError::MuxUnavailable` at Op call time
+    // (not at resolve time).
+    //
+    // Cross-platform: resolve NEVER emits pipe-client notices on
+    // either platform now. This test locks that invariant so a
+    // future revert would fire loudly.
+    #[test]
+    fn conpty_resolve_emits_no_pipe_client_notice_after_c5_fix() {
+        let workspace = ws();
+        let state = serde_json::json!({
+            "transport": {
+                "kind": "conpty",
+                "shim": {
+                    "pipe_name": r"\\.\pipe\team-agent-conpty-test-team-a",
+                    "pipe_ready": true
+                },
+            }
+        });
+        let input = TransportFactoryInput::new(&workspace, TransportPurpose::LifecycleWorker)
+            .with_team_key(Some("team-a"))
+            .with_state(Some(&state));
+        let resolved = resolve_transport(input).expect("must succeed");
+        assert_eq!(resolved.kind, BackendKind::ConPty);
+        let pipe_notices: Vec<_> = resolved
+            .notices
+            .iter()
+            .filter(|n| n.event == "transport.conpty_pipe_client_unwired")
+            .collect();
+        assert!(
+            pipe_notices.is_empty(),
+            "CR C-5 fix: resolve must not emit pipe-client notices \
+             (connect deferred to backend lazy path). Found: {:?}",
+            pipe_notices
+                .iter()
+                .map(|n| &n.event)
+                .collect::<Vec<_>>()
+        );
+    }
+
     // Wire-string invariants for RequestedTransportBackend so a rename
     // in Rust cannot silently drift the CLI accept-list.
     #[test]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.5.2",
-    "@team-agent/cli-darwin-x64": "0.5.2",
-    "@team-agent/cli-linux-x64": "0.5.2"
+    "@team-agent/cli-darwin-arm64": "0.5.3",
+    "@team-agent/cli-darwin-x64": "0.5.3",
+    "@team-agent/cli-linux-x64": "0.5.3"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",