[udaychandra]

Spec: audit-process-lifecycle (audit F15, P1).

What changes

• BoundedProcess.await(CancellationToken) replaces await(). It waits with Process.waitFor(timeout). On timeout, cancellation, interrupt or any exception while waiting it kills and reaps the tree, then rethrows with the interrupt status set again. Cancelling the token sends SIGTERM on the token's thread and then runs kill() on a virtual thread, so a SIGTERM-deaf child is killed forcibly and does not keep the call waiting until the timeout. A child the call killed reports exit code -1.
• BoundedProcess.kill() kills and reaps. Descendants are captured once, before the first signal. Every signal also reaches descendants still visible at that moment. Whatever is alive after BoundedProcess.GRACE (2 s) is destroyed forcibly, whether or not the parent has exited. kill() returns once the tree has ended, or after a second GRACE. Each grace is timed on the waiting thread's own clock, not on the JVM's shared CompletableFuture timer, which a blocking callback elsewhere in the host can hold up. The signalling lives in the package-private ProcessTree.
• No unbounded join. Each output stream gets GRACE after the child exits. A drain still open then is abandoned and its stream is reported truncated. LocalProcessExecutionProvider's stdin feeder join uses the same constant. BoundedSink.drain holds the stream's monitor for the whole drain, so the JDK's processExited cannot close a pipe that a backgrounded descendant still writes to.
• CommandGrant.invoke(args, token) receives ctx.cancellation() from CommandGrantTool. A cancelled call returns Cancelled while invoking <name>.
• LocalProcessExecutionProvider no longer has its own kill callback or SIGKILL branch. InflightProcesses now tracks BoundedProcess and reaps through kill(), so close() and the shutdown hook use the same escalation. Before this, close re-read descendants after the parent died and left a re-parented grandchild that ignores SIGTERM running.
• JvmSandbox.create on failure closes the RPC channel before the socket and kills the child with SandboxLauncher.destroyTree. installPrelude now runs before the constructor, so a failed install never registers a shutdown hook. A package-private overload hands the accepted SandboxRpc to tests; Uday chose to keep it.
• CHANGELOG: Breaking rows for await and kill(), and one Fixed row.

Differences from the spec's wording

1. A cancelled await stops the child promptly with the bounded TERM-then-KILL escalation. It does not send SIGTERM and then wait out the timeout.
2. BoundedProcessTest.interruptWhileAwaitingPropagatesAndLeavesTheProcessToTheCaller asserted the old behaviour. Acceptance test 2 replaces it. Every other existing test keeps its assertions.
3. Uday's ruling during the pre-merge review: provider close() is fixed in this PR (kill() now means kill-and-reap).
4. Acceptance test 1's child writes 256 KiB before it exits. This makes sure the drain is already reading when the child exits; the spec's echo started alone left that to chance.

Size

+68 net main-code lines against df416089 (javadoc, comments, imports and blanks excluded), within the ~90-line budget. The pre-merge review removed the exit-signal thread and latch and InflightProcesses' duplicate escalation.

Verification

• mvn -B clean verify javadoc:jar at the head: BUILD SUCCESS, 7,882 tests run, 0 failures, 0 errors, 62 skipped (key-gated live tests). PMD, CPD, Spotless, JaCoCo and ArchUnit pass.
• JaCoCo: every changed line and branch is covered. Each claimed behaviour was hand-mutated, and a test fails for every mutant except the four noted below.
• Repetition: 23,640 repetitions of BoundedProcessTest, BoundedSinkTest, CommandGrantTest and LocalProcessExecutionProviderRobustnessTest, with 0 failures. Delay injection at seven race windows found no failure. The final commit (own-clock grace, synchronous SIGTERM on cancel) passed five further full runs of those classes.

Not pinned by a test, and why:

• Shutdown-hook ordering on a failed launch: only observable through reflection or GC.
• Channel-before-socket release order: the reader's log race is not deterministic without a new hook.
• destroyTree versus destroyForcibly: the launch has no grandchildren at that point.
• ProcessTree's interrupt handling: it changes timing only.
• That the grace does not depend on the JVM's shared timer: proving it needs a test that ties up that timer, which takes a TimeUnit argument. The TimedWaitInTest PMD rule forbids that, and suppressions are not allowed.

🤖 Generated with Claude Code