fix(scaffold): a cli adapter's in-flight children never outlive it (io.pilot.otto)

[TeoSlayer]

Stacked on #111, which covers the adapter exiting with its daemon and a caller hang-up cancelling its call. This PR covers the CLI child processes, the first-spawn download, and timeouts. Review #111 first. Once #111 merges, this PR's base becomes main.

Problem

These leaks were measured in the published io.pilot.otto 0.20.0 bundles on darwin/arm64, darwin/amd64 (Rosetta), linux/arm64 and linux/amd64 (docker --init). The same adapter template backs every cli/hybrid app: aegis, docker, duckdb, miren, mysql, otto, postgres, redis, smol, sqlite, tldr and upfile.

	Published 0.20.0 (measured)
In-flight child, adapter SIGKILLed	This is the supervisor's stop path in app-store ≤ v1.0.3: SIGKILL to the pid only. otto.exec ["mcp","serve-http","--port",P] survives and keeps listening on P 8 s later, with ppid=1, on all 4 platforms.
In-flight child, daemon dies	Linux: the adapter's Pdeathsig kills the adapter, but not its child. The child ends up with ppid=1 and P still listening (3/3 runs per arch). macOS has no Pdeathsig: the adapter itself stays up and keeps serving (the fix for that is in #111), and so does its child.
Stop during the first-spawn download	The otto download takes 3.5–27.6 s. signal.NotifyContext is only installed after staging, so a SIGTERM takes Go's default action (exit 143) and leaves $TMPDIR/pilot-asset-* behind in the daemon's shared TMPDIR. SIGKILL does the same.
Per-call timeout	Returned as a normal reply, {"exit":-1,"stdout":"Otto MCP HTTP server listening…"} after 60 s, rather than as an error.

Fix (template only)

Commit 1 carries the fixes prototyped in the apps sweep for miren and aegis, copied verbatim (tests included), so those branches can rebase onto this one with no conflict.

• client_cli: every CLI child stays in the adapter's process group. On Linux it also gets Pdeathsig=SIGKILL, and the forking thread stays locked until Wait returns (Pdeathsig fires when that thread exits). A cancelled call sends SIGTERM first; exec's WaitDelay escalates to SIGKILL after 5 s. A deadline or shutdown is returned as an IPC error.
• main: signal handling and fix(scaffold): generated adapters exit with their daemon and drop abandoned calls #111's parent watch are installed before staging. Shutdown waits up to 8 s for in-flight calls, and therefore for their children.
• stage: downloads go to $APP/.staged/tmp and are cancelled along with the adapter. Anything a SIGKILLed start leaves there is swept by the next start.

Commit 2 closes the one case that commit 1 leaves open on macOS: a SIGKILLed adapter. macOS has no parent-death signal, so after the adapter dies nothing else would stop the child.

• childguard.go (new). While a CLI child is running, the adapter keeps a guard: the same binary re-executed with --pilot-child-guard, in the adapter's process group, reading a pipe that only the adapter can write to (close-on-exec). The kernel closes that pipe however the adapter dies. On EOF, the guard waits until it has been reparented, which proves the adapter is really gone, and then SIGKILLs the process group, itself included. A process group id is not reused while any member is alive, and the guard is a member, so the signal cannot reach an unrelated group.
• The guard runs only when the adapter leads its own process group, which is how the supervisor spawns it. It retires 1 s after the last child is reaped. On a clean shutdown it is released and reaped, so the group is left empty.
• This covers every daemon version, and also the OOM killer, a crash, and an operator's kill -9, on both OSes. app-store http adapter: REST path params + PATCH/PUT/DELETE + broker pattern allow-list #39 (group SIGKILL on stop) is still worth having, but it only takes effect once a daemon release ships it.
• docs/CLI-ADAPTER.md now documents the child-lifetime and staging guarantees.

Tests

TestCLIInflightServerE2E (new) reproduces otto's case: a passthrough call runs a server. It has six subtests: supervisor death using the supervisor's real spawn attributes (Setpgid, plus Pdeathsig on Linux from a locked thread, via a helper process); SIGKILL of the adapter; a clean stop leaving an empty group; guard idle retirement; the adapter surviving its guard's death; and a group stop. The tests from commit 1 are TestCLIAdapterChildLifecycleE2E (timeout returns an error; SIGTERM and SIGKILL with a child in flight) and TestStageInterruptedLeavesNothingE2E.

	darwin-arm64	linux-arm64	linux-amd64
TestCLIInflightServerE2E on main	FAIL: adapter outlived its supervisor; child outlived it	FAIL: child outlived the dead supervisor and adapter	FAIL: same
same, guard disabled (negative control)	FAIL: server child … outlived the SIGKILLed adapter
this branch	PASS (-count=5)	PASS (-count=5)	PASS (previous revision, see below)
go test ./...	PASS	scaffold + publish PASS	PASS: CI build-test on this head (ubuntu-latest, -race)

Linux ran in golang:1.25.13-bookworm, with amd64 under emulation. The amd64 run is where the one bug found in review showed up. The guard originally read the adapter's pid with getppid() at startup. Under emulation it could start after the adapter had already died, read pid 1, and then never act (adapter's process group … not empty after it was SIGKILLed). The adapter now passes its pid in argv. After that change, darwin and linux-arm64 pass with -count=5, and CI (linux-amd64, -race) passes.

Verified on real otto bundles (rebuilt from this branch)

I built submissions/io.pilot.otto at version 0.20.1 with publish.BuildBundle, the same path as pilot-app verify-submission, and signed it with a TEST-ONLY key. Nothing was published. pilot-app verify and the sweep harness's verify (manifest, signature, binary sha256, Mach-O/ELF os/arch) pass on all 4 bundles. I then ran the real staged otto CLI, with otto.exec ["mcp","serve-http"] in flight, against both the rebuilt 0.20.1 bundles and the published 0.20.0 ones. All rows come from bundles built from this head. For the Linux lifecycle runs I used copies of the bundles with the otto CLI pre-staged from its sha-pinned asset: R2 downloads inside Docker were taking more than 90 s at the time. The cold-start rows used the real download.

Scenario	0.20.0 published	0.20.1 this branch
SIGKILL adapter pid (supervisor stop)	LEAK on all 4: child ppid=1, port listening at 8 s	CLEAN on all 4 (darwin: guard; Linux: Pdeathsig)
supervisor SIGKILLed (Linux: with Pdeathsig)	LEAK: darwin app + child alive at 10 s; Linux child alive, ppid=1	CLEAN on all 4: app gone in 1–286 ms, child gone, run dir empty
SIGTERM adapter	clean	CLEAN, exit 0 in 15–71 ms
group SIGTERM→SIGKILL (proposed supervisor stop)	—	CLEAN on all 4
per-call timeout (60 s)	{"exit":-1} reply	IPC error …/otto: context deadline exceeded (darwin-arm64, linux-arm64), child gone
SIGTERM during first-spawn download	exit 143, pilot-asset-* left in TMPDIR	exit 0, TMPDIR and $APP/.staged/tmp empty (darwin-arm64, linux-arm64)
SIGKILL during first-spawn download	partial left in TMPDIR	TMPDIR empty; partial only in $APP/.staged/tmp, swept by the next start, which staged OK on darwin-arm64 in 6.5 s (on linux-arm64 the old partial was swept; the slow download did not finish within the 120 s window)

Harness, lifecycle + stopkill + orphan phases:

• otto.help ×200: 200/200 on all 4.
• otto.status ×200, which execs otto on every call: 200/200 on darwin-arm64 and linux-arm64. Under emulation the 180 s budget allowed 85 calls on darwin-amd64 and 87 on linux-amd64, all ok.
• fd flat or down on every run. Descendants at idle: 0.
• SIGTERM: exit 0 in 1–55 ms, socket removed, empty process group.
• Orphan without Pdeathsig: SELF-EXIT after 202–340 ms on all 4. It was ORPHAN on 0.20.0. Linux with Pdeathsig: PASS in 1–8 ms.

Not in this PR

• Supervisor:
  • A SIGKILL stop still leaves app.sock on disk. The supervisor deletes it before the next spawn.
  • app-store http adapter: REST path params + PATCH/PUT/DELETE + broker pattern allow-list #39, and a SIGTERM-first stop, belong in app-store.
• Daemonized servers (otto start detaches its relay with setsid, as do redis-server --daemonize and pg_ctl start) are outside the process group, so neither the group signal nor Pdeathsig reaches them. For otto this is latent: the staged Bun binary can't start its relay at all today (Unable to resolve relay runtime entrypoint, an upstream telepat-io/otto issue). The sweep's postgres branch prototypes a cli.teardown hook for this case.
• Grandchildren a CLI starts in its own process group (the sqlite .shell case): not covered here.
• Shipping otto 0.20.1:
  • needs the otto publisher key (ed25519:mTyrd5ZG/tl76CLpdUEaaGvCjrnE6QLHPVm7XrduH/w=), an R2 upload of the four adapter bundles, and a re-signed catalogue.
  • The native otto assets stay at their 0.20.0 URLs, so they need no upload.
  • The version bump is deliberately not in this PR: merging a submission change triggers publish-on-merge, and the bundles have to be on R2 first.

🤖 Generated with Claude Code

[TeoSlayer]

Aegis measurement against this head (808243f). I built io.pilot.aegis 0.1.5 from it: natives from pilot-protocol/aegis#4, a TEST-ONLY key, and the natives staged over HTTP from a local mirror. I ran the lifecycle harness on darwin/arm64, darwin/amd64 (Rosetta), linux/arm64 and linux/amd64 (docker --init).

Clean on all four:

• The judge server after a flagged scan: 0 left after SIGTERM and after SIGKILL of the app.
• install-models past the 60 s timeout: an IPC error at about 60.0 s, 0 left.
• The app SIGTERMed with install-models in flight: 0 left, 3/3.
• help, version, status and exec scan-cmd, 200 calls each: 200/200, fd flat.
• Orphan without Pdeathsig: SELF-EXIT in 305–319 ms. Linux with Pdeathsig: PASS.

Two differences from #116 plus the SIGTERM line (#117):

• Offline first spawn exits 1 before the socket appears, on all four. fix(scaffold): a cli app is ready before its binary is, and a failed download is retried #116 listens before staging, so help works offline there (20/20).
• Per-call latency on macOS. darwin/arm64 aegis.status ×200: p50 41.8 ms and p95 296.9 ms here, against 6.2 / 8.5 ms with fix(scaffold): a cli app is ready before its binary is, and a failed download is retried #116 plus the SIGTERM line. On darwin/amd64 the p50 is 42.9 ms. That is one childguard process per call. The Linux numbers are about the same in both builds.

🤖 Generated with Claude Code