fix!: close divergences from the reference CLI and gate on go-tools

.github/deadcode-allow.txt

@@ -0,0 +1,2 @@
+# Functions no binary reaches that are correct for ever, one `<symbol>  # why` a line (go tool deadgate -allow).
+# An entry that matches nothing fails, so the list only shrinks.

.github/deadcode-pending.txt

@@ -0,0 +1,2 @@
+# Functions no binary reaches whose deletion somebody owes, one `<symbol>  # why` a line (go tool deadgate -pending).
+# Printed on every green run; an entry that matches nothing fails.

.github/testquality-allow.txt

@@ -0,0 +1,3 @@
+# Tests testquality reports that are kept on purpose, one <package>:<TestName> a line with why
+# (go tool testquality -allow). An entry that matches nothing fails, so the list only shrinks.
+github.com/devcontainers/cli/internal/exec:TestHelperProcess  # the child process OSRunner tests exec; it asserts nothing by design, the parent tests do

.github/workflows/go-cli.yml

@@ -19,11 +19,50 @@ on:
 permissions:
   contents: read
 
+# A newer push to a branch makes the run before it moot, so that run is cancelled; never on main,
+# whose every commit needs its answer. 3 of 11 push runs (2026-10-23..25) ran for a commit a newer
+# push had replaced.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/master' }}
+
+# The jobs that build and run containers land on spin-stack's docker8 fleet (spin-stack/ci: an
+# ephemeral 8-vCPU EC2 instance per job, no nested virtualization). On GitHub's 4-vCPU runners a
+# runtime parity shard took 10.7 min at p50 and 14.4 at p90, against 5.0 on Blacksmith's. A pull
+# request from a fork runs on GitHub's runners instead: its code never reaches spin-stack's AWS
+# account. Only a branch of this repository, which takes write access to push, runs on the fleet.
+
 jobs:
+  # What a pull request changed, broken one small edit at a time (go-tools mutate): an
+  # edit no test refuses fails, so new code arrives with tests that hold it.
+  mutate:
+    if: github.event_name == 'pull_request'
+    runs-on: ${{ (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && 'runs-on/fleet=docker8/env=production' || 'ubuntu-latest' }}
+    # 4 min on GitHub's runners for a diff's 200 mutations; a large diff's builds are many.
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version-file: go.mod
+      - name: What this change broke, and whether a test noticed
+        env:
+          BASE: origin/${{ github.base_ref }}
+        run: go tool task mutate
+
   lint-and-test:
     runs-on: ubuntu-latest
+    # p90 3.2 min on GitHub's runners.
+    timeout-minutes: 15
     permissions:
       contents: read
+    outputs:
+      # Where the jobs that build and run containers land (see the top of this file).
+      fleet: ${{ (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && 'runs-on/fleet=docker8/env=production' || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
@@ -51,7 +90,9 @@ jobs:
           if-no-files-found: error
 
   e2e:
-    runs-on: ubuntu-latest
+    runs-on: ${{ needs.lint-and-test.outputs.fleet }}
+    # p90 1.6 min on GitHub's runners.
+    timeout-minutes: 15
     needs: lint-and-test
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -75,7 +116,10 @@ jobs:
   # Hermetic parity gate: read-configuration golden comparison + the contract
   # lane of the parity matrix (flag validation / output contract, no Docker).
   parity:
+    # The contract and network lanes start no container: GitHub's runner is enough.
     runs-on: ubuntu-latest
+    # p90 2.0 min on GitHub's runners.
+    timeout-minutes: 10
     needs: lint-and-test
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -124,6 +168,7 @@ jobs:
   daily-changes:
     if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     outputs:
       run: ${{ steps.check.outputs.run }}
     steps:
@@ -139,7 +184,7 @@ jobs:
   #             run with the plain binary: a fast gate (the full matrix is ~45 min).
   #   daily   — the FULL matrix with the instrumented binary, so one run gates parity
   #             AND measures coverage; daily-changes keeps it off on quiet days.
-  # 4 shards across independent runners (each its own docker daemon) so the matrix
+  # 2 shards across independent runners (each its own docker daemon) so the matrix
   # never contends for one runner's CPU/disk/daemon. PARITY_SHARD_TOTAL MUST equal the
   # length of matrix.shard — parity_sharding_workflow_test.go enforces it so a mismatch
   # can't silently drop cases.
@@ -153,18 +198,25 @@ jobs:
       && needs.lint-and-test.result == 'success'
       && (github.event_name == 'push' || github.event_name == 'pull_request'
           || needs.daily-changes.outputs.run == 'true')
-    runs-on: ubuntu-latest
+    runs-on: ${{ needs.lint-and-test.outputs.fleet }}
+    # A shard took 14.4 min at p90 as one of four on GitHub's runners; one of two on them (a
+    # fork's pull request) takes about twice that.
+    timeout-minutes: 45
     strategy:
-      fail-fast: false
+      # On a push or a pull request the first failing shard stops the other: what it would have
+      # found is in the next push's run. The daily run keeps going, since it also measures
+      # coverage.
+      fail-fast: ${{ github.event_name == 'push' || github.event_name == 'pull_request' }}
       matrix:
-        shard: [0, 1, 2, 3]
+        shard: [0, 1]
     env:
       PARITY_RUNTIME_TIMEOUT: "10m"
-      # Each shard owns ~a quarter of the selected cases; -parallel 2 per 2-core runner
-      # is the proven-safe load (per-case id-label / COMPOSE_PROJECT_NAME isolation).
-      PARITY_PARALLEL: "2"
+      # Each shard owns half of the selected cases. -parallel 2 was the proven load on a
+      # 4-vCPU runner (per-case id-label / COMPOSE_PROJECT_NAME isolation); docker8's 8 vCPU
+      # hold twice that.
+      PARITY_PARALLEL: ${{ needs.lint-and-test.outputs.fleet == 'ubuntu-latest' && '2' || '4' }}
       PARITY_SHARD_INDEX: ${{ matrix.shard }}
-      PARITY_SHARD_TOTAL: "4"
+      PARITY_SHARD_TOTAL: "2"
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -220,7 +272,10 @@ jobs:
   parity-publish-full:
     needs: [lint-and-test, daily-changes]
     if: needs.daily-changes.outputs.run == 'true'
-    runs-on: ubuntu-latest
+    # Daily and dispatched only: this repository's own code.
+    runs-on: runs-on/fleet=docker8/env=production
+    # p90 3.3 min on GitHub's runners.
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -247,6 +302,7 @@ jobs:
   parity-runtime-gate:
     if: always()
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     needs: [lint-and-test, e2e, parity, parity-runtime, parity-publish-full]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -277,6 +333,7 @@ jobs:
 
   cross-compile:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     needs: lint-and-test
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7

.github/workflows/release.yml

@@ -78,7 +78,12 @@ jobs:
 
   # Runtime lane (real Docker containers). ubuntu-latest ships Docker.
   gate-runtime:
-    runs-on: ubuntu-latest
+    # A tag push or a dispatch: this repository's own code, so spin-stack's docker8 fleet (see
+    # go-cli.yml), where the whole runtime matrix is one job.
+    runs-on: runs-on/fleet=docker8/env=production
+    # e2e, the whole runtime matrix and publish parity in one job; the matrix alone is about 45
+    # min on a 4-vCPU runner.
+    timeout-minutes: 90
     needs: prepare
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -178,6 +183,9 @@ jobs:
 
       - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
 
+      # The released image's base, by digest from versions.yaml.
+      - run: go tool task release:env
+
       - uses: goreleaser/goreleaser-action@a4f02ab5355a589de60d917a659ce617ed19b3de # v7
         with:
           distribution: goreleaser

.golangci.yml

@@ -17,8 +17,6 @@ linters:
         - fmt.Fprintln
         - (*github.com/spf13/pflag.FlagSet).MarkHidden
         - (*github.com/spf13/cobra.Command).MarkFlagRequired
-        - github.com/devcontainers/cli/internal/pfs.Remove
-        - github.com/devcontainers/cli/internal/pfs.MkdirAll
         # Best-effort metadata/config parsing: on failure the target stays zero
         # (an accepted fallback throughout); behavioral divergences are caught by
         # the parity matrix, not by these unchecked returns.

.goreleaser.yml

@@ -73,6 +73,8 @@ dockers_v2:
     build_args:
       VERSION: "{{ .Version }}"
       REVISION: "{{ .FullCommit }}"
+      # The base image by digest, from versions.yaml (task release:env).
+      DISTROLESS_IMAGE: "{{ .Env.DISTROLESS_IMAGE }}"
     labels:
       org.opencontainers.image.title: devcontainer-cli
       org.opencontainers.image.source: https://github.com/spin-stack/devcontainer-cli

Dockerfile

@@ -18,8 +18,12 @@
 # context. For a local single-arch build:
 #   mkdir -p linux/amd64
 #   CGO_ENABLED=0 go build -o linux/amd64/devcontainer ./cmd/devcontainer
-#   docker buildx build --platform linux/amd64 --load -t devcontainer-cli .
-FROM gcr.io/distroless/static:nonroot
+#   docker buildx build --platform linux/amd64 --load $(go tool versions args distroless) -t devcontainer-cli .
+#
+# The base is pinned by digest in versions.yaml (distroless) and handed in: GoReleaser
+# reads it from DISTROLESS_IMAGE, which `task release:env` exports.
+ARG DISTROLESS_IMAGE
+FROM ${DISTROLESS_IMAGE}
 
 # Version/revision are injected at build time. GoReleaser passes them via
 # build_args; a local build can pass --build-arg VERSION=... .