refactor(mxc): adopt RFC 0012 supervisor/sandbox runtime

[drew]

Summary

Supersedes #3358 with the final RFC 0012 MXC architecture on current main after #2942. The gateway/MXC driver now provisions a host openshell-supervisor --role=isolation-backend, which controls openshell-sandbox inside a ProcessContainer over the authenticated, generation-bound Sandbox Protocol. The sandbox launches and controls the workload; no custom relay or forwarding bridge remains.

Related Issue

Part of #1737.

Supersedes #3358 and incorporates the sandbox-authentication and runtime-boundary work merged in #2942.

Changes

• Provision a per-generation host supervisor and in-MXC Windows sandbox runtime as one lifecycle unit.
• Reuse the common TLS/JWT-authenticated Sandbox Protocol for admission, workload/exec lifecycle, retained output, signals, provider refresh, and loopback forwarding.
• Route governed egress through the supervisor-owned policy engine, middleware, provider resolution, and authenticated explicit proxy.
• Preserve MXC filesystem, UI, ProcessContainer, and default-deny network enforcement while requiring measured AppContainer evidence at admission.
• Protect supervisor and boundary bootstrap state with restricted Windows DACLs; consume and delete boundary config and TLS private-key files before workload launch.
• Remove the standalone supervisor-relay crate, driver JSON control channel, forwarding bypass, provider snapshot side channel, and relay-only examples/tests.
• Update architecture, RFC 0013, gateway configuration, Windows build guidance, and contributor inventories for the shared runtime.

Testing

• mise run pre-commit
• mise run test
• mise run ci
• Targeted Linux checks and backend/server tests
• Windows x64 MSVC cross-check including test targets
• Windows ARM64 MSVC production-target cross-check
• Public/contributor skill inventory consistency check
• Physical Windows MXC create/run/forward/provider/stop/delete qualification

The remaining unchecked gate requires a Windows host with MXC. Linux compilation cannot validate ProcessContainer reachability, DACL changes made by MXC, traffic fencing, or process-tree teardown under the real runtime.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture and user-facing configuration docs updated
• Obsolete component and skill inventories removed

Known constraints

• The converted path supports process_container; isolation_session is rejected until separately implemented and qualified.
• Egress is attributed to the admitted main workload binary. Windows per-child socket-owner identity is not yet available, so descendants cannot receive distinct binary-specific network rights.
• Authenticated loopback TLS is the transport, but host loopback is not itself a security boundary; the gateway host remains trusted.
• Windows ConPTY resize is not implemented and is reported as unsupported.

Convergence plan

Show the full implementation and qualification plan

PR 3370: converge MXC forwarding on the shared runtime

Objective and recommendation

Preserve MXC workload launch, UI/filesystem enforcement, governed egress,
provider mediation, and dynamic forwarding while reducing the custom relay
protocol introduced by PR #3370. The destination is an external
openshell-supervisor paired with an MXC implementation of the RFC 0012
runtime boundary through a Windows openshell-sandbox platform implementation.
Go directly to this architecture. Do not build, shrink, or ship an interim
relay/forwarding bridge. Use the existing relay only as a behavior reference and
source of regression scenarios, then remove it during the integrated cutover.

The fastest route is one narrow end-to-end implementation for Windows x64
process_container, the current default backend. Establish admission, identity,
and egress enforcement early, reuse the existing protocol and supervisor
services, and expand platform coverage only after that path works. Porting the
old relay under a different executable name does not satisfy this plan.

Implementation was explicitly authorized on PR #3370 and is tracked by #1737.
The remaining plan sections preserve the design rationale, qualification gates,
and follow-up constraints for review.

Implementation status on PR #3370

The branch now implements the selected final topology directly:

• The MXC driver provisions a per-generation host
  openshell-supervisor --role=isolation-backend and launches
  openshell-sandbox --bootstrap as the ProcessContainer entrypoint.
• The pair uses the common authenticated Sandbox Protocol over generation-scoped
  TLS/JWT credentials. The sandbox consumes and deletes its bootstrap and TLS
  key files before accepting the supervisor.
• The Windows sandbox runtime owns canonical workload/exec lifecycle, retained
  output, signals, shutdown, provider-environment refresh, and sandbox-local
  loopback connections used by standard gateway forwarding.
• The host supervisor owns the gateway session, policy engine, network proxy,
  provider resolution, credential injection, and middleware. MXC permits only
  loopback egress and the proxy requires a fresh per-generation authorization
  value.
• The driver monitors both runtime processes as one lifecycle unit and tears down
  the counterpart when either exits. Host bearer material is stored under an
  owner-only Windows DACL.
• The bespoke supervisor-relay crate, driver JSON control channel, forwarding
  bypass, provider snapshot side channel, and relay-only examples are removed.
• The sandbox now measures TokenIsAppContainer before confirming the boundary;
  it no longer claims ProcessContainer enforcement solely from staged config.
• Linux targeted checks, Windows x64 test-target and ARM64 production-target
  cross-compilation, pre-commit, the full repository test suite, and aggregate
  CI pass. Real-MXC behavioral qualification remains the completion gate that
  cannot run from the Linux integration worktree.

The vertical slice intentionally chose authenticated loopback TLS rather than a
new named-pipe protocol because it reuses the existing Sandbox Protocol and MXC
can fence the workload to loopback. This does not make host loopback a security
boundary. The gateway host remains trusted, and per-generation authentication
prevents unauthenticated local traffic from entering the sandbox policy context.

One known limitation remains explicit: the host proxy attributes connections to
the admitted main workload binary because Windows socket-owner identity is not
yet available on this path. Descendants therefore cannot receive distinct
binary-specific network rights. Policies that depend on that distinction must
not be claimed as fully enforced until authoritative Windows attribution is
implemented and qualified.

Evidence and constraints

• The current driver embeds openshell-supervisor-network::host for egress.
  Moving that proxy into a process does not replace incoming forwarding.
• openshell-supervisor --role=network-proxy deliberately excludes gateway
  attachment, workload management, backend attachment, and provider resolution.
  It is not a replacement for the relay or a complete sandbox supervisor.
• The current relay launches the workload, reports a configured port ready,
  handles shutdown, and connects forwarding streams to local target ports.
• The standard isolation contract already exposes process and loopback
  connection primitives. Reuse those semantics instead of growing a second
  public runtime protocol.
• Windows support for the complete supervisor and sandbox runtime has not been
  established by the existing gateway/relay MSVC build lane. The sandbox has
  Linux-specific startup and enforcement, and the supervisor has Unix-oriented
  dependencies and bootstrap assumptions. This is platform work, not a flag change.
• Host-to-workload loopback reachability is not proven impossible. The earlier
  discussion overstated that limitation. Measure it separately for
  process_container and isolation_session; shared addressing alone does not
  establish trustworthy target ownership.
• Today's egress path permits host loopback broadly and uses a configured static
  binary identity. Neither is evidence of authoritative per-connection identity
  or isolation from unrelated host services.

Sources: crates/openshell-driver-mxc/{README.md,src/driver.rs,src/relay.rs},
crates/openshell-supervisor/{src/main.rs,src/lib.rs,Cargo.toml},
crates/openshell-sandbox/src/main.rs,
crates/openshell-isolation-interface/src/contract.rs, and
architecture/plans/pr-3358-rebase-after-2942.md.

Phase 1: settle only the prerequisites on the critical path

Run small real-MXC probes before changing production architecture:

1. Start a workload listener on sandbox loopback. Test host-to-workload,
   workload-to-host, and cross-sandbox connectivity with two live sandboxes.
   Start with x64 process_container and record the exact MXC/Windows versions
   and policy settings. Verify service ownership, not merely a successful connect.
2. Prove the driver can launch openshell-sandbox as the MXC entrypoint, that
   the runtime can launch its workload child with the required restrictions,
   and that the driver can terminate the entire tree on failure. No independent
   helper launch or multiple-entrypoint design is needed.
3. Establish a secret delivery path that does not use argv, readable shared
   files, or logs. Test inherited handles first; consider a named pipe only with
   explicit access control, authenticated generation binding, and protection
   against endpoint impersonation and handle inheritance into workloads.
4. Audit the Windows build surface for supervisor, sandbox backend, isolation
   interface, and sandbox runtime. Inventory Unix/Linux assumptions and separate
   portable protocol code from platform enforcement and process operations.
5. Map RFC 0012 requirements to available Windows evidence: process identity,
   executable identity, containment, egress fence, lifecycle, and transport.
   List unsupported requirements explicitly and verify contract rejection rules.

Deliverable: one selected transport/bootstrap mechanism and a concrete mapping
of required contract operations to Windows primitives. Prefer an existing
authenticated protocol transport if it works securely under MXC. Use inherited
handles for bootstrap where supported; do not commit to a new named-pipe data
transport before checking existing transport reuse. Loopback TLS is a candidate
only if endpoint access and egress fencing remain enforceable.

The first go/no-go gate is trustworthy runtime admission, process identity,
and non-bypassable network mediation. A successful authenticated connection is
insufficient. If these require MXC capabilities we do not have, identify the
specific missing primitive immediately instead of spending time on a proxy-only
approximation. Do not weaken the common admission contract to accelerate launch.

Phase 2: shared RFC 0012 runtime

This is the required final architecture. The gateway supplies authenticated
policy/session services; the MXC driver provisions the two runtime processes
and their containment and bootstrap resources:

Gateway / MXC driver
        |
        | gateway authentication + policy/session services
        v
openshell-supervisor --role=isolation-backend       (host)
        |
        | authenticated, per-generation runtime transport
        v
openshell-sandbox                                  (inside MXC)
        |
        | launch, monitor, and control
        v
workload

The diagram shows logical relationships, not a single direction of traffic.
The supervisor connects to the gateway; requests and events travel both ways.
The driver separately provisions and tears down the host supervisor and the MXC
boundary. It does not become a policy or forwarding hop between these peers.
The host supervisor is a per-sandbox-generation process, outside the workload's
access boundary. The in-boundary runtime must also protect its control handles
and bootstrap keys from workload access; merely placing it inside MXC does not
establish that protection.

Final ownership boundaries

Component	Owns	Must delegate
Gateway	Sandbox records, policy/provider configuration, supervisor authentication and session admission	Runtime operations through the standard supervisor path
MXC driver	MXC provisioning, host supervisor placement, outer filesystem/UI/network restrictions, protected bootstrap, generation ownership, final teardown	Workload launch/control to the runtime through the supervisor; policy and credential mediation to the supervisor
Host supervisor	Gateway session, admitted policy, provider resolution/refresh, egress decisions, common forwarding orchestration	Windows process and sandbox-local connection operations through the backend contract
Windows sandbox runtime	Canonical process launch and observation, authorized process operations, protected transport endpoint, sandbox-local connection primitives and identity evidence	Policy and provider-secret decisions to the supervisor
Workload	Application execution with intended environment and public trust material	Governed network access through the enforced mediation path

For incoming TCP forwarding, the gateway's standard supervisor path reaches the
runtime's loopback connection primitive and then the workload service. For
outgoing traffic, Windows enforcement must route governed connections through
supervisor policy evaluation and prevent direct bypass. These are separate
flows; implementing incoming forwarding alone does not complete egress mediation.

The gateway supplies supervisor authentication via trusted launch inputs. Only
the host supervisor consumes that identity. The runtime receives its separate
boundary credentials, and the workload receives neither set. Raw provider
credentials and interception CA private keys remain outside the MXC workload
boundary. Bootstrap may pass through driver-owned protected resources, but no
secret-bearing payload belongs in process arguments or general shared files.

Implementation sequence

1. Extract/reuse portable boundary protocol and transport code. Add Windows
   implementations behind explicit platform interfaces rather than scattering
   MXC branches through supervisor session, proxy, and forwarding code.
2. Implement Windows runtime process launch, exit/status, signaling, environment
   delivery, handle isolation, and loopback connection operations. Preserve
   canonical argv and lifecycle semantics. Define supported exec/TTY behavior;
   do not advertise unimplemented operations.
3. Implement trustworthy Windows identity and containment evidence required by
   RFC 0012. ETW observations alone are not synchronous authorization evidence.
   Resolve any contract gaps before claiming compatibility; if a contract change
   is needed, make it explicit and separately reviewed.
4. Add the protected transport proven in Phase 1. Reuse the common authenticated
   boundary protocol where possible. Bind bootstrap credentials to sandbox ID,
   runtime generation, and intended peer, with replay rejection and fail-closed
   disconnect behavior. Endpoint ACLs supplement authentication.
5. Have the driver provision the host supervisor and in-boundary runtime as one
   lifecycle unit. Deliver feat(isolation): implement the RFC 0012 sandbox architecture #2942 supervisor launch authentication only to the
   external supervisor and distinct boundary credentials to the runtime.
   Update backend registration/descriptor handling where needed; the current
   supervisor CLI selects the OpenShell sandbox backend explicitly.
6. Move gateway policy/session handling and provider resolution to the supervisor.
   Replace create-scoped credential snapshots only after the common refresh and
   revocation path works. Stage only public CA material and intended workload
   placeholders inside the boundary.
7. Attach normal gateway forwarding to the backend's loopback connection
   primitive. Reuse common duplex, cancellation, and half-close handling;
   remove the MXC driver forwarding bypass after equivalent tests pass.
8. Make readiness require the supervisor session and admitted runtime, and adjust
   capability reporting accordingly. Preserve MXC UI/filesystem enforcement in
   provisioning while keeping dynamic policy evaluation in the supervisor.
9. Preserve the outer network fence. Specify how Windows traffic reaches the
   supervisor and how identity is obtained; a protocol port alone does not
   provide Linux seccomp interception or prevent bypass. Reject policies whose
   guarantees cannot be enforced on Windows.
10. Delete the bespoke relay, protocol handlers, obsolete configuration, and
    driver credential side channel when no supported path needs them. Remove
    only MXC-specific host-proxy code proven unused; retain standalone proxy mode.

PR and compatibility sequence

• First: Phase 1 probes and contract mapping, tied to the accepted issue.
• Next: minimal Windows compilation and platform implementations in existing
  supervisor/runtime crates. Keep Linux behavior covered by existing tests.
• Next: a complete vertical slice: driver provisions the host supervisor and
  runtime, they authenticate and confirm enforcement, the gateway admits the
  supervisor session, the runtime launches one command, and exit/stop/delete
  reliably clean up the generation. Include a command without a listening port.
• Next: standard TCP forwarding and governed outbound networking, using common
  protocol operations; validate policy and provider refresh/revocation through
  the supervisor. These complete the enforcement work proven feasible in Phase 1.
• Last: remove the custom relay and MXC bypass paths, qualify real-MXC behavior,
  and update packaging/configuration/docs as part of the same cutover.

Use these as reviewable implementation slices, not separately shipped runtime
architectures. Keep #3370 draft until the final path is qualified; revise its
description around the final implementation rather than presenting it as only
a rebase. Preserve reusable UI mapping, policy tests, and auth work. Fix the
UI-backfill and other surviving findings in their owning components; deleting
the relay does not automatically fix them.

Scope choices that shorten delivery

• Qualify x64 process_container first. Keep isolation_session unsupported
  in the converted path until independently qualified; reject selection clearly
  instead of falling back to the old relay. Follow with ARM64 qualification.
• Reuse the existing gateway session, credential refresh, policy engine, backend
  contract, and boundary messages. Add only the necessary Windows platform code
  and transport adaptation; avoid a new public API or generic plugin framework.
• Default to the existing OpenShell sandbox backend and protocol. Introduce a
  distinct backend only if the contract mapping proves that necessary.
• Do not introduce restart recovery, a Windows service installer, or optional
  interactive TTY features into the first slice. Required backend operations
  still have to pass admission and conformance; unsupported optional features
  must be reported truthfully.
• Do not spend implementation effort hardening a relay that will be deleted.
  Carry its failure cases into shared-runtime regression tests, including stalled
  readers, half-close, payload logging, and cleanup after errors.

Critical path: enforceable Windows boundary and protected bootstrap → admitted
supervisor/runtime pair → canonical workload lifecycle → forwarding and provider
mediation → real-MXC qualification and legacy removal. Windows compilation can
proceed alongside the initial probes once the platform interfaces are agreed.

For changed pc_relay_* configuration, either translate old settings without
changing their security properties or reject them with an actionable migration
message. Never silently fall back to unprotected direct launch. Restarts create
fresh generations and invalidate old channels and forwarding sessions.

Update the existing architecture overviews, MXC README, gateway-config and
compute-driver references, public/contributor skill guidance, build packaging,
and relevant examples in the corresponding implementation PR. Apply
sync-agent-infra when component inventories and workflow coverage change.

Validation and completion gates

Contract and regression tests must cover:

• Bidirectional sustained traffic, a stalled reader in either direction,
  request EOF followed by a response, abrupt peer loss, and bounded resource use.
• Late open/reply cleanup, malformed/partial frames, protocol mismatch, and
  cancellation while opening, writing, or closing a session.
• Concurrent stop/delete/natural exit; process kill/wait failures; driver and
  supervisor crashes; failed startup; two complete create/start/stop/delete cycles.
• Two sandboxes with shared cwd, overlapping target ports, and distinct
  generations: no crossed routing, shutdown, credentials, or stale reconnect.
• Secret absence in process argv, debug artifacts, logs, and unintended inherited
  handles/environment; rejection of wrong peer, sandbox, and generation.
• UI/filesystem enforcement, direct-egress denial, proxy credential rejection,
  bound provider substitution, refresh/revocation, and accurate
  binary identity. Existing Linux runtime behavior must remain unchanged.

Run targeted Rust tests, pre-commit, unit tests, and local CI as required by the
repository. Run relevant sandbox E2E and Windows MSVC build/test lanes. Real MXC
qualification is mandatory for transport reachability, handle protection,
process-tree cleanup, and enforcement; Linux cross-compilation is insufficient.
Qualify supported architectures/backends individually and mark untested ones
unsupported rather than extrapolating a passing result.

The plan completes when the standard supervisor
session and boundary protocol own runtime operations, the required backend
conformance passes, capability claims match observed enforcement, and no bespoke
relay remains in the supported MXC path.

Final removal checks: no openshell-supervisor-relay deployment, no MXC JSON
launch/forward protocol, no driver-owned provider snapshot handoff for the
converted path, no embedded MXC host proxy on that path, and no independent
driver readiness claim that bypasses supervisor/runtime admission. Preserve
driver resource-health reporting and emergency process-tree teardown; those
remain compute-driver responsibilities. If Windows cannot satisfy a required
identity, containment, or transport invariant, record the blocker and revisit
the design explicitly. An interim bridge is outside the selected scope.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3370.docs.buildwithfern.com/openshell