refactor(supervisor): make managed child ownership structural

[elezar]

Description

Make Linux managed-child ownership structural so callers cannot accidentally separate spawning, PID registration, waiting, unregistering, and lost-child diagnostics.

Context

The child reaper race fixed by PR #3142 required every Linux child path to use the correct registration protocol. The current registry helper closes the immediate spawn-to-registration window, but ownership remains a convention across canonical and SSH process paths. The diagnostics and wait-handling follow-ups explored during that review belong with the ownership cleanup.

Definition of Done

• Introduce a managed-child abstraction that owns Linux child registration and cleanup.
• Route canonical and SSH child paths through the abstraction.
• Centralize explicit-wait handling, unregistering, and ECHILD diagnostics.
• Add deterministic tests for ownership and reaper interleavings.
• Preserve non-Linux behavior without introducing Linux-only reaper machinery there.

Related Work

• PR fix(supervisor): serialize child registration with reaping #3142

[elezar]

🏗️ build-plan

Implementation Plan

Issue type: refactor
Complexity: Medium
Confidence: High — the lifecycle boundary is clear; SSH stdio extraction needs careful API shaping.

Summary

Replace the managed-child convention with a generic, cross-platform ManagedChild<C> owner. It will make child lifecycle ownership structural: callers use one wrapper for Tokio and std child variants on every platform. On Linux, it atomically registers the PID and owns orphan-reaper coordination; on other platforms, registry work is a no-op.

Scope

• crates/openshell-supervisor-process/src/managed_children.rs: introduce the cross-platform wrapper and keep Linux registry/reaper mechanics internal.
• crates/openshell-supervisor-process/src/process.rs: migrate the canonical Tokio child path to the wrapper on every platform.
• crates/openshell-supervisor-process/src/ssh.rs: migrate PTY and piped SSH child paths to the wrapper on every platform, with narrow stdio extraction APIs.

Implementation Steps

1. Add cross-platform ManagedChild<C> with private raw-child ownership, atomic Linux registration, no-op non-Linux bookkeeping, and drop cleanup.
2. Provide specialized Tokio/std methods for spawn, waiting, try_wait, and narrow stdio extraction.
3. Migrate canonical process waiting and try_wait to the Tokio wrapper without platform-specific child types at call sites.
4. Migrate SSH waiters to the std wrapper while preserving output ordering and stdio setup.
5. Centralize lost-child (ECHILD) diagnostics and PID unregistration in the wrapper.
6. Add lifecycle tests and retain the PR fix(supervisor): serialize child registration with reaping #3142 race coverage.

Test Plan

• Unit tests: cross-platform Tokio/std lifecycle behavior; Linux registration before return, successful and failed wait cleanup, and try_wait(None) retaining registration.
• Integration tests: N/A — ownership remains internal to the process supervisor.
• E2E tests: retain the Docker detached-fast-exit regression test from PR fix(supervisor): serialize child registration with reaping #3142.

Risks & Open Questions

• Do not expose unrestricted raw-child access or into_inner, which would let callers bypass lifecycle cleanup.
• SSH must extract stdio before the wrapper moves into its waiter thread.
• Keep Linux-only reaper behavior internal rather than leaking cfg-specific child types into callers.
• This branch depends on PR fix(supervisor): serialize child registration with reaping #3142; rebase it onto main once that prerequisite lands.

Documentation Impact

None expected — no user-facing behavior or configuration changes.

---

Revision 2 — cross-platform ownership model

[elezar]

Implementation is available in stacked PR #3156 (base: #3142).

It applies the cross-platform ManagedChild<C> ownership model from the plan: Linux reaper registration stays internal, while canonical-process and SSH callers use the same managed Tokio/std child lifecycle API on every platform. The PR includes cross-platform std/Tokio lifecycle tests and retains Linux-only reaper-race coverage.