[jakepetroules]

Adds ExecutionResult.resourceUsage: the CPU time, peak memory, page faults, and context switches of every terminated subprocess, for every run overload.

Pitch: Subprocess: Reporting the CPU time and peak memory of terminated child processes

let result = try await run(.name("swiftc"), arguments: ["-O", "main.swift"], output: .discarded)
result.resourceUsage.userTime          // Duration?
result.resourceUsage.peakMemoryUsage   // Int?, bytes

Why Subprocess has to do this

The kernel hands back a child's resource accounting through the same call that reaps it, so the data exists only between the child's exit and its reap. Subprocess owns that window: monitoring and reaping happen inside run(), and the PID is gone by the time it returns. getrusage(RUSAGE_CHILDREN) is a running total over every child the process has waited for, so it can't be attributed to one child when several run concurrently. Reaping the child yourself takes it away from Subprocess, which then can't report its termination status.

API

public struct ResourceUsage: Sendable {
    public var userTime: Duration?
    public var systemTime: Duration?
    public var peakMemoryUsage: Int?            // bytes
    public var minorPageFaults: Int?
    public var majorPageFaults: Int?
    public var voluntaryContextSwitches: Int?
    public var involuntaryContextSwitches: Int?

    public init(userTime: Duration? = nil, /* ... all defaulting to nil */)
}

extension ExecutionResult {
    public var resourceUsage: ResourceUsage { get }
}

• A property is nil when the platform doesn't report that measurement or querying it failed. Zero is a real measurement, never a placeholder.
• ResourceUsage is deliberately not Equatable or Hashable: no two runs measure alike. Individual Duration and Int properties remain comparable.
• ExecutionResult synthesizes Equatable and Hashable, which requires every stored property to conform. It stores the measurement in an internal wrapper whose instances all compare equal and exposes it through a computed property, so ExecutionResult's equality is unchanged by this PR and resourceUsage takes no part in it. Removing those conformances instead would be a breaking change.
• The public initializer exists so callers can construct values, for example in tests. Values produced by Subprocess come only from the kernel.

Property	Darwin, Linux, Android, FreeBSD, OpenBSD	Windows
userTime, systemTime	Always	Unless the query fails
peakMemoryUsage	Always (but see the open issue below for Linux)	Unless the query fails
Page faults, context switches	Always	nil

Implementation

Unix. The reap takes two calls, because no interface on every supported platform reports both pieces completely:

1. A blocking waitid(WEXITED | WNOWAIT) reads the termination status from siginfo_t, exactly as main does, without consuming the zombie. This preserves the full int the child passed to exit where the kernel keeps it (Darwin, FreeBSD).
2. wait4 then reaps the zombie and supplies the rusage. It's the only interface every supported libc exposes that reports rusage for a specific child. Its wait status is discarded, since it holds only the low 8 bits of the exit code.

Subprocess is the only thing that reaps this child, so both calls observe the same zombie. wait4 is reached through a _subprocess_wait4 C shim, because musl declares it only under _GNU_SOURCE/_BSD_SOURCE. Wrapping the libc entry point, rather than issuing Linux's 5-argument waitid syscall, also keeps libc's struct rusage layout in play: the kernel's __kernel_old_timeval fields disagree with libc's wherever time_t is 64-bit on a 32-bit architecture.

ru_maxrss is normalized from KiB to bytes on Linux, Android, FreeBSD, and OpenBSD, saturating rather than trapping if a peak above 2 GiB is reported on a 32-bit platform.

Windows. GetProcessTimes and K32GetProcessMemoryInfo are read just before GetExitCodeProcess, while the process handle is still open. If either fails, its properties are nil rather than failing the reap, since the exit status is the caller's primary result.

Commits

1. Add ResourceUsage — the original change, reaping with wait4 alone.
2. Read the termination status with waitid, not wait4 — fixes a regression in (1), reported by Jonathan Grynspan on the pitch thread: wait4 truncated exit codes to 8 bits, so a child exiting 0x12345 was reported as .exited(0x45) on Darwin and FreeBSD. Adds a regression test.
3. Reshape ResourceUsage in response to pitch feedback — drops the raw rusage member in favor of typed properties, renames maxRSS to peakMemoryUsage, makes properties optional vars with a public initializer, and removes Equatable/Hashable from ResourceUsage.
4. Keep the allocation test's buffer resident long enough to be sampled — FreeBSD samples RSS on clock ticks.

Commit 1 on its own contains the exit-status regression, so this should be squash-merged or have 1 and 2 squashed before merging.

Open issue: peak memory on Linux

Since #365, Subprocess spawns with posix_spawn on Linux, which glibc implements with clone(CLONE_VM | CLONE_VFORK); musl does the same. At exec, the kernel folds the high-water RSS of the address space being replaced into the child's maxrss (exec_mm_put_old in fs/exec.c). Because that address space is the parent's, every child's ru_maxrss is at least the parent's peak RSS. CI shows it: a 1 KiB and a 32 MiB dd both report the test runner's ~80 MB. CPU times, page faults, and context switches are unaffected.

testResourceUsagePeakMemoryUsageScalesWithAllocation currently fails on Linux because of this, and should keep failing until it's resolved. Options are being discussed on the pitch thread.

Testing

• macOS: full suite passes locally (Swift 6.4).
• testExitCodeWiderThanEightBits (Darwin, FreeBSD): runs perl -e 'exit 0x1234' and expects .exited(0x1234); fails without commit 2. A shell can't be used because it truncates its own exit status to 8 bits.
• Unit tests cover rusage conversion, including KiB scaling, the initializer defaults, and ExecutionResult equality ignoring resource usage.
• Integration tests cover CPU time being reported, CPU time rather than wall time being charged, peak memory scaling with allocation, and usage being reported for a signaled child.