feat(devcontainer): drive wmux from a container over the TCP bridge - #170

`--wsl` picked `0.0.0.0` on the strength of a comment:

    // WSL2's NAT gives the distro an address the container resolves as
    // host.docker.internal, but 127.0.0.1 inside the distro is not it.

That is true, and it is true only under NAT. NAT is WSL2's default, so the
assumption holds on most machines — but `networkingMode=mirrored` (WSL 2.0+ on
Windows 11) removes the distro's network namespace entirely and gives it the
Windows host's interfaces instead, LAN adapter and VPN adapter included.
`0.0.0.0` in a mirrored distro is a bind on the corporate network, not on an
isolated 172.x. What filters it is the Hyper-V firewall rather than the ordinary
Windows Firewall profile, and the recipe everyone copies to make WSL reachable
is exactly the one that opens it:

    Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-...}' -DefaultInboundAction Allow

Mirrored plus that setting puts wmux's control pipe on the LAN. The pipe token
authenticates every request either way, so this is exposure rather than an open
door — but it is a configuration people actually run, not a hypothetical future
WSL change, and it is not a default to pick on someone's behalf.

So the mode is established at runtime instead of inferred from the fact that we
are in WSL:

  * WSL first — "microsoft"/"wsl" in /proc/sys/kernel/osrelease AND WSL_INTEROP
    or WSL_DISTRO_NAME set. Both, because each is weak alone: a container can
    mount a /proc carrying the host's kernel string while having its own network
    stack, and the env vars are inherited by anything a WSL shell launches.
    `--wsl` outside that refuses and names what it looked for.
  * Then `wslinfo --networking-mode`, which prints `nat` or `mirrored`.
  * `nat` → bind 0.0.0.0 as before, and say on startup why that is contained,
    including that it stops being true under mirrored.
  * `mirrored` → refuse to pick 0.0.0.0. The error explains that the distro
    shares the host's adapters, names the Hyper-V firewall as the thing standing
    between the bind and the LAN, and points at `--host <addr>`.
  * absent or unparseable (wslinfo needs WSL 2.0.5+) → `unknown`, which refuses
    too. Folding it into `nat` would restore the old silent 0.0.0.0 on exactly
    the hosts least able to report what they are doing.

An explicit `--host` is always honoured, `--host 0.0.0.0` under mirrored
included: that is a stated choice rather than an inherited default, and
overruling it would only push people to a wrapper script and lose them the
warning. The beyond-loopback warning is upgraded under mirrored to say the bind
is on the host's real interfaces.

The decision is a pure function in src/cli/wsl-network.ts, so the whole table —
nat/mirrored/unknown x in-WSL-or-not x explicit-host-or-not — is tested on Linux,
including the mirrored branch, which cannot be exercised on a NAT host.

docs/DEVCONTAINER.md asserted flatly that the bind is "reachable from containers
on that host and not from the LAN" and "needs no Windows firewall rule". Both
passages are now qualified with the mode, and there is a Mirrored networking
section with the `.wslconfig` setting, the firewall cmdlet, the `wslinfo` check
and what to pass instead.

Not verified against a real mirrored distro — that needs a machine to flip
`networkingMode` on and shut WSL down, which was not available here. The refusal
is the safe default if the detection is wrong in either direction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

`wmux raw-v1` took any line and handed it to the V1 handler. It exists for one
caller — wmux-bash-integration.sh reporting shell state from inside a
devcontainer, where it cannot reach the pipe directly (issue amirlehmam#19) — but nothing
in it said so, so it was a generic V1 passthrough in practice.

That is a standing side door rather than a bug with a symptom. Every V1 command
added later becomes reachable from a container the day it lands, without anyone
deciding it should be, and the pipe's V1 surface stops being something the V1
handler alone defines. `notify` and `report_pr` are already reachable that way
today and have no business being.

The set the integration emits is six verbs long, so name them:

    report_pwd  report_git_branch  clear_git_branch
    report_shell_state  ports_kick  report_startup_command

The first five are every `_wmux_report` call site in the shipped script. The
sixth comes from the other side: the devcontainer feature appends a
`report_startup_command` line to its own copy of the integration so a restored
pane can be relaunched, so leaving it out would break that path.

Anything else exits non-zero naming the accepted set. `raw-v1` keeps its usage
string and its COMMANDS entry — the command is still there, it is just no longer
a wildcard.

The test derives the expected verbs from the shipped script rather than
restating them, because the allowlist and the integration drifting apart is the
one failure that silently breaks reporting in a container.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The CLI and the Claude Code hook helper are two processes dialling the
same socket, and each carried its own deadline. wmux.ts derived one from
`remoteTarget || usesNpiperelay()`; wmux-hook.ts wrote `remote ? 30000 :
5000`. Same intent, two spellings — and the hook's did not know about
npiperelay, so a hook firing from a WSL shell armed the 5s local-pipe
timer for a hop that measures ~7s worst case and destroyed the socket
on a call that was going to succeed.

Both now describe their connection the same way — {remote, pipePath,
env} — and ask transport-deadline.ts for the number. The floor and the
slow-transport predicate live there and nowhere else, so a third client,
or a change to either value, has one place to find.

No behaviour change for a local pipe: the floor raises a deadline and
never lowers one, so a native Windows run keeps its original timings and
a browser verb keeps the longer budget it asked for. WMUX_RPC_TIMEOUT_MS
is likewise a floor rather than a cap.

The agreement test asserts both call sites still route through the
module and that neither has redeclared the constants inline, since a
re-hardcoded literal is precisely how the two drifted apart the first
time.

…orts

The CLI is packaged file-by-file — extraResources names dist/cli/wmux.js
and dist/cli/wmux-hook.js individually, not the directory. Until now that
was harmless because each file was self-contained. Splitting the deadline
derivation out (and, earlier in this branch, the WSL bind decision) makes
them require siblings that no build step ships.

This failure mode is worse than the one packaging.test.ts already guards.
A missing resource is a silently-absent feature behind an existsSync
warning; a missing sibling module is MODULE_NOT_FOUND on the first line
of `wmux ping` and of every Claude Code hook the moment they run from an
installed build. And `npm run dev` cannot show it — the module is sitting
right there in dist/.

So both are listed, and the check is derived from the imports rather than
written down: walk the relative imports out of every src/cli entry point
that extraResources ships, and require each to be shipped too. Adding the
next shared module without packaging it now fails `npm test`, which gates
the tag. Enumerating the two we know about is what let amirlehmam#149 through the
last version of this file.

Found by that check, not by review: wsl-network.js was already missing.

Fallout from making --wsl a checked claim. The suite spawned every bridge
with `--wsl`, but each of its tests connects over 127.0.0.1 — the flag
only ever picked the bind ADDRESS, which is a different question from the
upstream transport being asserted. Now that --wsl is verified against the
running environment instead of being a synonym for "bind 0.0.0.0", it
made the whole suite fail anywhere outside a real WSL2 distro for reasons
unrelated to the relay.

Replaced with an end-to-end test of the part a pure function cannot
reach. chooseBridgeHost() is handed `inWsl2`; readWslEnvironment() has to
produce it from /proc and the interop vars on the actual machine, and the
obvious spelling of that probe is wrong in a way that ships easily: a
Linux container on a Windows host runs on the WSL2 *kernel*, so its
osrelease reads "microsoft-standard-WSL2" while it has no Windows host to
reach and no interop to reach it with. Matching osrelease alone would
bind 0.0.0.0 in every devcontainer on Windows — the opposite of the point.

This suite runs inside exactly such a container, so that case is covered
by observation rather than by argument.

resources/cli/*.js is a copy of the tsc output in dist/cli/, and 42e3cca made
that an invariant rather than a hope: `npm run verify:resources` compares the
two byte-for-byte and CI runs it after build:main. So this is no longer
bookkeeping that can slip — the branch does not pass without it.

Two files are new. transport-deadline.js and wsl-network.js are shared modules
this branch introduces, and verify-resources compares directories, not a list
of names, so a build output with no copy fails the same way a stale copy does.
electron-builder.json names them too (earlier commit), for a different reason:
the CLI is packaged file-by-file, and a missing sibling is MODULE_NOT_FOUND on
the first line of every hook rather than a degraded feature.

The reason this is readable at all is 42e3cca. In amirlehmam#166 the same regeneration
read +1412/-445, which is what made that PR unreviewable: the checked-in copy
had drifted ~1700 diff lines behind its own source, so the bridge's output was
buried in years of unrelated rot. Regenerating from today's master, the diff is
just the bridge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>