# Go command environments

`internal/gotool` resolves effective Go settings once for a validation or build
operation and applies the shared environment to its Go commands. It uses
`internal/process` for cancellation, the working directory, output, and wrapped
errors.

## Command output ownership

`Tool.Run` executes a status-only command. It forwards combined stdout and
stderr to the optional writer while the child runs, then releases its capture
on success. Failures include the captured diagnostic text and preserve the
underlying process or forwarding error.

`Tool.Output` returns combined stdout and stderr for commands whose output is
needed by the caller, such as compiler identification. After the child stops,
the capture's backing bytes transfer to the caller without a second copy. A
failed output command returns both those bytes and an error containing the
diagnostic text. The capture remains in memory for the duration of the child;
an 8 MiB forwarded capture currently allocates about 8.39 MB per operation,
with the returned 8 MiB slice owned by its caller. Failed output also formats
diagnostics into the error, so the returned bytes and diagnostic string can
coexist. Disk-backed diagnostics could reduce large failure peaks, but add file
lifecycle and cleanup work and remain a follow-up option.

Dependency preparation uses a separate command environment so proxy, private
module, checksum, and cache settings remain available. Its completed capture
uses the same ownership transfer when formatting a failure.

## Configuration discovery

The owner asks the installed `go` command for `GOHOSTOS` and `GOHOSTARCH`, then
queries effective operational settings with that host selected. Both queries
use `GOTOOLCHAIN=local` and controlled `GOFLAGS`. Discovery sets
`GOEXPERIMENT=none` and clears architecture feature variables so an invalid or
nonbaseline tuning value cannot prevent settings from being read. The
experiment override is discovery-only.

The persistent Go environment remains active during discovery. The owner copies
the effective cache and module-cache locations, Go root, temporary directory,
and native cgo/C-tool configuration into its settings. This captures values
supplied by either the process environment or the persistent Go environment
file.

Configuration discovery parses JSON from stdout. Stderr is captured separately
and included in command-failure diagnostics, so a successful query can emit
warnings while supplying valid configuration.

## Command environments

Every Go command receives `GOENV=off`, so removed persistent values cannot
return. ReleaseKit owns `GOFLAGS=-mod=readonly`, `GOWORK=off`,
`GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`.
Native commands use `GOHOSTOS` and `GOHOSTARCH` and retain the effective
`CGO_ENABLED`, `CC`, `CXX`, `PKG_CONFIG`, and `CGO_CFLAGS`, `CGO_CPPFLAGS`,
`CGO_CXXFLAGS`, and `CGO_LDFLAGS`. Static commands use the selected target and
`CGO_ENABLED=0`.

Both modes clear `GOEXPERIMENT` and the Go architecture feature variables
`GOAMD64`, `GOARM`, `GOARM64`, `GO386`, `GOMIPS`, `GOMIPS64`, `GOPPC64`,
`GORISCV64`, and `GOWASM`. The selected Go toolchain supplies its ordinary
baseline values. Effective `GOCACHE`, `GOCACHEPROG`, `GOMODCACHE`, `GOPATH`,
`GOROOT`, and `GOTMPDIR` values are retained. Other process variables remain
available to child commands.

Candidate validation uses native mode for the offline `go test` suite and
selected full `go vet` pass. Package-compilation checks use static mode for each
selected target and direct Go's output to the operating system null device, so
they leave no binary artifact. Artifact builds also use static mode for
selected-target compilation, then build the native version-check executable;
that executable runs as a normal child process.