Phase 2: Implement Execution Environment Abstraction (v0.3.0)

This commit implements Phase 2 of the CHORUS Task Execution Engine development plan,
providing a comprehensive execution environment abstraction layer with Docker
container sandboxing support.

## New Features

### Core Sandbox Interface
- Comprehensive ExecutionSandbox interface with isolated task execution
- Support for command execution, file I/O, environment management
- Resource usage monitoring and sandbox lifecycle management
- Standardized error handling with SandboxError types and categories

### Docker Container Sandbox Implementation
- Full Docker API integration with secure container creation
- Transparent repository mounting with configurable read/write access
- Advanced security policies with capability dropping and privilege controls
- Comprehensive resource limits (CPU, memory, disk, processes, file handles)
- Support for tmpfs mounts, masked paths, and read-only bind mounts
- Container lifecycle management with proper cleanup and health monitoring

### Security & Resource Management
- Configurable security policies with SELinux, AppArmor, and Seccomp support
- Fine-grained capability management with secure defaults
- Network isolation options with configurable DNS and proxy settings
- Resource monitoring with real-time CPU, memory, and network usage tracking
- Comprehensive ulimits configuration for process and file handle limits

### Repository Integration
- Seamless repository mounting from local paths to container workspaces
- Git configuration support with user credentials and global settings
- File inclusion/exclusion patterns for selective repository access
- Configurable permissions and ownership for mounted repositories

### Testing Infrastructure
- Comprehensive test suite with 60+ test cases covering all functionality
- Docker integration tests with Alpine Linux containers (skipped in short mode)
- Mock sandbox implementation for unit testing without Docker dependencies
- Security policy validation tests with read-only filesystem enforcement
- Resource usage monitoring and cleanup verification tests

## Technical Details

### Dependencies Added
- github.com/docker/docker v28.4.0+incompatible - Docker API client
- github.com/docker/go-connections v0.6.0 - Docker connection utilities
- github.com/docker/go-units v0.5.0 - Docker units and formatting
- Associated Docker API dependencies for complete container management

### Architecture
- Interface-driven design enabling multiple sandbox implementations
- Comprehensive configuration structures for all sandbox aspects
- Resource usage tracking with detailed metrics collection
- Error handling with retryable error classification
- Proper cleanup and resource management throughout sandbox lifecycle

### Compatibility
- Maintains backward compatibility with existing CHORUS architecture
- Designed for future integration with Phase 3 Core Task Execution Engine
- Extensible design supporting additional sandbox implementations (VM, process)

This Phase 2 implementation provides the foundation for secure, isolated task
execution that will be integrated with the AI model providers from Phase 1
in the upcoming Phase 3 development.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

vendor/github.com/docker/go-connections/sockets/inmem_socket.go

@@ -0,0 +1,81 @@
+package sockets
+
+import (
+	"errors"
+	"net"
+	"sync"
+)
+
+var errClosed = errors.New("use of closed network connection")
+
+// InmemSocket implements net.Listener using in-memory only connections.
+type InmemSocket struct {
+	chConn  chan net.Conn
+	chClose chan struct{}
+	addr    string
+	mu      sync.Mutex
+}
+
+// dummyAddr is used to satisfy net.Addr for the in-mem socket
+// it is just stored as a string and returns the string for all calls
+type dummyAddr string
+
+// NewInmemSocket creates an in-memory only net.Listener
+// The addr argument can be any string, but is used to satisfy the `Addr()` part
+// of the net.Listener interface
+func NewInmemSocket(addr string, bufSize int) *InmemSocket {
+	return &InmemSocket{
+		chConn:  make(chan net.Conn, bufSize),
+		chClose: make(chan struct{}),
+		addr:    addr,
+	}
+}
+
+// Addr returns the socket's addr string to satisfy net.Listener
+func (s *InmemSocket) Addr() net.Addr {
+	return dummyAddr(s.addr)
+}
+
+// Accept implements the Accept method in the Listener interface; it waits for the next call and returns a generic Conn.
+func (s *InmemSocket) Accept() (net.Conn, error) {
+	select {
+	case conn := <-s.chConn:
+		return conn, nil
+	case <-s.chClose:
+		return nil, errClosed
+	}
+}
+
+// Close closes the listener. It will be unavailable for use once closed.
+func (s *InmemSocket) Close() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	select {
+	case <-s.chClose:
+	default:
+		close(s.chClose)
+	}
+	return nil
+}
+
+// Dial is used to establish a connection with the in-mem server
+func (s *InmemSocket) Dial(network, addr string) (net.Conn, error) {
+	srvConn, clientConn := net.Pipe()
+	select {
+	case s.chConn <- srvConn:
+	case <-s.chClose:
+		return nil, errClosed
+	}
+
+	return clientConn, nil
+}
+
+// Network returns the addr string, satisfies net.Addr
+func (a dummyAddr) Network() string {
+	return string(a)
+}
+
+// String returns the string form
+func (a dummyAddr) String() string {
+	return string(a)
+}

vendor/github.com/docker/go-connections/sockets/proxy.go

@@ -0,0 +1,31 @@
+package sockets
+
+import (
+	"net"
+	"os"
+	"strings"
+)
+
+// GetProxyEnv allows access to the uppercase and the lowercase forms of
+// proxy-related variables.  See the Go specification for details on these
+// variables. https://golang.org/pkg/net/http/
+//
+// Deprecated: this function was used as helper for [DialerFromEnvironment] and is no longer used. It will be removed in the next release.
+func GetProxyEnv(key string) string {
+	proxyValue := os.Getenv(strings.ToUpper(key))
+	if proxyValue == "" {
+		return os.Getenv(strings.ToLower(key))
+	}
+	return proxyValue
+}
+
+// DialerFromEnvironment was previously used to configure a net.Dialer to route
+// connections through a SOCKS proxy.
+//
+// Deprecated: SOCKS proxies are now supported by configuring only
+// http.Transport.Proxy, and no longer require changing http.Transport.Dial.
+// Therefore, only [sockets.ConfigureTransport] needs to be called, and any
+// [sockets.DialerFromEnvironment] calls can be dropped.
+func DialerFromEnvironment(direct *net.Dialer) (*net.Dialer, error) {
+	return direct, nil
+}

vendor/github.com/docker/go-connections/sockets/sockets.go

@@ -0,0 +1,66 @@
+// Package sockets provides helper functions to create and configure Unix or TCP sockets.
+package sockets
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"syscall"
+	"time"
+)
+
+const (
+	defaultTimeout        = 10 * time.Second
+	maxUnixSocketPathSize = len(syscall.RawSockaddrUnix{}.Path)
+)
+
+// ErrProtocolNotAvailable is returned when a given transport protocol is not provided by the operating system.
+var ErrProtocolNotAvailable = errors.New("protocol not available")
+
+// ConfigureTransport configures the specified [http.Transport] according to the specified proto
+// and addr.
+//
+// If the proto is unix (using a unix socket to communicate) or npipe the compression is disabled.
+// For other protos, compression is enabled. If you want to manually enable/disable compression,
+// make sure you do it _after_ any subsequent calls to ConfigureTransport is made against the same
+// [http.Transport].
+func ConfigureTransport(tr *http.Transport, proto, addr string) error {
+	switch proto {
+	case "unix":
+		return configureUnixTransport(tr, proto, addr)
+	case "npipe":
+		return configureNpipeTransport(tr, proto, addr)
+	default:
+		tr.Proxy = http.ProxyFromEnvironment
+		tr.DisableCompression = false
+		tr.DialContext = (&net.Dialer{
+			Timeout: defaultTimeout,
+		}).DialContext
+	}
+	return nil
+}
+
+// DialPipe connects to a Windows named pipe. It is not supported on
+// non-Windows platforms.
+//
+// Deprecated: use [github.com/Microsoft/go-winio.DialPipe] or [github.com/Microsoft/go-winio.DialPipeContext].
+func DialPipe(addr string, timeout time.Duration) (net.Conn, error) {
+	return dialPipe(addr, timeout)
+}
+
+func configureUnixTransport(tr *http.Transport, proto, addr string) error {
+	if len(addr) > maxUnixSocketPathSize {
+		return fmt.Errorf("unix socket path %q is too long", addr)
+	}
+	// No need for compression in local communications.
+	tr.DisableCompression = true
+	dialer := &net.Dialer{
+		Timeout: defaultTimeout,
+	}
+	tr.DialContext = func(ctx context.Context, _, _ string) (net.Conn, error) {
+		return dialer.DialContext(ctx, proto, addr)
+	}
+	return nil
+}

vendor/github.com/docker/go-connections/sockets/sockets_unix.go

@@ -0,0 +1,18 @@
+//go:build !windows
+
+package sockets
+
+import (
+	"net"
+	"net/http"
+	"syscall"
+	"time"
+)
+
+func configureNpipeTransport(tr *http.Transport, proto, addr string) error {
+	return ErrProtocolNotAvailable
+}
+
+func dialPipe(_ string, _ time.Duration) (net.Conn, error) {
+	return nil, syscall.EAFNOSUPPORT
+}

vendor/github.com/docker/go-connections/sockets/sockets_windows.go

@@ -0,0 +1,23 @@
+package sockets
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"time"
+
+	"github.com/Microsoft/go-winio"
+)
+
+func configureNpipeTransport(tr *http.Transport, proto, addr string) error {
+	// No need for compression in local communications.
+	tr.DisableCompression = true
+	tr.DialContext = func(ctx context.Context, _, _ string) (net.Conn, error) {
+		return winio.DialPipeContext(ctx, addr)
+	}
+	return nil
+}
+
+func dialPipe(addr string, timeout time.Duration) (net.Conn, error) {
+	return winio.DialPipe(addr, &timeout)
+}

vendor/github.com/docker/go-connections/sockets/tcp_socket.go

@@ -0,0 +1,22 @@
+// Package sockets provides helper functions to create and configure Unix or TCP sockets.
+package sockets
+
+import (
+	"crypto/tls"
+	"net"
+)
+
+// NewTCPSocket creates a TCP socket listener with the specified address and
+// the specified tls configuration. If TLSConfig is set, will encapsulate the
+// TCP listener inside a TLS one.
+func NewTCPSocket(addr string, tlsConfig *tls.Config) (net.Listener, error) {
+	l, err := net.Listen("tcp", addr)
+	if err != nil {
+		return nil, err
+	}
+	if tlsConfig != nil {
+		tlsConfig.NextProtos = []string{"http/1.1"}
+		l = tls.NewListener(l, tlsConfig)
+	}
+	return l, nil
+}

vendor/github.com/docker/go-connections/sockets/unix_socket.go

@@ -0,0 +1,84 @@
+/*
+Package sockets is a simple unix domain socket wrapper.
+
+# Usage
+
+For example:
+
+	import(
+		"fmt"
+		"net"
+		"os"
+		"github.com/docker/go-connections/sockets"
+	)
+
+	func main() {
+		l, err := sockets.NewUnixSocketWithOpts("/path/to/sockets",
+			sockets.WithChown(0,0),sockets.WithChmod(0660))
+		if err != nil {
+			panic(err)
+		}
+		echoStr := "hello"
+
+		go func() {
+			for {
+				conn, err := l.Accept()
+				if err != nil {
+					return
+				}
+				conn.Write([]byte(echoStr))
+				conn.Close()
+			}
+		}()
+
+		conn, err := net.Dial("unix", path)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		buf := make([]byte, 5)
+		if _, err := conn.Read(buf); err != nil {
+			panic(err)
+		} else if string(buf) != echoStr {
+			panic(fmt.Errorf("msg may lost"))
+		}
+	}
+*/
+package sockets
+
+import (
+	"net"
+	"os"
+	"syscall"
+)
+
+// SockOption sets up socket file's creating option
+type SockOption func(string) error
+
+// NewUnixSocketWithOpts creates a unix socket with the specified options.
+// By default, socket permissions are 0000 (i.e.: no access for anyone); pass
+// WithChmod() and WithChown() to set the desired ownership and permissions.
+//
+// This function temporarily changes the system's "umask" to 0777 to work around
+// a race condition between creating the socket and setting its permissions. While
+// this should only be for a short duration, it may affect other processes that
+// create files/directories during that period.
+func NewUnixSocketWithOpts(path string, opts ...SockOption) (net.Listener, error) {
+	if err := syscall.Unlink(path); err != nil && !os.IsNotExist(err) {
+		return nil, err
+	}
+
+	l, err := listenUnix(path)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, op := range opts {
+		if err := op(path); err != nil {
+			_ = l.Close()
+			return nil, err
+		}
+	}
+
+	return l, nil
+}

vendor/github.com/docker/go-connections/sockets/unix_socket_unix.go

@@ -0,0 +1,54 @@
+//go:build !windows
+
+package sockets
+
+import (
+	"net"
+	"os"
+	"syscall"
+)
+
+// WithChown modifies the socket file's uid and gid
+func WithChown(uid, gid int) SockOption {
+	return func(path string) error {
+		if err := os.Chown(path, uid, gid); err != nil {
+			return err
+		}
+		return nil
+	}
+}
+
+// WithChmod modifies socket file's access mode.
+func WithChmod(mask os.FileMode) SockOption {
+	return func(path string) error {
+		if err := os.Chmod(path, mask); err != nil {
+			return err
+		}
+		return nil
+	}
+}
+
+// NewUnixSocket creates a unix socket with the specified path and group.
+func NewUnixSocket(path string, gid int) (net.Listener, error) {
+	return NewUnixSocketWithOpts(path, WithChown(0, gid), WithChmod(0o660))
+}
+
+func listenUnix(path string) (net.Listener, error) {
+	// net.Listen does not allow for permissions to be set. As a result, when
+	// specifying custom permissions ("WithChmod()"), there is a short time
+	// between creating the socket and applying the permissions, during which
+	// the socket permissions are Less restrictive than desired.
+	//
+	// To work around this limitation of net.Listen(), we temporarily set the
+	// umask to 0777, which forces the socket to be created with 000 permissions
+	// (i.e.: no access for anyone). After that, WithChmod() must be used to set
+	// the desired permissions.
+	//
+	// We don't use "defer" here, to reset the umask to its original value as soon
+	// as possible. Ideally we'd be able to detect if WithChmod() was passed as
+	// an option, and skip changing umask if default permissions are used.
+	origUmask := syscall.Umask(0o777)
+	l, err := net.Listen("unix", path)
+	syscall.Umask(origUmask)
+	return l, err
+}

vendor/github.com/docker/go-connections/sockets/unix_socket_windows.go

@@ -0,0 +1,7 @@
+package sockets
+
+import "net"
+
+func listenUnix(path string) (net.Listener, error) {
+	return net.Listen("unix", path)
+}