fix: docker.sock reliability + release 1.0.7

.cursor/rules/calf.mdc

@@ -122,6 +122,7 @@ calf/
 │   │   │   ├── cli_ops.go                      Shared container/image/volume/network/registry ops embedded by Native and Guest
 │   │   │   ├── native.go                       Native runtime: talks directly to host nerdctl/docker.sock (Linux)
 │   │   │   ├── guest_darwin.go                 Shared guest disk/EFI/vsock helpers (embedded by Krunkit)
+│   │   │   ├── container_ghosts.go             Detect/wipe corrupt empty-name docker leftovers on macOS guest
 │   │   │   ├── guest_disk_fetch_darwin.go       First-run GitHub disk download + zstd extract
 │   │   │   ├── nerdctl.go                      Shared nerdctl output parsing, compose project inference, log filtering
 │   │   │   ├── buildx.go                       Docker buildx build --load args, builder bootstrap
@@ -166,7 +167,7 @@ calf/
 │   │   ├── daemon/                             stats_history + docker_socket_proxy tests
 │   │   ├── dockercli/context_test.go
 │   │   ├── dockerhub/device_test.go
-│   │   ├── runtime/                            build_enrich, build_parser, buildx, command_error, container_mounts, image_history, localhost_proxy, nerdctl, network, prune, registry, rootless, volume_detail tests
+│   │   ├── runtime/                            build_enrich, build_parser, buildx, command_error, container_ghosts, container_mounts, image_history, localhost_proxy, nerdctl, network, prune, registry, rootless, volume_detail tests
 │   │   └── volumeexport/                       name_pattern, schedule_timing tests
 │   ├── version/version.go                     Single Version constant
 │   └── go.mod / go.sum                        Module github.com/enegalan/calf/backend, Go 1.22.1
@@ -358,6 +359,7 @@ Docker Hub OAuth2 device-code flow client. Polls for a token, decodes JWT claims
 - `cli_ops.go` — `cliOps`: the container/image/volume/network/registry operations that are identical between `Native` and `Guest` (a `requireRunning`/`emptyIfStopped` guard around a shared `nerdctl.go`-style helper called through a runtime-specific command runner). `Native` and `Guest` embed it and wire up `status`/`runLocal`/`runLocalWithStdin` in their constructors; operations that differ between the two runtimes stay defined directly on `Native`/`Guest`.
 - `native.go` — `Native` runtime: talks directly to a host `nerdctl`/`docker.sock` on Linux, with optional rootless user-socket preference.
 - `guest_darwin.go` — shared guest disk/EFI/vsock helpers embedded by `Krunkit`. Disk under `~/.config/calf/guest/`; release assets `calf-guest-disk-*`; `$HOME` bind mounts via `calf-home` virtiofs.
+- `container_ghosts.go` — detect empty-name corrupt container leftovers and build the guest wipe/restart script used on engine start.
 - `unsupported.go` — Windows stub Runtime until a new backend lands.
 - `guest_disk_fetch_darwin.go` — first-run GitHub Release download + pure-Go zstd extract for `calf-guest-disk-<arch>.raw.zst`.
 - `nerdctl.go` — shared low-level helpers: JSON-line parsing of `nerdctl ps/images/volume ls/history` output, compose project/service inference, log-line noise filtering, log streaming plumbing.

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.7] - 2026-08-15
+
+### Fixed
+
+- **Docker CLI EOF on macOS** — parallel `docker` / Compose calls no longer leave stuck engine-socket connections that make later commands fail with EOF. calf limits concurrent vsock use so the guest socket stays responsive under load.
+- **Empty `docker run` / `docker exec` output on macOS** — attach streams keep working through `docker.sock`. calf does not half-close the engine vsock after the CLI finishes sending a hijacked request, and plain API calls use `Connection: close` so keep-alive cannot wedge the socket under load.
+- **Empty resource lists** — Containers, Images, Volumes, and similar API lists return `[]` when empty instead of `null`.
+- **Guest helper leftovers** — interrupted guest setup commands no longer leave behind `calf-guestcmd-*` containers; calf retries cleanup and prunes them on engine start.
+- **Anonymous alpine leftovers on macOS** — guest mount setup no longer leaves nameless helper containers behind after a socket blip. Corrupt engine entries that show in `docker ps` but cannot be inspected are cleaned up when the engine starts.
+
+### Changed
+
+- **`verify-docker-cli`** — uses `docker compose` when available, otherwise falls back to `docker-compose`, and counts compose step failures correctly.
+
 ## [1.0.6] - 2026-08-15
 
 ### Changed

CLAUDE.md

@@ -118,6 +118,7 @@ calf/
 │   │   │   ├── cli_ops.go                      Shared container/image/volume/network/registry ops embedded by Native and Guest
 │   │   │   ├── native.go                       Native runtime: talks directly to host nerdctl/docker.sock (Linux)
 │   │   │   ├── guest_darwin.go                 Shared guest disk/EFI/vsock helpers (embedded by Krunkit)
+│   │   │   ├── container_ghosts.go             Detect/wipe corrupt empty-name docker leftovers on macOS guest
 │   │   │   ├── guest_disk_fetch_darwin.go       First-run GitHub disk download + zstd extract
 │   │   │   ├── nerdctl.go                      Shared nerdctl output parsing, compose project inference, log filtering
 │   │   │   ├── buildx.go                       Docker buildx build --load args, builder bootstrap
@@ -162,7 +163,7 @@ calf/
 │   │   ├── daemon/                             stats_history + docker_socket_proxy tests
 │   │   ├── dockercli/context_test.go
 │   │   ├── dockerhub/device_test.go
-│   │   ├── runtime/                            build_enrich, build_parser, buildx, command_error, container_mounts, image_history, localhost_proxy, nerdctl, network, prune, registry, rootless, volume_detail tests
+│   │   ├── runtime/                            build_enrich, build_parser, buildx, command_error, container_ghosts, container_mounts, image_history, localhost_proxy, nerdctl, network, prune, registry, rootless, volume_detail tests
 │   │   └── volumeexport/                       name_pattern, schedule_timing tests
 │   ├── version/version.go                     Single Version constant
 │   └── go.mod / go.sum                        Module github.com/enegalan/calf/backend, Go 1.22.1
@@ -354,6 +355,7 @@ Docker Hub OAuth2 device-code flow client. Polls for a token, decodes JWT claims
 - `cli_ops.go` — `cliOps`: the container/image/volume/network/registry operations that are identical between `Native` and `Guest` (a `requireRunning`/`emptyIfStopped` guard around a shared `nerdctl.go`-style helper called through a runtime-specific command runner). `Native` and `Guest` embed it and wire up `status`/`runLocal`/`runLocalWithStdin` in their constructors; operations that differ between the two runtimes stay defined directly on `Native`/`Guest`.
 - `native.go` — `Native` runtime: talks directly to a host `nerdctl`/`docker.sock` on Linux, with optional rootless user-socket preference.
 - `guest_darwin.go` — shared guest disk/EFI/vsock helpers embedded by `Krunkit`. Disk under `~/.config/calf/guest/`; release assets `calf-guest-disk-*`; `$HOME` bind mounts via `calf-home` virtiofs.
+- `container_ghosts.go` — detect empty-name corrupt container leftovers and build the guest wipe/restart script used on engine start.
 - `unsupported.go` — Windows stub Runtime until a new backend lands.
 - `guest_disk_fetch_darwin.go` — first-run GitHub Release download + pure-Go zstd extract for `calf-guest-disk-<arch>.raw.zst`.
 - `nerdctl.go` — shared low-level helpers: JSON-line parsing of `nerdctl ps/images/volume ls/history` output, compose project/service inference, log-line noise filtering, log streaming plumbing.

backend/internal/daemon/core.go

@@ -86,7 +86,11 @@ func (s *Core) startDockerSocketProxy() {
 	if public == "" || engine == "" || public == engine {
 		return
 	}
-	proxy := newDockerSocketProxy(s.Logger, public, engine, s.lifecycleCtx, s.EnsureRuntimeRunning)
+	var gater engineConnGater
+	if g, ok := s.Runtime.(engineConnGater); ok {
+		gater = g
+	}
+	proxy := newDockerSocketProxy(s.Logger, public, engine, s.lifecycleCtx, s.EnsureRuntimeRunning, gater)
 	if err := proxy.Start(); err != nil {
 		s.Logger.Warn("docker socket proxy failed to start", "error", err)
 		return

backend/internal/daemon/docker_socket_proxy.go

@@ -1,6 +1,7 @@
 package daemon
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"io"
@@ -16,12 +17,24 @@ import (
 )
 
 const (
-	dockerProxyMaxConcurrent   = 16
+	// dockerProxyMaxConcurrent caps simultaneous dials into krunkit vsock.
+	// Keep this modest: high fan-out floods virtio-vsock. Too low deadlocks
+	// clients (e.g. docker CLI) that open more than one connection per command.
+	dockerProxyMaxConcurrent   = 8
 	dockerProxyReclaimInterval = 2 * time.Second
+	dockerProxyDialProbe       = 2 * time.Second
+	dockerProxyDialAfterWake   = 30 * time.Second
+	dockerProxyMaxHTTPHeader   = 1 << 20
 
 	dockerProxyModeListen int32 = 0
 )
 
+// engineConnGater limits concurrent use of the guest Docker engine socket (vsock).
+type engineConnGater interface {
+	AcquireEngineConn(ctx context.Context) error
+	ReleaseEngineConn()
+}
+
 // dockerSocketProxy listens on the public Docker CLI socket and forwards to the
 // engine vsock socket. When the engine is stopped (Resource Saver), the first
 // CLI connection wakes it via EnsureRuntimeRunning before forwarding.
@@ -35,6 +48,7 @@ type dockerSocketProxy struct {
 	engine    string
 	wake      func(context.Context) error
 	lifecycle context.Context
+	gater     engineConnGater
 	gate      chan struct{}
 	mode      atomic.Int32
 	switchMu  sync.Mutex
@@ -52,13 +66,14 @@ type engineDockerSocketer interface {
 }
 
 // newDockerSocketProxy builds a wake-on-connect proxy when public and engine paths differ.
-func newDockerSocketProxy(logger *slog.Logger, public, engine string, lifecycle context.Context, wake func(context.Context) error) *dockerSocketProxy {
+func newDockerSocketProxy(logger *slog.Logger, public, engine string, lifecycle context.Context, wake func(context.Context) error, gater engineConnGater) *dockerSocketProxy {
 	return &dockerSocketProxy{
 		logger:    logger,
 		public:    public,
 		engine:    engine,
 		wake:      wake,
 		lifecycle: lifecycle,
+		gater:     gater,
 		gate:      make(chan struct{}, dockerProxyMaxConcurrent),
 		stopCh:    make(chan struct{}),
 		doneCh:    make(chan struct{}),
@@ -287,24 +302,22 @@ func (p *dockerSocketProxy) handle(client net.Conn) {
 	if p.lifecycle != nil {
 		parent = p.lifecycle
 	}
-	select {
-	case p.gate <- struct{}{}:
-		defer func() { <-p.gate }()
-	case <-parent.Done():
+	if err := p.acquireConn(parent); err != nil {
 		return
 	}
+	defer p.releaseConn()
 
 	ctx, cancel := context.WithTimeout(parent, constants.GuestDiskFetchTimeout+3*time.Minute)
 	defer cancel()
 
-	server, err := p.dialEngine(ctx, 400*time.Millisecond)
+	server, err := p.dialEngine(ctx, dockerProxyDialProbe)
 	if err != nil {
 		p.logger.Info("docker CLI connected while engine stopped; waking")
 		if wakeErr := p.wake(ctx); wakeErr != nil {
 			p.logger.Warn("docker socket wake failed", "error", wakeErr)
 			return
 		}
-		server, err = p.dialEngine(ctx, 30*time.Second)
+		server, err = p.dialEngine(ctx, dockerProxyDialAfterWake)
 		if err != nil {
 			p.logger.Warn("docker socket dial engine failed", "error", err)
 			return
@@ -315,6 +328,31 @@ func (p *dockerSocketProxy) handle(client net.Conn) {
 	proxyUnixConnection(client, server)
 }
 
+// acquireConn takes a shared vsock slot (or the local gate when no gater is set).
+func (p *dockerSocketProxy) acquireConn(ctx context.Context) error {
+	if p.gater != nil {
+		return p.gater.AcquireEngineConn(ctx)
+	}
+	select {
+	case p.gate <- struct{}{}:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// releaseConn frees the slot taken by acquireConn.
+func (p *dockerSocketProxy) releaseConn() {
+	if p.gater != nil {
+		p.gater.ReleaseEngineConn()
+		return
+	}
+	select {
+	case <-p.gate:
+	default:
+	}
+}
+
 // dialEngine connects to the krunkit vsock socket, retrying until timeout.
 func (p *dockerSocketProxy) dialEngine(ctx context.Context, timeout time.Duration) (net.Conn, error) {
 	var d net.Dialer
@@ -341,34 +379,108 @@ func (p *dockerSocketProxy) dialEngine(ctx context.Context, timeout time.Duratio
 	return nil, lastErr
 }
 
-// proxyUnixConnection copies bytes both ways and half-closes on EOF.
+// proxyUnixConnection forwards one Docker API connection.
+//
+// Plain HTTP requests get Connection: close so dockerd ends the response and
+// frees the vsock slot (keep-alive would wedge after the CLI half-closes).
+// Hijacked streams (Upgrade: tcp) keep both directions open without
+// CloseWrite on the engine side — vsock treats half-close as full teardown,
+// which drops `docker run`/`exec` stdout.
 func proxyUnixConnection(client, server net.Conn) {
-	done := make(chan struct{}, 2)
+	head, rest, upgrade, err := readDockerAPIRequestHead(client)
+	if err != nil {
+		return
+	}
+	if !upgrade {
+		head = forceHTTPConnectionClose(head)
+	}
+	if _, err := server.Write(head); err != nil {
+		return
+	}
 
+	clientReader := io.Reader(client)
+	if len(rest) > 0 {
+		clientReader = io.MultiReader(bytes.NewReader(rest), client)
+	}
+
+	done := make(chan struct{}, 2)
 	go func() {
-		_, _ = io.Copy(server, client)
-		closeWriteConn(server)
+		_, _ = io.Copy(server, clientReader)
 		done <- struct{}{}
 	}()
-
 	go func() {
 		_, _ = io.Copy(client, server)
-		closeWriteConn(client)
 		done <- struct{}{}
 	}()
 
-	<-done
-	<-done
+	if upgrade {
+		<-done
+		<-done
+	} else {
+		<-done
+		_ = client.Close()
+		_ = server.Close()
+		<-done
+	}
+	_ = client.Close()
+	_ = server.Close()
 }
 
-// closeWriteConn half-closes the write side when the connection type supports it.
-func closeWriteConn(conn net.Conn) {
-	type closeWriter interface {
-		CloseWrite() error
+// readDockerAPIRequestHead reads until the end of HTTP headers (or EOF).
+func readDockerAPIRequestHead(r io.Reader) (head, rest []byte, upgrade bool, err error) {
+	buf := make([]byte, 0, 4096)
+	tmp := make([]byte, 2048)
+	for {
+		if len(buf) > dockerProxyMaxHTTPHeader {
+			return nil, nil, false, fmt.Errorf("docker API headers exceed %d bytes", dockerProxyMaxHTTPHeader)
+		}
+		n, readErr := r.Read(tmp)
+		if n > 0 {
+			buf = append(buf, tmp[:n]...)
+			if idx := bytes.Index(buf, []byte("\r\n\r\n")); idx >= 0 {
+				head = buf[:idx+4]
+				rest = buf[idx+4:]
+				return head, rest, httpRequestHeadIsUpgrade(head), nil
+			}
+		}
+		if readErr != nil {
+			if len(buf) == 0 {
+				return nil, nil, false, readErr
+			}
+			if readErr == io.EOF {
+				return buf, nil, httpRequestHeadIsUpgrade(buf), nil
+			}
+			return nil, nil, false, readErr
+		}
 	}
-	if cw, ok := conn.(closeWriter); ok {
-		_ = cw.CloseWrite()
+}
+
+// httpRequestHeadIsUpgrade reports a Docker API hijack (attach/exec/raw stream).
+func httpRequestHeadIsUpgrade(head []byte) bool {
+	return bytes.Contains(bytes.ToLower(head), []byte("\r\nupgrade:"))
+}
+
+// forceHTTPConnectionClose strips Connection headers and adds Connection: close.
+func forceHTTPConnectionClose(head []byte) []byte {
+	if len(head) == 0 {
+		return head
+	}
+	trimmed := bytes.TrimSuffix(head, []byte("\r\n\r\n"))
+	lines := bytes.Split(trimmed, []byte("\r\n"))
+	out := make([][]byte, 0, len(lines)+1)
+	for i, line := range lines {
+		if i == 0 {
+			out = append(out, line)
+			continue
+		}
+		lower := bytes.ToLower(line)
+		if bytes.HasPrefix(lower, []byte("connection:")) {
+			continue
+		}
+		out = append(out, line)
 	}
+	out = append(out, []byte("Connection: close"))
+	return append(bytes.Join(out, []byte("\r\n")), []byte("\r\n\r\n")...)
 }
 
 // resolveEngineDockerSocket returns the vsock path when the runtime exposes one.
@@ -383,10 +495,15 @@ func resolveEngineDockerSocket(rt interface{ DockerSocket() string }) string {
 
 // NewDockerSocketProxyForTest constructs a wake-on-connect proxy for unit tests.
 func NewDockerSocketProxyForTest(public, engine string, lifecycle context.Context, wake func(context.Context) error) *DockerSocketProxy {
-	inner := newDockerSocketProxy(slog.Default(), public, engine, lifecycle, wake)
+	inner := newDockerSocketProxy(slog.Default(), public, engine, lifecycle, wake, nil)
 	return &DockerSocketProxy{inner: inner}
 }
 
+// ProxyUnixConnectionForTest exposes proxyUnixConnection for leak-regression tests.
+func ProxyUnixConnectionForTest(client, server net.Conn) {
+	proxyUnixConnection(client, server)
+}
+
 // DockerSocketProxy is the exported test/handle surface for the public Docker CLI socket proxy.
 type DockerSocketProxy struct {
 	inner *dockerSocketProxy

backend/internal/httpkit/response.go

@@ -4,14 +4,28 @@ import (
 	"encoding/json"
 	"log/slog"
 	"net/http"
+	"reflect"
 	"strings"
 )
 
 // WriteJSON encodes payload as JSON and writes it with the given HTTP status.
+// Nil slices encode as [] so list endpoints never return JSON null.
 func WriteJSON(w http.ResponseWriter, status int, payload any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(payload)
+	_ = json.NewEncoder(w).Encode(nonNilJSONPayload(payload))
+}
+
+// nonNilJSONPayload replaces a nil slice with an empty slice of the same type.
+func nonNilJSONPayload(payload any) any {
+	if payload == nil {
+		return payload
+	}
+	value := reflect.ValueOf(payload)
+	if value.Kind() != reflect.Slice || !value.IsNil() {
+		return payload
+	}
+	return reflect.MakeSlice(value.Type(), 0, 0).Interface()
 }
 
 // WriteError writes a JSON error response with the given status and message.