5db1d50b

docs: step 3 plan gains Task 9, the cross-OS journeys gate

a73x 2026-09-04 10:16

Commit message

docs: step 3 plan gains Task 9, the cross-OS journeys gate

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SakwJEwD9dXBoRP5kWbemW

docs/superpowers/plans/2026-09-03-macos-port-step3-darwin-arm.md

+---
+### Task 9: `test/xos.sh` — cross-OS journeys: a Mac client on a Linux daemon, a Linux client on a Mac daemon
+**Ruling (user, 2026-09-04):** "once macos builds we'll also need to test
+macos client to linux daemon and vice versa." The macOS port is a second
+ARM of one product, and the wire is the claim step 3 has not graded: every
+pin so far runs one OS on both ends. This task attaches across the seam in
+both directions, over both transports, and pins that a cross-arch
+`mux d upgrade HOST` is refused before a byte moves.
+**Execution order:** run this task BEFORE Task 8, so Task 8's
+`docs/decisions.md` entry records the cross-OS verdict beside the Mac e2e
+table. The number is 9 because it was added after the plan was cut.
+**The fixture (a human/eitri action, never harness code, the `vm.sh` rule):**
+- The MAC is the HOST `squirtle` (`$MUX_MAC`, arm64, macOS 26): it holds
+  the toolchain and builds; `make install` there puts an aarch64 `mux` in
+  `~/.local/bin`, which is where `client.handoff`'s appended PATH finds it
+  for a non-login ssh (`local_bin_append`). The macOS GUEST is not used:
+  it holds no key for any Linux box and a pristine guest must stay that way.
+- The LINUX daemon box is `mux-lan` (`$MUX_LAN`, default
+  `ubuntu@192.168.0.37`): an eitri VM on host `onyx` with its `lan`
+  network, x86_64 Ubuntu, reachable by plain ssh from BOTH this box and
+  the Mac (squirtle's `~/.ssh/id_ed25519.pub` was authorized by cloud-init,
+  this box's key appended after; the `mux-vm-gate` cert is refused there).
+  Made 2026-09-04 with eitri `vm_create {name: mux-lan, host: onyx,
+  network: lan}`; the DHCP lease can move, `vm_info` re-reads it.
+- This box is the Linux CLIENT and the orchestrator: `zig-out/bin/mux`
+  and `zig-out/bin/ptyclient` from this tree drive the Linux→Mac legs.
+- Reachability measured 2026-09-04: squirtle cannot ssh INTO this box
+  (publickey denied) or the e2e VM (charizard's private network), which is
+  why a LAN box exists. The Mac's non-interactive ssh PATH is
+  `~/.cargo/bin:/usr/bin:/bin:/usr/sbin:/sbin` — no brew, no
+  `~/.local/bin` — so every harness ssh onto the Mac spells
+  `$HOME/.local/bin/mux` and the repo's shim PATH itself.
+**Files:**
+- Create: `test/xos.sh`
+- Modify: `Makefile` (`xos` target, beside `vm` and `mac`, never inside `ci`), `README.md` (one paragraph under the macOS section naming the gate and its two boxes), `CLAUDE.md` (the toolchain block's `make vm` line gains `xos`)
+**Interfaces:**
+- Consumes: `MUX_MAC` (default `squirtle`), `MUX_LAN` (default `ubuntu@192.168.0.37`), the repo at `~/code/rad/mux` on the Mac, `deps/mac-sdk/bin` on the Mac PATH, `test/os_oracle.sh` (its Linux arm runs on `mux-lan`, its Darwin arm on the Mac), `test/vm.sh`'s reset block and `test/mac.sh`'s `hssh`/push legs as the shapes to copy, `mux a`'s `--quic HOST --key PATH` spelling, `main.zig`'s refusal line `mux d upgrade: HOST is ARCH and this image is ARCH; refusing to push a binary that cannot run there`.
+- Produces: `make xos`, exit 0 with `xos OK (N legs ...)`; the verdict Task 8 records.
+- [ ] **Step 1: The script**, shaped like `test/mac.sh` (`set -eu`; BatchMode
+  everywhere the harness itself sshes; `ok`/`fail` with a literal leg-count
+  pin; every claim about a box asserted by a SEPARATE ssh reading that box
+  through the oracle, never by trusting the connection under test). Two
+  helpers, `mssh SECONDS` (script on stdin, on the Mac, under `/bin/sh -s`,
+  every inner ssh takes `-n` — `mac.sh`'s rule) and `lssh SECONDS` (the
+  same onto `$MUX_LAN`). Legs, each named:
+. `push` — `mac.sh`'s push leg verbatim (`--force` to `mac-journey`,
+   detach first, `HOST_SHA` equals `HEAD_SHA`).
+. `build` — on the Mac: `make build` and `make install` under the shim
+   PATH (`export PATH=$HOME/code/rad/mux/deps/mac-sdk/bin:/opt/homebrew/bin:$PATH`);
+   `$HOME/.local/bin/mux --version` equals this tree's `zig-out/bin/mux --version`.
+   Here: `$(ZIG) build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe -p dist/xosgate`
+   (the Makefile does it, `vm`'s spelling — static musl because `mux-lan`
+   is a VM on a host whose CPU this box did not build for; the laptop was
+   bricked by a native push once, `docs/decisions.md` 2026-09-01), and
+   this box's own `zig build` for the Debug client and `ptyclient`.
+. `reset` — on `mux-lan`, `vm.sh`'s scorched-earth block verbatim
+   (kill every mux, remove `~/.local/bin/mux`, state, cache, config and
+   `$XDG_RUNTIME_DIR/mux*`, `enable-linger`, the bashrc PATH line); then
+   `scp` the musl `mux` to `~/.local/bin/mux` and `test/os_oracle.sh` to
+   `~/xos/`; `~/.local/bin/mux --version` equals the tree's. On the MAC
+   nothing is killed and nothing under `~` is removed — it is the user's
+   machine, not a throwaway: the leg REFUSES with a clear line if
+   `pgrep -x mux` finds a mux there already ("stop it or run on another
+   Mac"), and asserts `/tmp/mux-$(id -u)` is absent, so the daemon the
+   Linux→Mac legs meet is the one they start. Both boxes: an isolated
+   `XDG_STATE_HOME` for every mux the HARNESS runs (`~/xos/state` there,
+   `$SCRATCH/state` here), because every attaching mux writes its daemon
+   into the hosts file (CLAUDE.md) — the daemons themselves run under
+   each box's DEFAULT runtime dir, since that is where the entry dial's
+   `mux d endpoint --start` will look.
+. `keys` — one 32-byte QUIC key for the run: `mux d keygen` into
+   `$SCRATCH/key` here, then installed 0600 at `~/xos/key` on both remote
+   boxes. Never `~/.config/mux/key` on the Mac (the user's). Every daemon
+   below starts with `--key ~/xos/key`, every QUIC client dials with
+   `--key`/`MUX_KEY_FILE`.
+. `mac-to-linux` — on `mux-lan`:
+   `MUX_SHELL_INTEGRATION=1 ~/.local/bin/mux d start -d --quic 0.0.0.0 --key ~/xos/key`;
+   read `LPID` (`pgrep -x mux`). On the Mac, `zig-out/bin/ptyclient` (built by
+   leg 2) drives `$HOME/.local/bin/mux $MUX_LAN` on a real pty with
+   `XDG_STATE_HOME=$HOME/xos/state`: `expect \x1b[?1049h`, settle,
+   `send printf "XOS-M2L-%s-%s\\n" $(uname -m) $$\n`, `expect XOS-M2L-x86_64-`,
+   detach with `\x1cd`, `waitexit`. The marker carries the SESSION shell's
+   `uname -m`, so `x86_64` on a Mac's screen is the cross-OS fact itself.
+   Read the shell pid off the capture; assert on `mux-lan` via the oracle
+   that `pid_children LPID` lists it; assert the capture holds NO
+   `landed over ssh` line (the entry dial fetched the daemon's QUIC
+   coordinates over ssh and moved onto QUIC — inbound UDP to a LAN VM
+   works, `mux-test-boxes`' rule), and via the oracle
+   `udp_local_bound LPID 4433` on `mux-lan`. `mux d dump` on `mux-lan`
+   still holds the marker after the detach.
+. `mac-to-linux-quic` — on the Mac, no ssh in the path:
+   `MUX_KEY_FILE=$HOME/xos/key $HOME/.local/bin/mux a run --quic 192.168.0.37 --key $HOME/xos/key --timeout 20000 'echo m2lq-$$'`
+   (`mux a` joins the session leg 5 made; `--quic HOST --key PATH` is its
+   own spelling): reply carries `"mechanism":"marks"`, `"exit_code":0`,
+   and a pid that `pid_children LPID` on `mux-lan` lists. This is the
+   Darwin wolfSSL build's PSK handshake against the musl build's, in one
+   round trip, with no ssh to fall back to.
+. `linux-to-mac` — from HERE: `zig-out/bin/ptyclient` drives
+   `zig-out/bin/mux $MUX_MAC` with `XDG_STATE_HOME=$SCRATCH/state`; the
+   entry dial runs `ssh squirtle 'PATH=...; mux d endpoint --start'`, which
+   is the daemon's ONLY starter on the Mac in this gate (`asked` is the
+   entry dial's alone). Marker `XOS-L2M-%s-%s` with `$(uname -m)` → expect
+   `XOS-L2M-arm64-`. Then on the Mac via the oracle's Darwin arm (the repo
+   checkout at `mac-journey` has it): `MPID` is `pgrep -x mux`,
+   `pid_holds_unix_sock MPID /tmp/mux-$(id -u)/muxd.sock` (no
+   `XDG_RUNTIME_DIR` on an ssh login — the Task 2 fallback, exercised by a
+   REAL `mux HOST`), `pid_exe MPID` equals `$HOME/.local/bin/mux` resolved
+   with `cd -P`/`pwd -P` (mac.sh's spelling), `pid_children MPID` lists the
+   shell pid. The daemon has no `--quic` here because the entry dial
+   started it bare, so this attach is the ssh-handoff transport: assert
+   the capture DOES say the attach landed over ssh, or — if the daemon
+   announces a QUIC arm anyway — record which and assert that one; the
+   implementer reads the announce and pins what it says, with the reason in
+   the leg's comment.
+. `linux-to-mac-quic` — on the Mac, stop the bare daemon
+   (`$HOME/.local/bin/mux d stop`, `pid_alive MPID` false within 3 s) and
+   start `MUX_SHELL_INTEGRATION=1 $HOME/.local/bin/mux d start -d --quic 0.0.0.0 --key $HOME/xos/key`;
+   from HERE `MUX_KEY_FILE=$SCRATCH/key zig-out/bin/mux a run --quic 192.168.0.47 --key $SCRATCH/key --timeout 20000 'echo l2mq-$$'`
+   after a pty attach `zig-out/bin/mux quic://192.168.0.47` (with the key
+   in `MUX_KEY_FILE`) has made a session: the reply's pid is a child of
+   the new `MPID`. **This is the leg that asks whether macOS delivers
+   inbound UDP 4433 to a daemon a non-GUI ssh session started.** If the
+   application firewall eats it, the leg fails with the dial's own words;
+   record that in the report as a product/platform finding, do NOT loosen
+   the leg — a Mac daemon nobody can dial over QUIC is a fact the user
+   needs, not a harness problem.
+. `upgrade-refused` — both ways, with the daemons of legs 5 and 8 up.
+   From HERE: `zig-out/bin/mux d upgrade $MUX_MAC --allow-same-version`
+   exits nonzero and stderr matches
+   `is arm64 and this image is x86_64; refusing to push a binary that cannot run there`;
+   on the Mac, `pgrep -x mux` is still `MPID` and `pid_exe` unchanged.
+   From the MAC: `$HOME/.local/bin/mux d upgrade $MUX_LAN --allow-same-version`
+   exits nonzero, stderr `is x86_64 and this image is arm64; refusing …`;
+   on `mux-lan`, `LPID` and its `pid_exe` unchanged. The preflight's
+   `uname -m` is the gate and nothing is streamed: assert the installed
+   binary's sha on each box (`shasum -a 256` / `sha256sum`, through the
+   oracle if it has a helper, else the two spellings in a `case`) equals
+   what leg 3 / leg 2 installed.
+. `stop` — `mux d stop` on both boxes with the isolated key/state;
+    `pid_alive` false within 3 s each; the Mac's `/tmp/mux-$(id -u)`
+    socket gone; `mux-lan`'s `$XDG_RUNTIME_DIR/muxd.sock` gone.
+. Cleanup trap: stop any daemon the run started on either box, always;
+    remove `~/xos` on `mux-lan`; on the Mac remove `~/xos` only (never
+    `~/.local/bin/mux`, which `make install` owns and the user may want).
+- [ ] **Step 2: Run it** — `make xos` from this box, twice; every leg
+  prints its name and `ok`; exit 0. Record per-leg wall-clock and which
+  transport each attach landed on in the report. A leg that fails on a
+  PRODUCT difference (leg 8's firewall question is the expected one) is
+  reported with the box's own words and left RED — the user decides.
+- [ ] **Step 3: Commit** — `test: make xos attaches a Mac client to a Linux daemon and a Linux client to a Mac daemon, over ssh and QUIC`
+---
+## Self-review
+- **Spec coverage:** Step 3's two arm files (Tasks 3, 4), harness `case "$(uname)"` arms (Task 6), the dep-script arm (Task 1, already in tree), the two hardware probes (answered, recorded in rulings and Task 8), the three named Darwin differences (Task 3 doc header + Task 8), the `runtimeDir` spelling (Task 2), the Testing section's gate — `make ci` on the Mac is Task 8's run, the oracle's own test is Task 6 Step 4, the `make vm`-shaped journey is Task 7. The Deferred build-host decision is ruling 1.