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

NucleicBroker/Wslc/WslcFacade.cs

@@ -16,14 +16,21 @@ namespace NucleicBroker.Wslc;
 // enum, RegistryAuth as a string, ImageInfo.Name/.Sha256, and two separate output events
 // instead of one with a stderr flag.
 //
-// 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.
+// Four things this SDK cannot do at all — enumerate containers, report per-container stats,
+// allocate/resize a pty, and attach to an existing container or session. That is not the
+// projection hiding them: `wslcsdk.dll` wraps `WSLCCompat.idl`, the deliberately-stable
+// SDK-facing COM surface, and that surface genuinely lacks them.
+//
+// They DO exist on `wslc.idl`, the service-internal COM interface `wslc.exe` itself calls
+// (IWSLCSessionManager, IID 82A7ABC8-6B50-43FC-AB96-15FBBE7E8760) — ListContainers, Stats,
+// ResizeTty, OpenContainer/Attach, OpenSessionByName, and IWSLCVirtualMachine::GetId, which
+// is the VM GUID an AF_HYPERV bind needs. Both IDLs are in the open-source WSL repo. The
+// internal one carries an explicit "ABI breaking changes are OK" warning.
+//
+// So there are two ways to close the gaps — direct internal COM, or shelling out to
+// `wslc.exe` — with a real stability-versus-fidelity trade-off between them, and it has NOT
+// been decided. §13.1 lays it out. Whichever wins lives entirely inside this class: `IWslc`
+// does not change, so nothing on the Swift side knows which surface answered.
 //
 // 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.