test(parity): serialize the cases that share the Feature content image

Without BuildKit both CLIs build Features from the fixed tag
dev_container_feature_content_temp, so two such cases at once can take
each other's Features. On the docker8 fleet the TS side failed that
way twice (an up in setup_cmd failing silently, then exec or verify
finding no container). A case can now name a lock; cases with the same
lock run one at a time and stay parallel with the rest. The 24 cases
that build Features without BuildKit hold feature-content-image, and
TestParityMatrixLocksTheFeatureContentImage keeps that list exact.

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

Author: aledbf

docs/parity/parity-matrix.yaml

@@ -1375,6 +1375,7 @@ initial_cases:
     current_status: match
 
   - id: build.buildkit-never-platform-failure
+    lock: feature-content-image
     lane: contract
     command: build
     priority: p1
@@ -1593,6 +1594,7 @@ initial_cases:
     current_status: match
 
   - id: exec.workspace-image-with-features-hello-success
+    lock: feature-content-image
     lane: runtime
     command: exec
     priority: p1
@@ -1606,6 +1608,7 @@ initial_cases:
     current_status: match
 
   - id: exec.workspace-dockerfile-with-features-hello-success
+    lock: feature-content-image
     lane: runtime
     command: exec
     priority: p1
@@ -1619,6 +1622,7 @@ initial_cases:
     current_status: match
 
   - id: exec.workspace-dockerfile-with-target-marker-success
+    lock: feature-content-image
     lane: runtime
     command: exec
     priority: p1
@@ -1632,6 +1636,7 @@ initial_cases:
     current_status: match
 
   - id: exec.workspace-compose-image-with-features-hello-success
+    lock: feature-content-image
     no_compose_isolation: true
     lane: runtime
     command: exec
@@ -1971,6 +1976,7 @@ initial_cases:
     current_status: match
 
   - id: up.image-with-features-omit-config-remote-env-from-metadata-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2009,6 +2015,7 @@ initial_cases:
     current_status: match
 
   - id: up.compose-image-with-features-omit-config-remote-env-from-metadata-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2024,6 +2031,7 @@ initial_cases:
     notes: "Unblocked by pinning the harness setup with `docker pull --platform linux/amd64 redis:alpine` (the fixture's db service) before compose."
 
   - id: up.compose-dockerfile-with-features-omit-config-remote-env-from-metadata-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2051,6 +2059,7 @@ initial_cases:
     current_status: match
 
   - id: up.image-metadata-container-env-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2063,6 +2072,7 @@ initial_cases:
     current_status: match
 
   - id: up.image-with-features-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2077,6 +2087,7 @@ initial_cases:
     current_status: match
 
   - id: up.image-with-git-feature-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2182,6 +2193,7 @@ initial_cases:
     current_status: match
 
   - id: up.compose-dockerfile-with-features-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2196,6 +2208,7 @@ initial_cases:
     notes: "Closed out by fixing the compose entrypoint generated by Go so that it uses real line breaks and keeps the container alive"
 
   - id: up.compose-dockerfile-with-features-reuse-stopped-container-with-persisted-overrides-success
+    lock: feature-content-image
     no_compose_isolation: true
     serial: true
     lane: runtime
@@ -2213,6 +2226,7 @@ initial_cases:
     notes: "Reuse of a stopped compose container with persisted overrides. The divergence observed before (TS failed the second `docker compose up --no-recreate`) was an artifact of the setup with the old TS path; with the setup pointing to the TS submodule, Go and TS match."
 
   - id: up.compose-dockerfile-with-features-reuse-stopped-container-without-persisted-overrides-success
+    lock: feature-content-image
     no_compose_isolation: true
     serial: true
     lane: runtime
@@ -2292,6 +2306,7 @@ initial_cases:
     current_status: match
 
   - id: up.compose-dockerfile-with-target-post-commands-success
+    lock: feature-content-image
     lane: runtime
     command: up
     priority: p1
@@ -2458,6 +2473,7 @@ initial_cases:
     current_status: match
 
   - id: build.image-metadata-local-features-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p1
@@ -2471,6 +2487,7 @@ initial_cases:
     current_status: match
 
   - id: build.skip-persisting-customizations-from-features-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p1
@@ -2484,6 +2501,7 @@ initial_cases:
     current_status: match
 
   - id: build.labels-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p0
@@ -2495,6 +2513,7 @@ initial_cases:
     current_status: match
 
   - id: build.local-feature-failure
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p0
@@ -2531,6 +2550,7 @@ initial_cases:
     current_status: match
 
   - id: build.dockerfile-multi-image-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p1
@@ -2607,6 +2627,7 @@ initial_cases:
     notes: "Passes in parity runtime by pinning DOCKER_DEFAULT_PLATFORM=linux/amd64 from the harness"
 
   - id: build.apply-build-options-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p1
@@ -2635,6 +2656,7 @@ initial_cases:
     notes: "Closed out using a valid cache source (`ubuntu:latest`); the nonexistent remote ref blocked TS before comparing Go."
 
   - id: build.image-metadata-container-env-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p1
@@ -2647,6 +2669,7 @@ initial_cases:
     current_status: match
 
   - id: build.compose-image-extra-cache-from-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p1
@@ -2746,6 +2769,7 @@ initial_cases:
       expect_infra_failure the harness compares exit codes instead of skipping via isInfraError."
 
   - id: build.compose-image-with-features-success
+    lock: feature-content-image
     lane: runtime
     command: build
     priority: p1

internal/cli/parity_lock_test.go

@@ -0,0 +1,76 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+)
+
+var (
+	parityWorkspaceFlag  = regexp.MustCompile(`--workspace-folder\s+(src/test/configs/[^\s"';]+)`)
+	parityConfigFlag     = regexp.MustCompile(`--config\s+(src/test/configs/[^\s"';]+)`)
+	nonEmptyFeaturesJSON = regexp.MustCompile(`"features"\s*:\s*\{\s*"`)
+)
+
+// A case that builds Features without BuildKit goes through the shared
+// dev_container_feature_content_temp image, so it must hold the
+// feature-content-image lock; a case that does not, must not, so the lock
+// serializes no more than it has to.
+func TestParityMatrixLocksTheFeatureContentImage(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join("..", "..", "docs", "parity", "parity-matrix.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var matrix parityMatrix
+	if err := yaml.Unmarshal(raw, &matrix); err != nil {
+		t.Fatal(err)
+	}
+	locked := 0
+	for _, tc := range matrix.InitialCases {
+		if _, ok := parityLocks[tc.Lock]; tc.Lock != "" && !ok {
+			t.Errorf("case %q names unknown lock %q", tc.ID, tc.Lock)
+		}
+		cmds := tc.TSCmd + "\n" + tc.SetupCmd
+		need := strings.Contains(cmds, "--buildkit=never") && slices.ContainsFunc(parityCaseConfigs(t, cmds), func(config string) bool {
+			data, err := os.ReadFile(filepath.Join("..", "..", config))
+			if err != nil {
+				t.Fatalf("case %q: %v", tc.ID, err)
+			}
+			return nonEmptyFeaturesJSON.Match(data)
+		})
+		switch has := tc.Lock == "feature-content-image"; {
+		case need && !has:
+			t.Errorf("case %q builds Features without BuildKit; add `lock: feature-content-image`", tc.ID)
+		case has && !need:
+			t.Errorf("case %q holds feature-content-image but builds no Features without BuildKit", tc.ID)
+		case has:
+			locked++
+		}
+	}
+	if locked == 0 {
+		t.Error("no case holds feature-content-image")
+	}
+}
+
+// parityCaseConfigs is every devcontainer.json the commands name, by
+// --config or as a --workspace-folder's.
+func parityCaseConfigs(t *testing.T, cmds string) []string {
+	var configs []string
+	for _, m := range parityConfigFlag.FindAllStringSubmatch(cmds, -1) {
+		configs = append(configs, m[1])
+	}
+	for _, m := range parityWorkspaceFlag.FindAllStringSubmatch(cmds, -1) {
+		for _, c := range []string{".devcontainer/devcontainer.json", ".devcontainer.json"} {
+			if _, err := os.Stat(filepath.Join("..", "..", m[1], c)); err == nil {
+				configs = append(configs, filepath.Join(m[1], c))
+				break
+			}
+		}
+	}
+	return configs
+}

internal/cli/parity_matrix_test.go

@@ -68,6 +68,10 @@ type parityCase struct {
 	// Serial forces a case to run sequentially (no t.Parallel). Used for the few
 	// runtime cases that can't be isolated for parallel execution.
 	Serial bool `yaml:"serial"`
+	// Lock names a Docker resource the case shares with other cases and cannot
+	// isolate; cases with the same lock run one at a time, still in parallel
+	// with every other case. See parityLocks.
+	Lock string `yaml:"lock"`
 	// CompareHashes keeps sha256/hex digests UNSCRUBBED so they are compared
 	// exactly between TS and Go. Set it for cases whose digests are deterministic
 	// and meaningful (resolve-dependencies installOrder resource@digest,
@@ -189,6 +193,16 @@ func writeParityReport(path string, snapshot map[parityOutcome][]string) error {
 	return nil
 }
 
+// parityLocks are the shared resources a case can name in `lock`.
+//
+// feature-content-image: without BuildKit, both CLIs build a Feature's files
+// into the fixed tag dev_container_feature_content_temp (TS containerFeatures.ts
+// getFeaturesBuildOptions) and build FROM it, so two such builds at once can
+// take each other's Features.
+var parityLocks = map[string]*sync.Mutex{
+	"feature-content-image": {},
+}
+
 // --- Main test ---
 
 func TestParityMatrix(t *testing.T) {
@@ -314,6 +328,14 @@ func TestParityMatrix(t *testing.T) {
 				outcome = paritySkippedArm64
 				t.Skip("arm64 experimental (set PARITY_ARM64=true to run; requires arm64 emulation)")
 			}
+			if tc.Lock != "" {
+				mu, ok := parityLocks[tc.Lock]
+				if !ok {
+					t.Fatalf("unknown lock %q", tc.Lock)
+				}
+				mu.Lock()
+				defer mu.Unlock()
+			}
 			perCaseTimeout := defaultTimeout
 			if tc.Lane == "runtime" {
 				perCaseTimeout = runtimeTimeout