fix(scaffold): a cli app is ready before its binary is, and a failed download is retried

[TeoSlayer]

Stacked on #111 (fix/sixtyfour-lifecycle): this PR uses its watchParent, serveConn and socket-ownership code and only adds to it. Review #111 first. Once #111 merges, this PR retargets to main.

Problem

The harness sweep of the published io.pilot.miren 0.1.0 bundles (all 4 platforms) found these problems. Each one comes from the cli templates, not from miren:

	Published 0.1.0 (measured)
Not ready on first install	The adapter downloads its CLI (40–60 MB for miren) before it creates its socket. The supervisor's waitReady waits 3 s (app-store v1.0.2, which daemon v1.13.9 pins, and v1.0.3) and never retries. With the real supervisor's spawn + Call, the first spawn answers every call with appstore: app not ready: io.pilot.miren until the next respawn. This happened on darwin-arm64 and linux-arm64 with both v1.0.2 and v1.0.3. The socket appeared after 11 s (darwin-arm64), 15 s (darwin-amd64), 20 s (linux-arm64) and 22 s (linux-amd64).
Offline first start	StageAssets fails, then log.Fatalf, exit 1 before the socket exists, so even miren.help is unavailable.
LEAK: in-flight CLI child outlives the adapter (Linux)	The supervisor gives the adapter Pdeathsig, but a child does not inherit it. miren login running over miren.exec survived a SIGKILL of the adapter and a daemon death with Pdeathsig. It was reparented to pid 1 and ran for 4.1 s (chatty) to 29 s (silent).
LEAK: partial download in the shared $TMPDIR	A first-start download that is interrupted leaves pilot-asset-* behind (58–84 KB measured, up to the whole tarball). SIGTERM during staging is not handled, because signal.NotifyContext is installed after staging: exit 143, and the file is left behind.
Timeout reported as success	A call cut off by its 60 s deadline replies {"exit":-1,…} as a result instead of an error.

Fix (templates + 2 docs)

• childproc_{linux,other}.go.tmpl (new, rendered for cli and hybrid): on Linux, every process the adapter starts (CLI calls, tar, install steps) gets Pdeathsig=SIGKILL. The forking thread stays locked until Wait returns. On other systems nothing is set. Children always stay in the adapter's process group, so the supervisor's group stop (http adapter: REST path params + PATCH/PUT/DELETE + broker pattern allow-list #39 in app-store) and reapStale's kill(-pgid) still reach them.
• stage.go.tmpl: a Stager runs StageAssetsContext in the background. The runner resolves its command through it (Runner.SetCommandResolver), so a call waits for the binary within its own deadline. If an attempt fails, each call reports the failure, and a later call retries it (backoff from 2 s, doubling up to 5 min). The adapter no longer exits. Downloads go to $APP/.staged/tmp. That directory is removed when an attempt ends or is cancelled, and swept at the next start. Download, tar and install steps are bound to the ctx. The idle registry connection is closed after staging.
• main.go.tmpl:
  • Signal handling and parent-death handling from fix(scaffold): generated adapters exit with their daemon and drop abandoned calls #111 are now installed before any startup work.
  • The socket is bound before staging.
  • serve returns only after every running call has returned. It closes connections and waits up to 8 s.
  • main waits for an interrupted download to clean up before it exits.
• client_cli.go.tmpl: a cancelled call, or a child ended by a signal, is now an IPC error (backend: …: context deadline exceeded) instead of {"exit":-1}.
• docs/CLI-ADAPTER.md and docs/R2-ARTIFACT-REGISTRY.md describe the new behaviour.

Tests

TestCLIAdapterChildLifecycleE2E covers timeout, SIGTERM, SIGKILL on Linux, and parent death with a call in flight. TestStageLifecycleE2E covers four cases: ready and help while the download is stalled; SIGTERM mid-download; the leftover from a SIGKILL mid-download is swept; a failed download keeps serving and a later call retries.

• On the base (80d19b2), darwin/arm64 and linux/arm64 both fail the timeout subtest (out={"exit":-1,…} err=<nil>) and all 4 staging subtests (socket … did not accept connections within 2.5s, download never started under $APP/.staged/tmp). linux/arm64 also fails the SIGKILL subtest (in-flight child pid … outlived the SIGKILLed adapter).
• On origin/main (fcd0b12), parent death also fails (adapter pid … kept running after its parent died). fix(scaffold): generated adapters exit with their daemon and drop abandoned calls #111 fixes that one.
• SIGTERM passes on every base. The published adapter already killed the child on SIGTERM. The drain here makes that deterministic.
• With this PR, the new tests plus fix(scaffold): generated adapters exit with their daemon and drop abandoned calls #111's TestGeneratedAdapterLifecycleE2E pass 5 times in a row on darwin/arm64 and on linux/arm64 (golang:1.25.13-bookworm, --init). The two new tests also passed once on emulated linux/amd64, before this branch was rebased onto fix(scaffold): generated adapters exit with their daemon and drop abandoned calls #111.
• go test ./... passes on darwin/arm64, and go vet ./... plus go test ./internal/... pass on linux/arm64.

Verified on real miren bundles built from this branch

publish.BuildBundle built submissions/io.pilot.miren with version 0.1.1, for all 4 DefaultPlatforms, signed with a TEST-ONLY key. Nothing was uploaded or published. pilot-app verify passes for all 4, and the harness verify passes too: sha, signature, pin, and Mach-O/ELF arch. Apart from version, binary sha and signature, the manifest and install.json are identical to the published 0.1.0.

Real supervisor, first spawn (sup.spawn + sup.Call, nothing staged):

supervisor	platform	0.1.0	this PR
app-store v1.0.3	darwin-arm64	never ready, app not ready	ready after 675 ms; miren.help ok; miren.exec version ok after 9.3 s of staging
app-store v1.0.3	linux-arm64	never ready	ready after 143 ms; exec ok after 25.6 s
app-store v1.0.2	darwin-arm64 / linux-arm64	—	ready after 653 ms / 222 ms; exec ok

Harness (help ×200 + stop/orphan phases; miren.exec version ×200):

• Ready in 558 ms on darwin-arm64, 2.2 s on darwin-amd64 (Rosetta first run, 1.5–1.8 s after that), 25 ms on linux-arm64 and 186 ms on linux-amd64. In the audit's harness runs of 0.1.0, the socket appeared after 6.8 s, 13.5 s, 10.8 s and 25.4 s.
• help: 200/200 on all 4.
• exec: 200/200 on darwin-arm64, darwin-amd64 and linux-arm64. linux-amd64 (emulated, host load about 78) did 141/141 before the harness's 3-minute budget ran out.
• The fd count stayed flat. On darwin-arm64, help ×5000 went fd 11→9 once staging finished, and RSS levelled off at about 19.8 MB.
• SIGTERM: exit code 0 in 1–40 ms, socket removed, process group empty.
• Orphan without Pdeathsig: the app exits by itself 205–325 ms after its parent dies (fix(scaffold): generated adapters exit with their daemon and drop abandoned calls #111). With Pdeathsig on Linux: 0–10 ms.
• Offline first spawn (sandbox-exec deny network / --network none): help 20/20 on all 4. miren.exec returns install assets: stage: fetch … as an error, and the app keeps running.

In-flight miren login (fake device-flow endpoint), then the app is stopped. The table shows whether the miren child is still alive afterwards:

stop	darwin-arm64 0.1.0 → PR	darwin-amd64 PR	linux-arm64 0.1.0 → PR	linux-amd64 PR
SIGTERM	gone → gone	gone	gone → gone	gone
SIGKILL of the pid (supervisor ≤ v1.0.3 stop)	alive 4.1 s → alive 4.2 s	alive 4.0 s	alive 4.1 s → gone	gone
SIGKILL of the group (app-store #39)	gone → gone	gone	— → gone	gone
daemon death, Linux Pdeathsig	—	—	alive 4.2 s → gone	gone
daemon death, no Pdeathsig	orphan, child alive >42 s → gone, app exits in 220 ms	gone (132 ms)	orphan >42 s → gone (214 ms)	gone (70 ms)

Real supervisor stop with that call in flight:

• linux-arm64: child gone with app-store v1.0.2 and v1.0.3, no supervisor change needed.
• darwin-arm64: still alive ppid=1 with v1.0.2 and v1.0.3, and gone with http adapter: REST path params + PATCH/PUT/DELETE + broker pattern allow-list #39 (fix/stop-app-process-group).

Not in this PR

• macOS + a pid-only SIGKILL stop (every released supervisor): a SIGKILLed adapter cannot clean up, and macOS has no parent-death signal. The child stays in the app's process group, so app-store http adapter: REST path params + PATCH/PUT/DELETE + broker pattern allow-list #39's group kill ends it (verified above).
• Grandchildren: a timed-out call kills its direct child only. Anything that child started stays in the app's process group, until the supervisor's group stop. On Linux, a grandchild gets no Pdeathsig. No curated miren method does this. miren server through miren.exec might, but that was not verified (it failed in an unprivileged container).
• Shipping: miren 0.1.1 still has to be built with the Miren publisher key and uploaded to R2, and then the submission version bumped. None of that is done here.

🤖 Generated with Claude Code

[TeoSlayer]

Aegis measurement against this head (0467324). 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. Then I SIGTERMed the app while aegis.exec install-models (a stub curl) was running, 3 rounds per platform.

• darwin/arm64 and darwin/amd64: the curl is left with ppid=1 in 3/3 rounds, and the adapter takes about 5 s to exit. On cancel, exec SIGKILLs aegis, so aegis never gets to stop its own child, and macOS has no Pdeathsig to fall back on.
• This head plus one line (cmd.Cancel = func() error { return cmd.Process.Signal(syscall.SIGTERM) }, fix(scaffold): a timed-out cli call gets SIGTERM before SIGKILL #117): 0 left in 3/3 on all four platforms, and the adapter exits in about 50 ms.
• That line is already in fix(scaffold): a cli adapter's in-flight children never outlive it (io.pilot.otto) #114. fix(scaffold): a timed-out cli call gets SIGTERM before SIGKILL #117 carries it alone, with a test, if this PR lands without fix(scaffold): a cli adapter's in-flight children never outlive it (io.pilot.otto) #114. It cherry-picks onto this head cleanly except for one docs sentence.
• Everything else I checked on this head was clean on all four platforms: offline first spawn (help 20/20), the judge after a flagged scan, the 60 s timeout, which now returns an IPC error, and orphan SELF-EXIT in 207–319 ms.

🤖 Generated with Claude Code