@automattic/vip 4.1.2 → 4.1.4

package/internal/debuglog/debuglog.go

@@ -0,0 +1,85 @@
+// Package debuglog emits opt-in diagnostics using Node debug namespace selectors.
+// Loggers belong to an invocation context, so commands and tests cannot leak
+// their debug settings or output writers into another invocation.
+package debuglog
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+	"sync"
+	"unicode"
+)
+
+type contextKey struct{}
+
+type logger struct {
+	mu               sync.Mutex
+	out              io.Writer
+	include, exclude []*regexp.Regexp
+}
+
+// WithLogger accepts comma/whitespace-separated namespaces, '*' wildcards,
+// and '-' exclusions, matching the Node debug package's selector grammar.
+func WithLogger(ctx context.Context, namespaces string, out io.Writer) context.Context {
+	l := &logger{out: out}
+	for _, pattern := range strings.FieldsFunc(namespaces, func(r rune) bool { return r == ',' || unicode.IsSpace(r) }) {
+		exclude := strings.HasPrefix(pattern, "-")
+		pattern = strings.TrimPrefix(pattern, "-")
+		if pattern == "" {
+			continue
+		}
+		expression := "^" + strings.ReplaceAll(regexp.QuoteMeta(pattern), `\*`, ".*") + "$"
+		re := regexp.MustCompile(expression)
+		if exclude {
+			l.exclude = append(l.exclude, re)
+		} else {
+			l.include = append(l.include, re)
+		}
+	}
+	return context.WithValue(ctx, contextKey{}, l)
+}
+
+// Enabled lets callers avoid constructing expensive diagnostic metadata when
+// its namespace is disabled.
+func Enabled(ctx context.Context, namespace string) bool {
+	if ctx == nil {
+		return false
+	}
+	l, _ := ctx.Value(contextKey{}).(*logger)
+	if l == nil || l.out == nil {
+		return false
+	}
+	for _, re := range l.exclude {
+		if re.MatchString(namespace) {
+			return false
+		}
+	}
+	for _, re := range l.include {
+		if re.MatchString(namespace) {
+			return true
+		}
+	}
+	return false
+}
+
+// Printf writes one diagnostic line if namespace is enabled. Callers must pass
+// only safe fields: this function escapes terminal controls, not secrets.
+func Printf(ctx context.Context, namespace, format string, args ...any) {
+	if !Enabled(ctx, namespace) {
+		return
+	}
+	l := ctx.Value(contextKey{}).(*logger)
+	line := namespace + " " + fmt.Sprintf(format, args...)
+	line = strings.Map(func(r rune) rune {
+		if unicode.IsControl(r) {
+			return ' '
+		}
+		return r
+	}, line)
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	_, _ = fmt.Fprintln(l.out, line)
+}

package/internal/debuglog/debuglog_test.go

@@ -0,0 +1,44 @@
+package debuglog
+
+import (
+	"bytes"
+	"context"
+	"strings"
+	"testing"
+)
+
+func TestNamespaceFiltering(t *testing.T) {
+	for _, tc := range []struct{ selector, want string }{
+		{"", ""},
+		{"*", "alpha one\nbeta two\n"},
+		{"alpha", "alpha one\n"},
+		{"a*,beta", "alpha one\nbeta two\n"},
+		{"*,-beta", "alpha one\n"},
+		{"-beta,*", "alpha one\n"},
+		{"alpha beta", "alpha one\nbeta two\n"},
+		{"[ab]*", ""},
+	} {
+		t.Run(tc.selector, func(t *testing.T) {
+			var out bytes.Buffer
+			ctx := WithLogger(context.Background(), tc.selector, &out)
+			Printf(ctx, "alpha", "%s", "one")
+			Printf(ctx, "beta", "%s", "two")
+			if out.String() != tc.want {
+				t.Fatalf("output = %q, want %q", out.String(), tc.want)
+			}
+		})
+	}
+}
+
+func TestLoggerIsScopedToContextAndEscapesControls(t *testing.T) {
+	var out bytes.Buffer
+	ctx := WithLogger(context.Background(), "*", &out)
+	Printf(context.Background(), "alpha", "must stay silent")
+	Printf(ctx, "alpha", "name=%s", "one\n\x1b[31mtwo")
+	if strings.Count(out.String(), "\n") != 1 || strings.Contains(out.String(), "\x1b") {
+		t.Fatalf("unsafe output: %q", out.String())
+	}
+	if !strings.Contains(out.String(), "one") || !strings.Contains(out.String(), "two") {
+		t.Fatalf("missing diagnostic: %q", out.String())
+	}
+}

package/internal/devenv/compose/view.go

@@ -144,9 +144,12 @@ func wordpressTag(d *instancedata.InstanceData) string {
 // phpFPMImagePrefix is the VIP php-fpm image repo; a bare version is appended.
 const phpFPMImagePrefix = "ghcr.io/automattic/vip-container-images/php-fpm:"
 
-// defaultPHPImage is the recommended php-fpm image when none is specified —
-// the first entry of Node's DEV_ENVIRONMENT_PHP_VERSIONS (8.2, recommended).
-const defaultPHPImage = phpFPMImagePrefix + "8.2"
+// DefaultPHPVersion is the recommended PHP version for new environments.
+// Keep this aligned with Node's DEV_ENVIRONMENT_DEFAULT_PHP_VERSION.
+const DefaultPHPVersion = "8.4"
+
+// defaultPHPImage is the recommended php-fpm image when none is specified.
+const defaultPHPImage = phpFPMImagePrefix + DefaultPHPVersion
 
 // phpImage resolves the php-fpm image from instance-data's php field, mirroring
 // Node DEV_ENVIRONMENT_PHP_VERSIONS resolution: empty -> recommended default; a

package/internal/devenv/compose/view_test.go

@@ -108,7 +108,7 @@ func TestNewViewResolvesPHPImage(t *testing.T) {
 		return &instancedata.InstanceData{SiteSlug: "e", Multisite: json.RawMessage("false"), PHP: php}
 	}
 	cases := []struct{ php, want string }{
-		{"", "ghcr.io/automattic/vip-container-images/php-fpm:8.2"},                                                    // empty -> recommended default
+		{"", "ghcr.io/automattic/vip-container-images/php-fpm:8.4"},                                                    // empty -> recommended default
 		{"8.4", "ghcr.io/automattic/vip-container-images/php-fpm:8.4"},                                                 // bare version -> mapped image
 		{"ghcr.io/automattic/vip-container-images/php-fpm:8.3", "ghcr.io/automattic/vip-container-images/php-fpm:8.3"}, // explicit image -> as-is
 	}

package/internal/devenv/debug.go

@@ -0,0 +1,4 @@
+package devenv
+
+// Keep the Node namespace so existing --debug filters work across runtimes.
+const debugNamespace = "@automattic/vip:bin:dev-environment"

package/internal/devenv/debug_test.go

@@ -0,0 +1,103 @@
+package devenv
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/Automattic/vip/internal/debuglog"
+	"github.com/Automattic/vip/internal/devenv/paths"
+)
+
+func fakeDebugDocker(t *testing.T) {
+	t.Helper()
+	t.Setenv("XDG_DATA_HOME", t.TempDir())
+	t.Setenv("DOCKER_HOST", "tcp://user:docker-secret@localhost:1234")
+	bin := t.TempDir()
+	t.Setenv("PATH", bin)
+	// Only this fake is reachable; even an unexpected invocation cannot reach Docker.
+	script := `#!/bin/sh
+case "$*" in
+  "compose version") exit 0 ;;
+  "compose -p running ps --format json --all") echo '{"Service":"php","State":"running","ExitCode":0}' ;;
+  "compose -p stopped ps --format json --all") echo '{"Service":"php","State":"exited","ExitCode":0}' ;;
+  "compose -p failed ps --format json --all") echo 'private-docker-error' >&2; exit 1 ;;
+  *) exit 1 ;;
+esac
+`
+	if err := os.WriteFile(filepath.Join(bin, "docker"), []byte(script), 0o700); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestListDebugExplainsStatusWithoutChangingResults(t *testing.T) {
+	fakeDebugDocker(t)
+	for _, slug := range []string{"failed", "running", "stopped"} {
+		if err := os.MkdirAll(paths.EnvironmentPath(slug), 0o700); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, ns := range []string{"@automattic/vip:bin:dev-environment", "unrelated", ""} {
+		t.Run(ns, func(t *testing.T) {
+			var out bytes.Buffer
+			got, err := List(debuglog.WithLogger(context.Background(), ns, &out))
+			want := []EnvStatus{{Slug: "failed"}, {Slug: "running", Running: true}, {Slug: "stopped"}}
+			if err != nil || !reflect.DeepEqual(got, want) {
+				t.Fatalf("List = %#v, %v", got, err)
+			}
+			if ns != "@automattic/vip:bin:dev-environment" {
+				if out.Len() != 0 {
+					t.Fatalf("unexpected diagnostics: %s", &out)
+				}
+				return
+			}
+			for _, text := range []string{"Names found", "failed", "status query failed", "running=true", "running=false"} {
+				if !strings.Contains(out.String(), text) {
+					t.Errorf("missing %q in %s", text, &out)
+				}
+			}
+			for _, secret := range []string{"docker-secret", "private-docker-error"} {
+				if strings.Contains(out.String(), secret) {
+					t.Errorf("leaked %q", secret)
+				}
+			}
+		})
+	}
+}
+
+func TestDevEnvDebugSummariesOmitArgumentsAndConfig(t *testing.T) {
+	fakeDebugDocker(t)
+	for _, tc := range []struct {
+		name string
+		run  func(context.Context) error
+	}{
+		{"create", func(ctx context.Context) error {
+			return Create(ctx, CreateConfig{Title: "secret-title", Domain: "secret-domain"})
+		}},
+		{"update", func(ctx context.Context) error {
+			value := "secret-config"
+			return Update(ctx, "missing", UpdateConfig{XdebugConfig: &value})
+		}},
+		{"exec", func(ctx context.Context) error {
+			return Exec(ctx, "missing", []string{"config", "set", "DB_PASSWORD", "secret-argument"})
+		}},
+		{"shell", func(ctx context.Context) error {
+			return Shell(ctx, "missing", "php", false, []string{"echo", "secret-argument"})
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var out bytes.Buffer
+			_ = tc.run(debuglog.WithLogger(context.Background(), "@automattic/vip:bin:dev-environment", &out))
+			if !strings.Contains(out.String(), tc.name) {
+				t.Fatalf("missing operation diagnostic: %s", &out)
+			}
+			if strings.Contains(out.String(), "secret-") || strings.Contains(out.String(), "docker-secret") {
+				t.Fatalf("secret in diagnostic: %s", &out)
+			}
+		})
+	}
+}

package/internal/devenv/devenv.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/Automattic/vip/internal/debuglog"
 	"github.com/Automattic/vip/internal/version"
 
 	"github.com/Automattic/vip/internal/devenv/compose"
@@ -28,9 +29,13 @@ import (
 // session logger (set by the cobra layer for create/start), the runner tees its
 // docker output into that per-env log.
 func newRunner(ctx context.Context) (*dockercli.Runner, error) {
-	if _, err := dockercli.DockerSocket(); err != nil {
+	socket, err := dockercli.DockerSocket()
+	if err != nil {
+		debuglog.Printf(ctx, debugNamespace, "Docker endpoint resolution failed")
 		return nil, err
 	}
+	// DOCKER_HOST may contain credentials; only report whether it was resolved.
+	debuglog.Printf(ctx, debugNamespace, "Docker endpoint resolved: explicit=%t", socket != "")
 	return &dockercli.Runner{Log: devlog.FromContext(ctx)}, nil
 }
 
@@ -64,6 +69,7 @@ type StartOptions struct {
 
 // Create writes a new env and (when c.Start) starts it.
 func Create(ctx context.Context, c CreateConfig) error {
+	debuglog.Printf(ctx, debugNamespace, "Will create an environment %q: start=%t", c.Slug, c.Start)
 	if err := writeNewEnv(c); err != nil {
 		return err
 	}
@@ -75,6 +81,7 @@ func Create(ctx context.Context, c CreateConfig) error {
 
 // Start materializes + starts an existing env (detecting migration on first run).
 func Start(ctx context.Context, slug string, opts StartOptions) error {
+	debuglog.Printf(ctx, debugNamespace, "Will start an environment %q: skipRebuild=%t", slug, opts.SkipRebuild)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err
@@ -95,6 +102,7 @@ func PlanLandoMigration(ctx context.Context, slug string) (lifecycle.MigrationPl
 
 // Rebuild downs (keeping volumes) + orphan-guards, then re-runs the start stack.
 func Rebuild(ctx context.Context, slug string) error {
+	debuglog.Printf(ctx, debugNamespace, "Will rebuild an environment %q", slug)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err
@@ -110,6 +118,7 @@ func Rebuild(ctx context.Context, slug string) error {
 // the compose files, pull-gates images, and runs lifecycle.Start. Shared by Start
 // and Rebuild.
 func startStack(ctx context.Context, r *dockercli.Runner, deps lifecycle.Deps, slug string, opts StartOptions) error {
+	debuglog.Printf(ctx, debugNamespace, "Will try to get instance data for environment %q", slug)
 	// Write the diagnostic banner to the head of a fresh per-invocation log
 	// (Node parity: writeLogBanner). No-op if the file already has content.
 	if r.Log != nil {
@@ -127,6 +136,7 @@ func startStack(ctx context.Context, r *dockercli.Runner, deps lifecycle.Deps, s
 	if _, err := Materialize(slug, view); err != nil {
 		return err
 	}
+	debuglog.Printf(ctx, debugNamespace, "Environment %q configuration materialized", slug)
 	// One-time Lando adoption: after materialize (so `compose down` finds the
 	// project's compose file) and before Start (so the Go proxy/containers come up
 	// clean on the reused data volume).
@@ -139,7 +149,9 @@ func startStack(ctx context.Context, r *dockercli.Runner, deps lifecycle.Deps, s
 			return err
 		}
 	}
-	pull := lifecycle.ShouldPull(time.Now(), d.PullAfter, registryReachable())
+	reachable := registryReachable()
+	pull := lifecycle.ShouldPull(time.Now(), d.PullAfter, reachable)
+	debuglog.Printf(ctx, debugNamespace, "Registry ghcr.io resolvable=%t; environment %q pull=%t", reachable, slug, pull)
 	if pull {
 		if err := r.Compose(ctx, slug, "pull"); err != nil {
 			return err
@@ -164,6 +176,7 @@ func startStack(ctx context.Context, r *dockercli.Runner, deps lifecycle.Deps, s
 
 // Stop stops an env's containers.
 func Stop(ctx context.Context, slug string) error {
+	debuglog.Printf(ctx, debugNamespace, "Will stop an environment %q", slug)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err
@@ -173,6 +186,7 @@ func Stop(ctx context.Context, slug string) error {
 
 // StopAll stops every on-disk environment (Node `dev-env stop --all`).
 func StopAll(ctx context.Context) error {
+	debuglog.Printf(ctx, debugNamespace, "Will stop all environments")
 	return stopEachEnv(instancedata.AllNames(), func(slug string) error {
 		return Stop(ctx, slug)
 	})
@@ -230,6 +244,7 @@ func eachEnv(names []string, fn func(string) error) error {
 // `--soft`); otherwise the env dir is removed and /etc/hosts is recomputed for
 // the remaining envs.
 func Destroy(ctx context.Context, slug string, soft bool) error {
+	debuglog.Printf(ctx, debugNamespace, "Will destroy an environment %q: preserveFiles=%t", slug, soft)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err
@@ -275,6 +290,7 @@ func Destroy(ctx context.Context, slug string, soft bool) error {
 // /etc/hosts block (only when some env had custom-domain entries — avoids a
 // needless sudo prompt).
 func Purge(ctx context.Context, soft bool) error {
+	debuglog.Printf(ctx, debugNamespace, "Will purge all environments: preserveFiles=%t", soft)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err
@@ -305,6 +321,7 @@ func Purge(ctx context.Context, soft bool) error {
 
 // Info returns a human-readable summary of an env (URL from bound ports + status).
 func Info(ctx context.Context, slug string) (string, error) {
+	debuglog.Printf(ctx, debugNamespace, "Will get info for an environment %q", slug)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return "", err
@@ -323,6 +340,7 @@ func Info(ctx context.Context, slug string) (string, error) {
 // a blank line (Node `dev-env info --all`).
 func InfoAll(ctx context.Context) (string, error) {
 	names := instancedata.AllNames()
+	debuglog.Printf(ctx, debugNamespace, "Will print info for all environments. Names found: %q", names)
 	if len(names) == 0 {
 		return "No local environments found.\n", nil
 	}

package/internal/devenv/devexec.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"os"
 
+	"github.com/Automattic/vip/internal/debuglog"
 	"github.com/Automattic/vip/internal/devenv/devlog"
 	"github.com/Automattic/vip/internal/devenv/devterm"
 	"github.com/Automattic/vip/internal/devenv/dockercli"
@@ -85,6 +86,7 @@ func shellArgv(r *dockercli.Runner, slug, service string, root bool, cmd []strin
 // output to a file) it runs through plain pipes. Either way output tees into
 // the unified log.
 func Exec(ctx context.Context, slug string, wpArgs []string) error {
+	debuglog.Printf(ctx, debugNamespace, "Will exec a WP command in environment %q: arguments=%d", slug, len(wpArgs))
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err
@@ -102,6 +104,7 @@ func Exec(ctx context.Context, slug string, wpArgs []string) error {
 // Shell opens an interactive shell (or runs cmd) in a service container. Like
 // Exec it falls back to plain pipes when stdin is not a terminal.
 func Shell(ctx context.Context, slug, service string, root bool, cmd []string) error {
+	debuglog.Printf(ctx, debugNamespace, "Will open shell in environment %q: service=%q root=%t arguments=%d", slug, service, root, len(cmd))
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err

package/internal/devenv/importdata.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 
 	"github.com/Automattic/vip/internal/appctx"
+	"github.com/Automattic/vip/internal/debuglog"
 	"github.com/Automattic/vip/internal/devenv/dockercli"
 	"github.com/Automattic/vip/internal/searchreplace"
 )
@@ -207,6 +208,7 @@ func containerID(ctx context.Context, r importRunner, slug, service string) (str
 // ImportSQL imports a SQL file into a running env, optionally search-replacing
 // it first. The real docker cp + exec are exercised under the devenv_e2e gate.
 func ImportSQL(ctx context.Context, slug, file string, o ImportOptions) error {
+	debuglog.Printf(ctx, debugNamespace, "Will import SQL into environment %q: inPlace=%t searchReplacePairs=%d", slug, o.InPlace, len(o.SearchReplace))
 	// --in-place rewrites the user's own dump irreversibly. Node reaches
 	// searchAndReplace from here via resolveImportPath (dev-environment-core.ts:854)
 	// with no batchMode, so its "This operation is not reversible" confirm
@@ -296,7 +298,7 @@ func importSQL(ctx context.Context, r importRunner, slug, file string, o ImportO
 	// `wp search-replace` after the import instead (see importMyDumperDump).
 	resolved := file
 	if !isMyDumper && len(o.SearchReplace) > 0 {
-		res, err := searchreplace.Run(file, searchReplacePairs(o.SearchReplace), searchreplace.Options{InPlace: o.InPlace})
+		res, err := searchreplace.RunContext(ctx, file, searchReplacePairs(o.SearchReplace), searchreplace.Options{InPlace: o.InPlace})
 		if err != nil {
 			return err
 		}
@@ -476,6 +478,7 @@ func decompressDumpToTemp(src string) (path string, cleanup func(), err error) {
 
 // ImportMedia copies a local media directory's contents into the env uploads.
 func ImportMedia(ctx context.Context, slug, srcDir string) error {
+	debuglog.Printf(ctx, debugNamespace, "Will import media into environment %q", slug)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err

package/internal/devenv/list.go

@@ -3,6 +3,7 @@ package devenv
 import (
 	"context"
 
+	"github.com/Automattic/vip/internal/debuglog"
 	"github.com/Automattic/vip/internal/devenv/instancedata"
 	"github.com/Automattic/vip/internal/devenv/lifecycle"
 )
@@ -32,9 +33,16 @@ func List(ctx context.Context) ([]EnvStatus, error) {
 	}
 	d := dockerAdapter{r: r}
 	var out []EnvStatus
-	for _, slug := range instancedata.AllNames() {
+	names := instancedata.AllNames()
+	debuglog.Printf(ctx, debugNamespace, "Will print info for all environments. Names found: %q", names)
+	for _, slug := range names {
 		states, err := d.ComposePS(ctx, slug)
 		running := err == nil && anyRunning(states)
+		if err != nil {
+			debuglog.Printf(ctx, debugNamespace, "Environment %q status query failed; reporting stopped", slug)
+		} else {
+			debuglog.Printf(ctx, debugNamespace, "Environment %q: services=%d running=%t", slug, len(states), running)
+		}
 		out = append(out, EnvStatus{Slug: slug, Running: running})
 	}
 	return out, nil

package/internal/devenv/logs.go

@@ -3,6 +3,7 @@ package devenv
 import (
 	"context"
 
+	"github.com/Automattic/vip/internal/debuglog"
 	"github.com/Automattic/vip/internal/devenv/devlog"
 )
 
@@ -27,6 +28,7 @@ func logsArgs(o LogOptions) []string {
 
 // Logs streams an env's container logs, tee'd through the unified log.
 func Logs(ctx context.Context, slug string, o LogOptions) error {
+	debuglog.Printf(ctx, debugNamespace, "Will display logs for environment %q: service=%q follow=%t", slug, o.Service, o.Follow)
 	r, err := newRunner(ctx)
 	if err != nil {
 		return err

package/internal/devenv/proxy/ca.go

@@ -42,14 +42,20 @@ func CAHostPath() string {
 
 // EnsureCA runs a one-shot container that idempotently generates the CA
 // (lndo.site.pem / lndo.site.key) in the shared certs volume.
+//
+// Both one-shot runs here override the image entrypoint with sh: the stock
+// Traefik entrypoint.sh probes whether $1 is a Traefik subcommand and, when it
+// is not, prints "= 'sh' is not a Traefik command: assuming shell execution."
+// to stderr before exec'ing anyway. Bypassing it drops that noise.
 func EnsureCA(ctx context.Context, r DockerRunner) error {
 	// Intentionally omits proxy_config: no CERT_BASENAME/CERT_SANS are passed,
 	// so the script's leaf-cert and Traefik YAML section is skipped entirely.
 	return r.Docker(ctx,
 		"run", "--rm",
+		"--entrypoint", "sh",
 		"-v", ProxyCertsVolume+":/certs",
 		ProxyImage,
-		"sh", "-c", genCertsScript,
+		"-c", genCertsScript,
 	)
 }
 
@@ -74,6 +80,7 @@ func EnsureCert(ctx context.Context, r DockerRunner, req CertRequest) error {
 
 	args := []string{
 		"run", "--rm",
+		"--entrypoint", "sh",
 		"-v", ProxyCertsVolume + ":/certs",
 		"-v", ProxyConfigVolume + ":/proxy_config",
 		"-e", "CERT_BASENAME=" + req.Basename,
@@ -84,7 +91,7 @@ func EnsureCert(ctx context.Context, r DockerRunner, req CertRequest) error {
 	args = append(args,
 		"-e", "CERT_SANS="+strings.Join(req.SANs, " "),
 		ProxyImage,
-		"sh", "-c", genCertsScript,
+		"-c", genCertsScript,
 	)
 
 	return r.Docker(ctx, args...)

package/internal/devenv/proxy/ca_test.go

@@ -32,7 +32,7 @@ func TestEnsureCARunsGenScript(t *testing.T) {
 		t.Fatalf("expected 1 docker call, got %d: %v", len(r.calls), r.calls)
 	}
 	joined := strings.Join(r.calls[0], " ")
-	for _, want := range []string{"run", "--rm", ProxyCertsVolume + ":/certs", ProxyImage, "sh", "-c"} {
+	for _, want := range []string{"run", "--rm", "--entrypoint", "sh", ProxyCertsVolume + ":/certs", ProxyImage, "-c"} {
 		if !strings.Contains(joined, want) {
 			t.Fatalf("EnsureCA call missing %q:\n%s", want, joined)
 		}

package/internal/devenv/proxy/network.go

@@ -7,17 +7,21 @@ import (
 )
 
 // DockerRunner is the slice of dockercli.Runner this package needs. The
-// concrete *dockercli.Runner satisfies it (Docker(ctx, args...) error).
+// concrete *dockercli.Runner satisfies it. Docker tees output to the terminal
+// and log; DockerOut captures stdout silently for read-only state queries.
 type DockerRunner interface {
 	Docker(ctx context.Context, args ...string) error
+	DockerOut(ctx context.Context, args ...string) ([]byte, error)
 }
 
 // EnsureNetwork creates the shared external bridge network if it is absent.
 // Ports Lando's bridge-network role onto our single shared network
 // (compose.ProxyNetwork). docker network inspect returns non-zero when the
-// network does not exist; we then create it.
+// network does not exist; we then create it. The inspect is a pure existence
+// probe, so its stdout (the full network JSON) is captured rather than teed to
+// the terminal.
 func EnsureNetwork(ctx context.Context, r DockerRunner) error {
-	if err := r.Docker(ctx, "network", "inspect", compose.ProxyNetwork); err == nil {
+	if _, err := r.DockerOut(ctx, "network", "inspect", compose.ProxyNetwork); err == nil {
 		return nil
 	}
 	return r.Docker(ctx, "network", "create", "--driver", "bridge", compose.ProxyNetwork)

package/internal/devenv/proxy/network_test.go

@@ -32,6 +32,12 @@ func (f *fakeRunner) Docker(ctx context.Context, args ...string) error {
 	return nil
 }
 
+// DockerOut mirrors Docker's scripting: a matching failSub errors, otherwise
+// empty stdout (no proxy container -> IsRunning false).
+func (f *fakeRunner) DockerOut(ctx context.Context, args ...string) ([]byte, error) {
+	return nil, f.Docker(ctx, args...)
+}
+
 func TestEnsureNetworkCreatesWhenMissing(t *testing.T) {
 	// network inspect fails (missing) -> network create is issued.
 	r := &fakeRunner{failSub: "inspect"}

package/internal/devenv/proxy/proxy.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 )
 
 // EnsureOptions configures an Ensure call. Domain is used in Traefik env vars.
@@ -14,14 +15,35 @@ type EnsureOptions struct {
 	free   func(int) bool
 }
 
-// IsRunning reports whether the proxy container is currently running by
-// inspecting it with `docker inspect`. Because DockerRunner only surfaces an
-// error (no stdout), we treat "inspect succeeds" as "container exists and is
-// running". A *stopped* orphan container also passes this check, so callers
-// that want to replace a stopped proxy should invoke RemoveOrphan first.
+// containerState is the shared proxy container's observed state.
+type containerState int
+
+const (
+	stateAbsent  containerState = iota // no container with ProxyContainerName
+	stateStopped                       // container exists but is not running
+	stateRunning                       // container exists and is running
+)
+
+// inspectState reads the proxy container's running state via
+// `docker inspect -f {{.State.Running}}`. inspect exits 0 for a *stopped*
+// container too (printing "false"), so the exit code alone cannot tell a
+// stopped orphan from a healthy proxy: the printed value must be read.
+func inspectState(ctx context.Context, r DockerRunner) containerState {
+	out, err := r.DockerOut(ctx, "inspect", "-f", "{{.State.Running}}", ProxyContainerName)
+	if err != nil {
+		return stateAbsent
+	}
+	if strings.TrimSpace(string(out)) == "true" {
+		return stateRunning
+	}
+	return stateStopped
+}
+
+// IsRunning reports whether the proxy container exists AND is running. A
+// stopped orphan (e.g. left behind by a Docker restart or a crashed start)
+// reports false; Ensure removes it before starting a fresh proxy.
 func IsRunning(ctx context.Context, r DockerRunner) bool {
-	err := r.Docker(ctx, "inspect", "-f", "{{.State.Running}}", ProxyContainerName)
-	return err == nil
+	return inspectState(ctx, r) == stateRunning
 }
 
 // Ensure starts the shared Traefik proxy if it is not already running,
@@ -38,12 +60,19 @@ func Ensure(ctx context.Context, r DockerRunner, opts EnsureOptions) (Ports, err
 		free = ListenProbe
 	}
 
-	if IsRunning(ctx, r) {
+	switch inspectState(ctx, r) {
+	case stateRunning:
 		// Already running — load whatever ports were persisted last time.
 		// A missing state file yields zero Ports (no error); the caller treats
 		// that as "ports unknown".
 		ports, err := LoadPorts(PortsStatePath())
 		return ports, err
+	case stateStopped:
+		// A stopped orphan holds the container name (and its old port
+		// bindings), so `docker run --name` below would fail. Remove it and
+		// fall through to start a fresh proxy (parity: Node's
+		// ensureNoOrphantProxyContainer).
+		_ = RemoveOrphan(ctx, r)
 	}
 
 	if err := EnsureNetwork(ctx, r); err != nil {