[Bug]: ClientProcess.kill always fails with "missing signal in xpc message" - client sends the signal as an integer, server reads it as a string

[JeronimoColon]

I have done the following

• I have searched the existing issues
• If possible, I've reproduced the issue using the 'main' branch of this project

Steps to reproduce

The failure is in the client library (ContainerAPIClient), so the reproduction is a small Swift program rather than a CLI command.

1. Start the engine and create a throwaway container to exec into:

container system start
container run --detach --name kill-repro alpine sleep 600

2. Build and run this program in a package that depends on github.com/apple/container (product ContainerAPIClient):

import ContainerAPIClient
import Foundation

let client = ContainerClient()
let container = try await client.get(id: "kill-repro")

// Start an exec'd process (a long sleep) so there is a live process to signal.
var processConfig = container.configuration.initProcess
processConfig.executable = "/bin/sleep"
processConfig.arguments = ["300"]
processConfig.terminal = false

let process = try await client.createProcess(
    containerId: container.id,
    processId: UUID().uuidString.lowercased(),
    configuration: processConfig,
    stdio: [nil, nil, nil]
)
try await process.start()

do {
    try await process.kill(SIGKILL)
    print("kill succeeded")
} catch {
    print("kill failed: \(error)")
}

3. Observe that kill throws and the sleep keeps running:

kill failed: invalidArgument: "missing signal in xpc message"

The same happens with every signal value, not only SIGKILL.

4. Clean up: container delete --force kill-repro

Problem description

ClientProcess.kill(_: Int32) never delivers a signal. Every call fails with invalidArgument: "missing signal in xpc message".

The cause is a type mismatch in the XPC message between the client and the API server. The client writes the signal as an integer (Sources/Services/ContainerAPIService/Client/ClientProcess.swift):

request.set(key: .signal, value: Int64(signal))

but the server's handler for the .containerKill route reads that key as a string, and rejects the request when the string is absent (Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift, the signal() helper):

guard let signal = self.string(key: .signal) else {
    throw ContainerizationError(.invalidArgument, message: "missing signal in xpc message")
}

The container-level kill shows the intended contract: ContainerClient.kill(id:signal:) takes the signal as a String, writes it as a string, and works. ClientProcess.kill is the odd one out. Since it is also the only API that targets a specific process, there is currently no working way to signal an exec'd process through the client library at all. In practice that means a timeout or cancel feature built on createProcess can stop waiting for a command, but cannot terminate it; the command keeps running until the container stops. The failure is also easy to miss, because kill is the kind of call that often gets wrapped in try?.

What I would expect: the client and server agree on the wire type, and the signal is delivered.

I observed the failure at runtime on container 1.0.0. The client write and the server read are both unchanged at tag 1.1.0 and on current main (checked at 5f277a9), so I expect it reproduces there as well.

Related work I found while searching: #1747 reports this same root cause surfacing through terminal-resize signal forwarding, and #1778 fixes the client-side encoding. The approach in #1778 (send the signal name rather than a number) looks right to me: Darwin and Linux disagree on some signal numbers (USR1 is 30 on Darwin and 10 on Linux), so a numeric passthrough could deliver the wrong signal even if the server accepted numbers.

Environment

• OS: macOS 26.5.2 (25F84)
• Xcode: 26.6 (17F113)
• Container: container CLI 1.0.0 (build: release, commit: ee848e3)

Code of Conduct

• I agree to follow this project's Code of Conduct

[wouterdebie]

Confirming this, and adding version scope: the mismatch is present in both the 1.0.0 and 1.1.0 release tags, not just main. Client side encodes an integer (Sources/Services/ContainerAPIService/Client/ClientProcess.swift, request.set(key: .signal, value: Int64(signal))); server side reads a string (Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift, guard let signal = self.string(key: .signal)). Same class of bug as #1747 (SIGWINCH forwarding).

Real-world impact from a client-library consumer (Davit, a GUI for this platform): any exec you need to time out, for example docker-compose-style healthcheck probes, cannot be killed. The probe process has to be abandoned and keeps running in the guest until the container stops, so a hung healthcheck command accumulates orphaned in-guest processes and pipe fds in the client for as long as the container lives. We work around it by capping abandoned probes and failing the health wait, but a working kill is the actual fix.

Happy to send a PR if maintainers agree on the direction; the minimal fix is making both sides agree on the encoding (either side works, though changing the server to read int64 also stays wire-compatible with old CLIs that never successfully sent kill anyway).