Merge nucleic/lucid-river-toad-6efj into dev

spikes/README.md

@@ -172,14 +172,56 @@ for, and nothing above it should move. These three are different:
 
 ---
 
-## Not yet written
+---
 
-- **`WslcSpike`** — the typed happy path: session → GHCR pull of `naros-agent` → container with an
-  NTFS `ContainerVolume` → `exec git status` in the bind-mounted worktree → stdio round-trip →
-  SIGTERM, plus the 9P latency numbers §15 wants (`git status` and `npm install` on a real repo,
-  mounted vs. in-VM). Deliberately held back until `WslcApiDump` has run: written now, against
-  guessed names, it would not compile, and fixing it blind is the mistake this whole approach
-  exists to avoid.
+## `WslcSpike` — does any of it actually work?
+
+M1 spike (a2). The whole Windows container subsystem now compiles and **none of it has ever
+run**: `WslcFacade` (compat SDK), `WslcInternal` (D13 Tier 1 recovery), the §3.3 RPC surface.
+This drives all of it the way hostd does — spawn `nucleic-brokerd.exe`, speak NDJSON JSON-RPC
+over its stdio — so what passes here is the shipping code and not a rehearsal of it.
+
+That is why it is a **client** of the broker rather than a second program calling wslc. Its
+csproj is plain `net9.0` with no wslc reference at all, so it *cannot* drift into a parallel
+implementation, and it builds on any machine even though it only runs on Windows.
+
+```powershell
+dotnet build windows\NucleicBroker\NucleicBroker.csproj -p:UseWslc=true   # the broker it drives
+dotnet run --project windows\spikes\WslcSpike -- --repo C:\src\nucleic
+```
+
+Options: `--image` (default `ghcr.io/abkslm/naros-agent:26.07`), `--container`, `--session-name`,
+`--iterations` (timing runs, default 5), `--broker <path>` if autodiscovery fails,
+`--no-recovery` to skip the crash test.
+
+It answers three open questions:
+
+1. **Does the happy path work?** session → GHCR pull → container with an NTFS `ContainerVolume` →
+   exec → stdio round-trip → signal → teardown. Also prints the §5 host gateway, which no wslc
+   API surfaces and the control plane depends on entirely — an empty or loopback value there is
+   M1 (b)'s answer arriving early.
+2. **Is 9P fast enough for D8?** §15 lists NTFS bind-mount performance as a top risk with no
+   numbers behind it. The spike times `git status` in the mounted worktree *and* in a copy on the
+   container's own ext4 — same container, same repo, so the mount is the only variable — then
+   reports the ratio and what it implies. It deliberately does not "fix" a bad result by moving
+   repos; §15 says surface that to the user, and a spike that silently relocated things would
+   hide the very finding it exists to produce.
+3. **Does D13 Tier 1 recovery work?** It kills a broker with the session up — the exact §2.3
+   crash — starts a fresh one, and reports whether the orphan was cleared or whether it still
+   fails `session_exists`. It distinguishes "Tier 1 never bound" from "Tier 1 bound and did not
+   work", because those are different bugs.
+
+Every step prints what happened rather than asserting: a spike's product is evidence. It exits
+non-zero only when a step that should have worked threw. The `[brokerd]` lines interleaved in the
+output are the facade's own stderr diagnostics — where `WslcFacade`/`WslcInternal` report what
+bound and what degraded — and are usually the fastest route to a cause.
+
+`--iterations` on a large repo is the number that matters for D8; the default 5 on a small one is
+a smoke test, not a measurement.
+
+---
+
+## Not yet written
 - ~~**The internal arm, Tier 1 — "recover"**~~ **written**: `windows/NucleicBroker/Wslc/WslcInternal.cs`.
   On broker restart it opens the orphaned session, lists its containers for the log, terminates
   it, and lets the facade start fresh — automatic clean recovery instead of a manual