[mengmengmengqiang]

Stacked on Ephemeral-AI-Lab#499 (fork base feat/ns-exec-helper, head 386f1b22). This PR is the skeleton only; it is not wired to the Engine and does not change workspace.exec behavior.

Scope

A hidden ns-exec-supervisor mode that owns one command across the Ephemeral-AI-Lab#499 mount-namespace seam, plus one hidden ns-exec-child mode on the same binary.

• Supervisor. Receives the daemon's mount-namespace descriptor over the existing SCM_RIGHTS socket, spawns the child, and closes its own copy. It never calls setns and never chdirs into the Workspace, so it cannot become a FUSE mount holder.
• Child. Reopens the inherited descriptor through /proc/self/fd (with the existing mnt: check), setns(CLONE_NEWNS), chdir(workspace), drops supplementary groups/gid/uid exactly as feat(sandbox): run workspace.exec in the daemon's mount namespace (ns-exec helper) Ephemeral-AI-Lab/layerfs#499's ns-exec does, then setsid() and PR_SET_PDEATHSIG(SIGKILL), re-checks getppid, and execs the command.
• Control socket. 0600 Unix socket, four-byte big-endian length frames with a fixed small body: Started {pid, pgid}, Exited {code, signal, group_alive}, Status/StatusReply, Signal {signo}, and a thin Stop {grace_ms} SIGTERM wrapper. A late caller receives the current Started/Exited snapshot under the same lock that registers it. Signal/Stop use kill(-pgid, signo) only for the child's own group; the supervisor's own group and arbitrary pids are refused. Peer admission is the supervisor's effective uid; further authorization is deferred.
• wait4. Reaps the direct child exactly once, reports code/signal, exits 128 + signal when signalled, and reports group_alive: true (via kill(-pgid, 0)) when grandchildren remain. Grandchildren are not killed in this slice.

Architecture modules

The design note is organized in layers (module map, interfaces, startup/signal/exit sequences, failure modes and invariants, implemented vs deferred, test matrix): EXEC-SUPERVISOR-SKELETON.md.

• Supervisor process. Owns one session: receives the mount-namespace descriptor, binds the control socket, spawns the child, observes its session, serves callers, reaps once and exits with the child's status. Never setns/chdirs.
• Child launcher. The only process that joins the namespace: reopens/validates the descriptor, setns, chdir, drops groups/gid/uid, setsid, PDEATHSIG, checks its parent and execs the command.
• Control link and protocol. 0600 socket, four-byte length frames, peer-uid admission, Started/Exited/Status/Signal/Stop, and a snapshot for late callers under the same lock as registration.
• Process table / session state. One in-memory slot (pid, pgid, started, exit, clients) behind one mutex; all state dies with the supervisor.
• Launcher / orchestrator (future, ownership open). Starts one supervisor per command, hands it the descriptor and maps the session to the Engine. Not implemented; where it lives conflicts with the current "daemon has no command supervisor" rule.
• Session registry / presence (future). Session ids, reconnect and caller-presence; required because the control socket lives only as long as the supervisor.

The note also records gaps that the skeleton does not close: starttime is not captured (identity is only (pid, pgid)), Stop is implemented but untested, a session-poll timeout yields Exited without Started, and group_alive is an observable-group probe rather than ownership.

Presence + registry decisions

The six decisions the design note left open are now locked — launcher ownership, lease granularity, daemon-restart semantics, lease authentication, background/disconnect policy and cancellation states. Full text and rationale: Presence + registry decisions (locked).

• Launcher. Engine exec spawns the supervisor and owns stdio and the exit code; the daemon only receives the registration and owns registry, presence and policy. The daemon does not become a command I/O broker and does not spawn the supervisor in this phase.
• Lease granularity. One dedicated lease connection per client process per Sandbox, multiplexing all of its sessions — not one per exec. Session ids/tokens identify sessions; the connection budget is one lease plus pooled RPC slots.
• Daemon restart. P1 does not adopt old sessions. A restart loses the registry and lease; supervisors act on control EOF by foreground (cancel/cleanup) vs background (keep) policy, and only host records remain. This is lost-session semantics, not recovery.
• Lease auth. SO_PEERCRED plus a daemon-issued per-session capability/token delivered over the authenticated control channel; never in argv, because same-uid processes can read /proc/<pid>/cmdline. Hostile same-Sandbox multi-tenancy additionally requires user/namespace isolation.
• Background. Not one boolean: mode: foreground|background and a separate onDisconnect: cancel|keep|reconnectWindow. This phase ships background + cancel; reconnectWindow comes later. detachOnDisconnect is foreground + keep.
• Cancelling. No reversible 500 ms Cancelling window. The reconnect window is the Orphaned phase (5 s default); once Cancelling starts it is one-way, and the grace period is only TERM → KILL cleanup time.

Phase impact: P1 registry + starttime; P2 presence + reaper; P3 reconnect/background; P4 Engine wiring.

Deliberately deferred

• client-presence detection and reconnect;
• the daemon session registry and session ids;
• force-kill orchestration, kill policy/escalation;
• close(force) integration;
• reaping/killing grandchildren;
• authorization beyond the socket mode and peer uid;
• retaining session state after the supervisor exits (the control socket lives only as long as the supervisor).

Tests

engine/crates/layerfs-daemon/tests/exec_supervisor.rs (Linux-gated; runs in the mount lane with CAP_SYS_ADMIN, like ns_exec.rs). It builds a private mount namespace with unshare -m, serves its /proc/<pid>/ns/mnt descriptor over SCM_RIGHTS, and drives the real binary over the control socket:

test	result
join the served namespace, enter the Workspace directory, read a namespace-local marker, Started has pgid == pid and pid != supervisor, exit 7	pass
supervisor's own mount namespace and cwd stay outside the Workspace	pass
command runs as 65534:65534 when told to drop there	pass
sleep 30 + Signal(SIGTERM) → Exited {signal: 15}, supervisor exit 143	pass
Status reports the running child; Signal(SIGKILL) → signal 9, exit 137	pass
sh -c 'sleep 5 & sleep 1' → group_alive: true instead of a clean exit	pass

Run in a privileged rust:1.85.1-bookworm container against a20f5ae81:

• cargo fmt --all -- --check — pass
• cargo check -p layerfs-daemon --all-targets — pass
• cargo clippy -p layerfs-daemon --all-targets -- -D warnings — pass
• cargo test -p layerfs-daemon --test exec_supervisor --no-run then exec_supervisor --test-threads=1 — 6 passed, 0 failed; repeated 10 consecutive runs, all green.

Docs

core/docs/issues/538/EXEC-SUPERVISOR-SKELETON.md is the modular architecture note: module map, interfaces (SCM_RIGHTS handoff, control frames, process identity, exit/group_alive semantics), startup/signal/exit sequences, failure modes and invariants, implemented-vs-deferred table and test matrix.

Dependency

Depends on Ephemeral-AI-Lab#499 (feat/ns-exec-helper, 386f1b22). Merging this before Ephemeral-AI-Lab#499 would not compile because it builds on Ephemeral-AI-Lab#499's ns_fd/cli seam. No changes to Ephemeral-AI-Lab#499 or upstream.