Convert the ca-sandbox docker boundary to an async, cancellable runner (#394 AC-3)

[SUaDtL]

Split out of #394, which delivered the bounded and typed halves. This is the remaining acceptance criterion:

AC-3: Cancellation can interrupt an active Docker call and still executes bounded teardown.

Why it could not ship with #394

spawnSync is by construction uninterruptible. A deadline can be set on it — that is what #394 did, and a hung sandbox exec now terminates and stops the container it targeted — but nothing can interrupt the call once it is in flight. There is no point at which an AbortSignal could be observed, because the calling thread is blocked inside the syscall.

Shipping a deadline that looks cancellable and is not would be worse than the honest gap, so #394 stated it rather than implying it.

What the change actually is

Convert the single docker chokepoint (plugins/ca-sandbox/tools/docker.ts) from spawnSync to an async spawn-based runner that accepts an AbortSignal, then thread await through every consumer:

• build.ts, claude-inside.ts, cli.ts, cp.ts, create.ts, destroy.ts, exec.ts, registry.ts, run.ts

The dockerRun injection seam every command module already exposes makes the test surface tractable — the fakes become async — but the ripple through the CLI dispatch is the bulk of the work, and the CLI's synchronous exit-code contract has to be preserved exactly.

Acceptance criteria

• AC-1: an in-flight docker call aborts when its signal fires, rather than running to completion or to its deadline.
• AC-2: an aborted call still executes the same bounded teardown a timeout does — for exec, the container it targeted is stopped.
• AC-3: the CLI's observable contract is unchanged: same exit codes, same stdout JSON, same stderr diagnostics.
• AC-4: the existing per-operation deadlines from Bound every sandbox Docker invocation and terminate timed-out execs #394 continue to apply, and a timeout is still typed distinctly from an abort.
• AC-5: covered on every OS where Docker is available, through the existing docker-gate layer discipline.

Relevant sources

• plugins/ca-sandbox/tools/docker.ts — runDocker, DOCKER_OPERATION_TIMEOUTS_MS, makeDockerRun
• plugins/ca-sandbox/tools/exec.ts — the timeout escalation added by Bound every sandbox Docker invocation and terminate timed-out execs #394
• plugins/ca-sandbox/tools/deadline.test.ts — the tests to extend

[SUaDtL]

Scoping brief — read before starting

Scoped but not started; the type change ripples, so there is no partial landing that compiles. Recording the design and five findings so the next pass starts here rather than re-deriving them.

The ripple is much smaller than the issue implies

runCli is already async and already returns Promise<number>, and cli.ts's entry already does .then((code) => process.exit(code)). So AC-3's hard part — preserving a synchronous exit-code contract across an async conversion — is already plumbed. Nothing about the CLI's observable shape has to change.

Production dockerRun( call sites: 15, across 7 files — claude-inside.ts 3, cp.ts 1, create.ts 4, destroy.ts 1, exec.ts 2, registry.ts 3, run.ts 1. Not the ~75 an early estimate suggested; that number counted test occurrences.

Five things that will bite

1. maxBuffer does not exist on spawn. It is a spawnSync/execFile option, and makeDockerRun's extra: Partial<SpawnSyncOptionsWithStringEncoding> is how claude-inside.ts currently widens it to 64 MB. The cap has to be re-implemented inside the runner (accumulate, compare Buffer.byteLength, kill on breach), and makeDockerRun's signature has to split genuine spawn options from the cap instead of passing both through as one bag.

2. close(null, "SIGKILL") is identical for a timeout-kill and an abort-kill. The runner cannot classify the outcome from the close event, so it must record which killer fired (killedBy: "timeout" | "abort" | "overflow") before calling child.kill, and map from that. AC-4 depends entirely on this.

3. The current sync path mis-reports an output overflow as a timeout. runDocker derives timedOut from (r.status === null && r.signal !== null), and a spawnSync maxBuffer breach kills the child — so ENOBUFS lands on that same branch and returns exit 124 with a "timed out" message. Unobserved today because claude-inside.ts widens the cap past anything real, but the async rewrite should type overflow distinctly rather than port the conflation forward.

4. A pre-aborted signal must not start a container at all. Check signal.aborted before spawn, not only after — otherwise cancelling during a multi-step command still creates the next container, and AC-2's "bounded teardown" then has something new to clean up that the caller never knew existed.

5. The test fakes have to become async child doubles. Seven test files inject dockerRun, and deadline.test.ts additionally injects spawn itself as a function returning a plain object ({ status, stdout, stderr }). That has to become an EventEmitter with stdout/stderr streams and a kill() that emits close. Worth a shared helper in the test file rather than seven hand-rolled doubles.

Shape

export type RunResult = { code: number; stdout: string; stderr: string;
                          timedOut?: boolean; aborted?: boolean; overflowed?: boolean };
export const DOCKER_ABORT_EXIT_CODE = 130;          // SIGINT convention
export type DockerCallOptions = { signal?: AbortSignal };
export type DockerRun = (args: string[], call?: DockerCallOptions) => Promise<RunResult>;

exec.ts's existing timeout escalation (docker stop --time 0 <id>, --time 0 because a --time 5 never completes inside a 4s runner deadline) becomes the shared teardown path for both timedOut and aborted — that is AC-2, and it is the one place where abort has to do more than propagate.

The SIGINT handler belongs in cli.ts's entry, not in docker.ts: one AbortController per CLI run, SIGINT → abort(), and exit 130. docker.ts stays a primitive that observes a signal it is handed.

Verification

AC-5 says every OS where Docker is available, through the existing docker-gate layer discipline. The abort path is assertable without a daemon via the injected spawn seam; AC-2's real teardown needs the gated live layer, same as #394's a sleeping exec is killed at the deadline test.