Merge nucleic/olive-jade-civet-rznt into dev

NucleicBroker/Wslc/WslcFacade.cs

@@ -16,13 +16,17 @@ namespace NucleicBroker.Wslc;
 // enum, RegistryAuth as a string, ImageInfo.Name/.Sha256, and two separate output events
 // instead of one with a stderr flag.
 //
-// Three differences are NOT renames and need decisions before this file is finished:
-//   1. there is no container enumeration at all, so §2.3 broker reattach and the
-//      container.list RPC have no API behind them;
-//   2. there is no per-container statistics call, so container.stats must exec cgroup
-//      reads inside the container instead;
-//   3. there is no pty and no uid/gid on ProcessSettings, so §7's Terminal panel loses
-//      tty mode and exec wraps argv in setpriv/su (which §3.2 already anticipated).
+// Three things the SDK genuinely cannot do — enumerate containers, report per-container
+// stats, or allocate a pty — and which `wslc.exe` CAN, addressing containers by name. So
+// this class becomes a HYBRID: the SDK for the hot path (session, create/start/stop, exec
+// with event stdio, pull with progress), and the CLI for the cold paths it lacks
+// (`wslc container ps` for the reattach roster, `wslc container stats`, `-it` for the
+// Terminal panel). That split lives entirely here — `IWslc` does not change, so nothing
+// on the Swift side knows which arm answered. See §13.1 for the evidence, including the
+// unanswered microsoft/WSL#41024 discussion reporting the same gap.
+//
+// Also note: `ProcessSettings` has no uid/gid, so exec wraps argv in setpriv/su — which
+// §3.2 already anticipated as the fallback, so it costs nothing.
 //
 // Read §13.1 before touching this file. Fixing it is the next step of item 5, and it is
 // now a fast loop: the package restores, so `dotnet build -p:UseWslc=true` compiles it.

spikes/README.md

@@ -67,8 +67,9 @@ for, and nothing above it should move. These three are different:
 
 | Finding | Consequence |
 | --- | --- |
-| No create-or-attach on `Session` | Broker-crash reattach (§2.3) has no mechanism; supervision needs redesigning before item 11. |
-| No gateway address on a live `Session` | §5's primary transport loses its source; promote the AF_HYPERV/AF_VSOCK fallback and spike that instead. |
+| No container enumeration, stats, or pty in the SDK | **Not fatal** — `wslc.exe` has all three and addresses containers by name, so `WslcFacade` becomes a hybrid (SDK hot path + CLI cold paths). Confirmed by the native header and the API reference, and publicly reported in [microsoft/WSL#41024](https://github.com/microsoft/WSL/discussions/41024), which Microsoft has not answered. |
+| No create-or-attach on `Session` | Still open. The native-only `WSLC_CONTAINER_START_FLAG_ATTACH` may be it; the C# `Start()` takes no flags. Needs a live answer before item 11. |
+| No gateway address anywhere on the API | §5's primary transport must source it from `GetAdaptersAddresses` over the `vEthernet (WSL)` adapter instead. If a `Bridged` container can't reach the host there, promote the AF_HYPERV/AF_VSOCK fallback. |
 | No uid on `ProcessSettings` | Recoverable, and already planned for: exec wraps argv in `setpriv`/`su agent -c`. Interceptors and nash don't care about the numeric uid (§3.2). |
 
 ---