feat(shutdown): reap wedged ssh transport children on exit — exact-PID registry (issue #6)

[bcourbage]

Reaps a wedged sync's orphaned ssh transport child on app exit, via a pure-C exact-child-PID registry. Follow-up to #7; passed cumulative adversarial review and the full live-validation matrix.

Defect

The engine spawns one ssh child per remote connection (remote.ml). Normal OCaml termination reaps it via at_exit end_ssh, but the AppKit host can terminate without running OCaml at_exit (applicationWillTerminate → unison_bridge_shutdown is a bounded C helper), and a sync wedged on a frozen remote is blocked on the transport socket, so closing fds never makes it exit. The child survived as an orphan (observed alive to t+230s; died only when the remote was killed). Characterized during #7 / TC10.

Design — exact-child-PID registry (needs no OCaml/Lwt progress at shutdown)

A C-owned, mutex-protected registry with three operations:

• track(pid) — OCaml records the exact pid right after spawn. Deduplicated under the mutex, so a repeat track is a no-op and one retire fully removes it.
• retire(pid) — teardown calls this before it waitpid/close_sessions the child. Under the mutex, and only while the pid is still registered, it SIGKILLs the exact pid and removes it — atomically. SIGKILL is issued before removal: the child is thereafter irrevocably terminating (SIGKILL can't be caught/blocked) though it may not have exited the instant kill() returns; its pid stays reserved until the following waitpid. Idempotent; never signals a pid it no longer tracks (so it can't hit a reused pid).
• reap() — the pure-C shutdown pass (called first in unison_bridge_shutdown): under the mutex it sets closing, SIGKILLs every still-registered pid, then clears the set.

Every kill(2) is issued while holding the mutex, before removal. Because OCaml can only waitpid a child after retire removed it under the same mutex, no concurrent reap can free a pid mid-signal → no PID-reuse race and no unregistered-but-still-alive window. No process enumeration — exact registered pids only. A spawn racing closing, or a full registry, is SIGKILLed at once so it can't escape. Full adversarial proof in docs/ssh-reaper-design.md.

Both spawn paths are covered by patches/0004: the synchronous buildShellConnection (CLI) and the async openConnectionStart/End/Cancel path the macOS GUI actually uses. Hooks are overridable (int -> unit) ref no-ops in remote.ml; the macOS bridge (uimacbridge.ml) installs the real ones. CLI/GTK builds link with zero bridge symbols (verified) and keep their prior at_exit behavior.

Toolchain / blob

The blob's runtime ABI is version-locked, so OCaml 5.5.0 is pinned: make check-ocaml-version fail-fast on build/vendor-blob; CI + release link via ocaml/setup-ocaml 5.5.0 (not bare brew install ocaml). vendor-blob builds only unison-blob.o (upstream's own app link can't resolve our C symbols).

Blob rebuilt at base 91421d0 + patches 0002/0003/0004, OCaml 5.5.0: sha256 a57f5c4ec18d96277ac2cde58a7d8f703b012daffdefa42877638671eb062b03, 5462536 bytes.

Validation

• 479 tests, 0 failures, incl. test_concurrentRetireAndReap_sameChild_isSafe — a genuinely concurrent retire vs reap on the same tracked child, synchronized start, 50 iterations, outcome-based assertions (child SIGKILLed+reaped, registry empty, unrelated survives, no hang/leak) — plus dedup, idempotent-retire, late-registration-after-shutdown, exact-kill, unrelated-survives, no-children.
• Debug + Release build; Release carries no test-hook strings; the test-only reset is UNISON_DEBUG_HOOKS-gated and absent from Release; git diff --check clean.
• Live (key auth, Demeter): normal-quit → no orphan (0 ssh, 0 remote, 0 errors); frozen-remote-server wedge → app quit → exact orphan reaped.
• Live (password auth, 192.168.2.241): open/scan/sync/leave/reopen; adaptive hold after sync with same-session Rescan and no re-prompt, and re-prompt only after an actual close; credential-prompt cancellation → pending ssh reaped, no stale callback, clean replacement profile; interactive-auth connection wedged during sync (stopped local transport child) → app quit → exact ssh child reaped; an unrelated ssh session survived untouched (exact-PID scoping). Password entered by the maintainer directly; never inspected/logged.

Limitations

• Teardown-time reaping only — this reaps transport children when the connection tears down or the app exits; it is not in-process core scan/connect cancellation (a separate, out-of-scope item).
• Blob not bit-reproducible — inputs (source/patches/toolchain/command) are pinned, but the .o is not byte-identical across clean rebuilds (OCaml/ld nondeterminism, observed); documented in vendor/README.md.
• Fixed 64-child registry (MAX_TRANSPORT_CHILDREN) — far beyond any real profile set; a pid that would overflow it is SIGKILLed rather than left untracked.
• The password-auth wedge was induced by stopping the local transport child (the remote is password-only, so its server can't be SIGSTOPed without the password); the frozen-remote-server variant is covered over key auth.

Refs #6 (not closed by this PR).

🤖 Generated with Claude Code