45b67e78

test: make mac drives a pristine macOS guest on the Mac the way make vm drives the VM

a73x 2026-09-04 10:16

Commit message

test: make mac drives a pristine macOS guest on the Mac the way make vm drives the VM

The macOS half of `make vm`. The Mac host builds, because it holds the
toolchain and the shadow SDK; a macOS guest cloned fresh for every run
only RUNS what the host built, which is the stronger claim — a bare Mac
with no developer tooling on it.

Eight legs, each with its own failure line and each claim asserted by a
separate ssh reading the guest through test/os_oracle.sh: push, build,
vm, install, daemon, attach, session, stop. The daemon leg is where the
Darwin runtime fallback is exercised end to end — a fresh ssh login to a
Mac has no XDG_RUNTIME_DIR, so the daemon binds /tmp/mux-<uid>/muxd.sock
and the oracle grades the directory's mode and the fd that holds it.

`mux a` joins and never creates, so the pty attach that makes the session
runs before the agent leg that talks to it, rather than after as the plan
had them.

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

README.md

+deliberately — answering it would let anything in any session read
+whatever you last copied.
+## macOS
+mux builds and runs on an Apple-silicon Mac. The gate for it is `make mac`,
+which is the macOS half of what `make vm` is for Linux: it pushes this
+commit to the Mac named by `MUX_MAC` (default `squirtle`), builds it there,
+and then runs the user journeys against a *pristine* macOS virtual machine
+with no developer tooling on it, so what is graded is the product on a bare
+Mac rather than on the machine that compiled it. The VM is Cirrus Labs
+`tart`, and the base image is made once by hand, on the Mac:
+```sh
+brew trust cirruslabs/cli && brew install cirruslabs/cli/tart
+tart clone ghcr.io/cirruslabs/macos-tahoe-base:latest mux-mac-base
+tart run --no-graphics mux-mac-base &            # user admin, password admin
+tart exec mux-mac-base sh -c 'mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo "PUBKEY" >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'
+tart stop mux-mac-base
+```
+`PUBKEY` is that Mac's own `~/.ssh/id_ed25519.pub`. Every `make mac` clones
+`mux-mac-base` to `mux-mac`, boots the clone, and stops it on the way out,
+so no run can see the run before it.
+## How it works
+Both ends run a real terminal engine. The daemon's is authoritative: shell

test/mac.sh

@@ @@ -0,0 +1,420 @@ @@
+#!/bin/sh
+# test/mac.sh — the `make mac` gate: real user journeys on a real macOS.
+#
+# What `make vm` is to the Linux port, this is to the macOS one. The unit
+# suite and the e2e suite grade the code; this grades the PRODUCT on the
+# operating system it was ported to, spelled exactly as a user spells it.
+#
+# Two machines, and the split is the point. The HOST (a Mac, $MUX_MAC)
+# holds the toolchain and the shadow SDK, so it builds. The GUEST is a
+# macOS virtual machine cloned fresh for every run, with no developer
+# tooling on it at all, and it only RUNS what the host built — which is the
+# stronger claim: a bare Mac, not the machine that compiled the binary.
+#
+# The pristine guest is a human action, never harness code (test/vm.sh's
+# rule). Tooling is Cirrus Labs `tart`; the base image is
+# ghcr.io/cirruslabs/macos-tahoe-base (macOS 26). The base VM is made ONCE,
+# by hand, on the host:
+#
+#     brew trust cirruslabs/cli && brew install cirruslabs/cli/tart
+#     tart clone ghcr.io/cirruslabs/macos-tahoe-base:latest mux-mac-base
+#     tart run --no-graphics mux-mac-base &            # user admin, password admin
+#     tart exec mux-mac-base sh -c 'mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo "PUBKEY" >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'
+#     tart stop mux-mac-base
+#
+# PUBKEY is the host's own ~/.ssh/id_ed25519.pub, so the host can ssh into
+# the guest without a password; `tart exec` needs the guest agent the
+# cirruslabs images ship. `mux-mac-base` is never RUN by this script: every
+# run clones it to `mux-mac`, boots the clone, and stops the clone on the
+# way out. Hermeticity comes from the clone, which is why the daemon leg
+# can assert the guest holds no mux and no runtime directory before it
+# starts one — a second run must not be able to see the first run's.
+#
+# Every claim about the guest is asserted by a separate ssh reading the
+# guest through test/os_oracle.sh, never by trusting the daemon's own
+# report over the connection under test ("ask the OS about the OS").
+set -eu
+MAC="${MUX_MAC:-squirtle}"
+# Relative to the HOST's $HOME, because that is how ssh's scp-like remote
+# spelling (`squirtle:code/rad/mux`) resolves a path.
+REPO="${MUX_MAC_REPO:-code/rad/mux}"
+BRANCH=mac-journey
+VM_BASE=mux-mac-base
+VM_RUN=mux-mac
+GUSER="admin"
+# A LITERAL $HOME: this string is pasted into a command line the HOST's
+# shell parses, so the expansion has to happen there and not here.
+GKEY='$HOME/.ssh/id_ed25519'
+# BatchMode so a broken auth fails in seconds instead of prompting a
+# harness nobody sits in front of. The guest key is accept-anything because
+# a freshly cloned VM has a host key nobody has ever seen and takes a new
+# one on the next run; the guest is reachable only on the host's own
+# virtual network, and the host hop above it is BatchMode-authenticated.
+HOST_SSH="-o BatchMode=yes -o ConnectTimeout=10"
+# LogLevel=ERROR because a throwaway known-hosts file makes ssh announce the
+# new key on stderr every single time, and that line would be most of what a
+# green run prints.
+GUEST_SSH="-o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -o ConnectTimeout=10 -i $GKEY"
+# now_ms, and the file_mode/pid_* names the guest legs source for
+# themselves. The harness spells time and paths through the oracle so this
+# script would still answer if it were ever run FROM a Mac.
+. "$(dirname "$0")/os_oracle.sh"
+GIP=""          # the guest's address, set by the vm leg
+OK_COUNT=0
+PUSHED=no
+ok() {
+    OK_COUNT=$((OK_COUNT + 1))
+    echo "$1 ok${2:+ ($2)}"
+}
+fail() {
+    echo "mac FAIL: $1: $2"
+    exit 1
+}
+# hssh SECONDS — run the script on stdin on the HOST, under /bin/sh.
+#
+# /bin/sh and not the host's login shell (zsh): `$VAR` holding several
+# words does not word-split in zsh, so an options string pasted into a
+# command line there arrives as ONE argument and ssh answers "keyword
+# batchmode extra arguments at end of line".
+#
+# The rule for a script handed to this: any ssh INSIDE it takes -n. The
+# host's sh is reading its own script off stdin, and an ssh that does not
+# close its stdin swallows the rest of that script — silently, with a 0
+# exit, so the lines after it simply never run.
+hssh() {
+    _ht=$1
+    # shellcheck disable=SC2086 # HOST_SSH is words on purpose
+    timeout "$_ht" ssh $HOST_SSH "$MAC" /bin/sh -s
+}
+# What every guest command runs under. XDG_STATE_HOME is isolated because
+# every mux that attaches records its daemon in it (CLAUDE.md), and
+# XDG_RUNTIME_DIR is UNSET on purpose: a fresh ssh login to a Mac has no
+# such variable, and the Darwin fallback /tmp/mux-<uid> is exactly what the
+# daemon leg is here to exercise end to end.
+GUEST_PRELUDE='
+export XDG_STATE_HOME=$HOME/mux-e2e/state
+unset XDG_RUNTIME_DIR
+mkdir -p $HOME/mux-e2e
+cd $HOME/mux-e2e
+'
+# gssh SECONDS — run the script on stdin in the GUEST, through the host.
+#
+# The quoting rule is that there is NO quoting. The script rides this
+# shell's stdin into the host's ssh, which forwards it to the guest's
+# `sh -s`; no shell between here and there parses it as a command line, so
+# a leg writes ordinary sh with whatever quotes it likes and nothing is
+# escaped anywhere. The one thing a caller owes: always give this a
+# heredoc. Called with no redirect it reads the enclosing script's stdin.
+gssh() {
+    _gt=$1
+    [ -n "$GIP" ] || fail vm "gssh before the guest had an address"
+    # shellcheck disable=SC2086 # HOST_SSH is words on purpose
+    { printf '%s\n' "$GUEST_PRELUDE"; cat; } |
+        timeout "$_gt" ssh $HOST_SSH "$MAC" "ssh $GUEST_SSH $GUSER@$GIP sh -s"
+}
+# The clone is stopped on every exit, including a failing one. It is left
+# in place rather than deleted so a failure can be logged into, and the
+# next run replaces it.
+cleanup() {
+    _rc=$?
+    hssh 180 >/dev/null 2>&1 <<H || true
+export PATH=/opt/homebrew/bin:\$PATH
+tart stop $VM_RUN 2>/dev/null || true
+H
+    exit "$_rc"
+}
+trap cleanup EXIT
+# ---- leg 1: push — the host builds THIS commit ------------------------
+HEAD_SHA=$(git rev-parse HEAD)
+HAVE=$(hssh 60 <<H || true
+cd \$HOME/$REPO 2>/dev/null || exit 0
+git rev-parse -q --verify refs/heads/$BRANCH 2>/dev/null || true
+H
+)
+if [ "$HAVE" != "$HEAD_SHA" ]; then
+    # A push cannot update the branch the remote has checked out, and the
+    # run before this one left it checked out. Detaching first is what
+    # makes a re-run work; it changes no commit and no file.
+    hssh 60 >/dev/null <<H || fail push "cannot detach $MAC:$REPO before the push"
+set -e
+cd \$HOME/$REPO
+if [ "\$(git rev-parse --abbrev-ref HEAD)" = "$BRANCH" ]; then
+    git checkout -q --detach
+fi
+H
+    # --force because this branch is a scratch mirror of whatever this tree
+    # is and never shared history: a local amend or rebase leaves the host's
+    # ref on a commit the new HEAD does not descend from, and a plain push
+    # would be rejected as a non-fast-forward for the rest of the branch's
+    # life.
+    git push --force "$MAC:$REPO" "HEAD:refs/heads/$BRANCH" >/dev/null 2>&1 ||
+        fail push "git push $MAC:$REPO HEAD:refs/heads/$BRANCH was refused"
+    PUSHED=yes
+fi
+hssh 60 >/dev/null <<H || fail push "the host could not check out $BRANCH"
+set -e
+cd \$HOME/$REPO
+git checkout -q $BRANCH
+git reset -q --hard $BRANCH
+H
+HOST_SHA=$(hssh 60 <<H
+cd \$HOME/$REPO && git rev-parse HEAD
+H
+)
+[ "$HOST_SHA" = "$HEAD_SHA" ] ||
+    fail push "the host is at $HOST_SHA, this tree is at $HEAD_SHA"
+ok push "$MAC:$REPO on $BRANCH at $(git rev-parse --short HEAD), pushed=$PUSHED"
+# ---- leg 2: build — the toolchain lives on the host --------------------
+# The unit suite runs HERE and not in the guest for the same reason: it
+# needs zig, the shadow SDK and the source tree, and the guest has none of
+# them. `make test` rather than a bare `deps/zig/zig build test` so the
+# mac-sdk shim is on PATH the way every other target gets it.
+BOUT=$(hssh 2400 <<H
+cd \$HOME/$REPO || { echo "RC_BUILD=90"; exit 0; }
+export PATH=\$HOME/$REPO/deps/mac-sdk/bin:/opt/homebrew/bin:\$PATH
+make build  >/tmp/mac-build.log 2>&1; echo "RC_BUILD=\$?"
+make check  >/tmp/mac-check.log 2>&1; echo "RC_CHECK=\$?"
+make test   >/tmp/mac-test.log  2>&1; echo "RC_TEST=\$?"
+H
+)
+for _step in BUILD CHECK TEST; do
+    _rc=$(printf '%s\n' "$BOUT" | sed -n "s/^RC_$_step=//p")
+    [ "$_rc" = "0" ] && continue
+    _log=$(printf '%s' "$_step" | tr 'A-Z' 'a-z')
+    # The verdict first and the reading under it, test/vm.sh's shape: a
+    # reader scrolling back finds the sentence that says what broke, not
+    # the tail of somebody else's stack trace.
+    echo "mac FAIL: build: make $_log on $MAC exited ${_rc:-<no answer>}"
+    hssh 60 <<H | sed 's/^/          /' || true
+tail -30 /tmp/mac-$_log.log 2>/dev/null || true
+H
+    exit 1
+done
+ok build "make build, check and test on $MAC"
+# ---- leg 3: vm — a pristine guest, cloned and booted -------------------
+VM_T0=$(now_ms)
+hssh 600 >/dev/null <<H || fail vm "could not clone and boot $VM_RUN on $MAC"
+export PATH=/opt/homebrew/bin:\$PATH
+tart list 2>/dev/null | awk '{print \$2}' | grep -qx $VM_BASE || {
+    echo "mac FAIL: vm: $MAC has no VM called $VM_BASE." >&2
+    echo "          Make it once by hand; the recipe is this script's header." >&2
+    exit 1; }
+tart stop $VM_RUN >/dev/null 2>&1 || true
+tart delete $VM_RUN >/dev/null 2>&1 || true
+tart clone $VM_BASE $VM_RUN || exit 1
+nohup tart run --no-graphics $VM_RUN >/tmp/$VM_RUN.log 2>&1 &
+sleep 1
+exit 0
+H
+# Polled on the HOST rather than one ssh per tick: a tick costs a whole
+# connection setup from here and the address usually arrives in seconds.
+GIP=$(hssh 240 <<H
+export PATH=/opt/homebrew/bin:\$PATH
+_i=0
+while [ \$_i -lt 60 ]; do
+    _ip=\$(tart ip $VM_RUN 2>/dev/null) && [ -n "\$_ip" ] && { echo "\$_ip"; exit 0; }
+    sleep 2; _i=\$((_i + 1))
+done
+exit 1
+H
+) || fail vm "$VM_RUN took no address within 120 s (host log: /tmp/$VM_RUN.log)"
+_i=0
+while :; do
+    # An `if` and not `gssh ... && break`: under `set -e` an AND-OR list
+    # that ends in a failing test is a failing command, so the first tick
+    # against a guest still booting would end the run.
+    if gssh 25 >/dev/null 2>&1 <<'G'
+true
+G
+    then break; fi
+    _i=$((_i + 1))
+    [ "$_i" -lt 40 ] || fail vm "$VM_RUN at $GIP never answered ssh within 120 s"
+    sleep 3
+done
+VM_MS=$(( $(now_ms) - VM_T0 ))
+ok vm "$VM_RUN cloned, booted and answering at $GIP in $((VM_MS / 1000))s"
+# ---- leg 4: install — the host's build, onto a bare Mac ----------------
+hssh 300 >/dev/null <<H || fail install "could not copy the build into $VM_RUN"
+set -e
+cd \$HOME/$REPO
+ssh -n $GUEST_SSH $GUSER@$GIP "mkdir -p ~/mux-e2e"
+scp -q $GUEST_SSH zig-out/bin/mux zig-out/bin/ptyclient test/os_oracle.sh $GUSER@$GIP:mux-e2e/
+H
+WANT_VER=$(hssh 60 <<H
+cd \$HOME/$REPO && ./zig-out/bin/mux --version
+H
+)
+GOT_VER=$(gssh 60 <<'G'
+./mux --version
+G
+)
+[ -n "$WANT_VER" ] && [ "$WANT_VER" = "$GOT_VER" ] ||
+    fail install "the guest answers '$GOT_VER', the host built '$WANT_VER'"
+BMODE=$(gssh 60 <<'G'
+. ./os_oracle.sh
+file_mode ./mux
+G
+)
+[ "$BMODE" = "755" ] ||
+    fail install "the copied binary is mode $BMODE, want 755"
+ok install "a bare macOS runs the host's build and answers '$GOT_VER'"
+# ---- leg 5: daemon — no XDG_RUNTIME_DIR, so /tmp/mux-<uid> ------------
+# The pristine claim, asserted rather than assumed: this is what the
+# per-run clone buys, and a clone that silently carried a previous run's
+# daemon would make every leg below it a check on somebody else's state.
+PRE=$(gssh 60 <<'G'
+echo "uid=$(id -u)"
+echo "muxes=$(pgrep -x mux 2>/dev/null | wc -l | tr -d ' ')"
+[ -e /tmp/mux-$(id -u) ] && echo "rt=present" || echo "rt=absent"
+G
+)
+GUID=$(printf '%s\n' "$PRE" | sed -n 's/^uid=//p')
+printf '%s\n' "$PRE" | grep -qx 'muxes=0' ||
+    fail daemon "the freshly cloned guest already runs a mux: $PRE"
+printf '%s\n' "$PRE" | grep -qx 'rt=absent' ||
+    fail daemon "the freshly cloned guest already has /tmp/mux-$GUID: $PRE"
+[ -n "$GUID" ] || fail daemon "the guest would not say its uid"
+# MUX_SHELL_INTEGRATION=1 because the session leg below reads a real exit
+# code, and marks are opt-in (README). It also puts the daemon's shellint
+# shim directory inside the runtime directory this leg is about.
+gssh 120 >/dev/null <<'G' || fail daemon "mux d start -d refused on the guest"
+MUX_SHELL_INTEGRATION=1 ./mux d start -d
+G
+DPID=$(gssh 60 <<'G'
+pgrep -x mux | head -1
+G
+)
+[ -n "$DPID" ] || fail daemon "no mux process on the guest after mux d start -d"
+SOCK="/tmp/mux-$GUID/muxd.sock"
+gssh 60 >/dev/null <<G || fail daemon "daemon $DPID does not hold $SOCK"
+. ./os_oracle.sh
+pid_holds_unix_sock $DPID $SOCK
+G
+# canonicalised WITHOUT the oracle's real_path: that spelling is greadlink,
+# and a pristine macOS has no GNU coreutils on it — installing them to
+# answer one question would make the guest something other than the bare
+# Mac this gate is about. `cd -P` resolves a symlinked directory the same
+# way, and lsof (which is what pid_exe reads) reports the same canonical
+# form for the last component.
+DEXE=$(gssh 60 <<'G'
+. ./os_oracle.sh
+echo "is=$(pid_exe $(pgrep -x mux | head -1))"
+echo "want=$(cd -P -- ./ && pwd -P)/mux"
+G
+)
+_is=$(printf '%s\n' "$DEXE" | sed -n 's/^is=//p')
+_want=$(printf '%s\n' "$DEXE" | sed -n 's/^want=//p')
+[ -n "$_want" ] && [ "$_is" = "$_want" ] ||
+    fail daemon "daemon $DPID execs '$_is', not the installed '$_want'"
+RTMODE=$(gssh 60 <<G
+. ./os_oracle.sh
+file_mode /tmp/mux-$GUID
+G
+)
+[ "$RTMODE" = "700" ] ||
+    fail daemon "/tmp/mux-$GUID is mode $RTMODE, want 700"
+ok daemon "daemon $DPID holds $SOCK, a 700 directory the guest had no \$XDG_RUNTIME_DIR for"
+# ---- leg 6: attach — a real pty, a real session ------------------------
+# Before the session leg and not after it, though the brief lists them the
+# other way round: `mux a` attaches at 0x0 and JOINS, so it can only speak
+# to a session that already exists (README). The pty attach is what makes
+# one, which makes it the leg that has to run first.
+ATT=$(gssh 240 <<'G'
+./ptyclient --cols 80 --rows 24 --out /tmp/mac-attach.cap --err /tmp/mac-attach.err -- ./mux <<'PC'
+expect \x1b[?1049h 30000
+settle 900 20000
+send printf "JOURNEY-%s\\n" ok\n
+expect JOURNEY-ok 20000
+settle 600 15000
+send \x1cd
+waitexit 15000
+PC
+echo "PTYRC=$?"
+G
+) || fail attach "the guest would not run ptyclient"
+printf '%s\n' "$ATT" | grep -qx 'PTYRC=0' || {
+    echo "mac FAIL: attach: ptyclient did not reach the JOURNEY-ok snapshot: $ATT"
+    gssh 60 <<'G' | sed 's/^/          /' || true
+cat /tmp/mac-attach.err 2>/dev/null
+G
+    exit 1; }
+# The detach was a goodbye and not a tear: the session it typed into is
+# still on the daemon, holding what it painted.
+gssh 60 >/dev/null <<'G' || fail attach "the session did not survive the detach"
+./mux d dump | grep -q JOURNEY-ok
+G
+ok attach "a pty client typed into a session and detached, the grid kept it"
+# ---- leg 7: session — one shot through the agent surface ---------------
+# $$ expands in the session's OWN shell, so the pid it prints is a pid only
+# the guest's process table can confirm — which is the assert nothing on
+# this side can fake.
+AREPLY=$(gssh 90 <<'G'
+./mux a run --timeout 20000 'echo mac-$$'
+G
+) || fail session "mux a run did not answer on the guest"
+case "$AREPLY" in
+    *'"mechanism":"marks"'*) ;;
+    *) fail session "mux a run answered under no mechanism this leg can read: $AREPLY" ;;
+esac
+case "$AREPLY" in
+    *'"exit_code":0'*) ;;
+    *) fail session "mux a run reported no clean exit code: $AREPLY" ;;
+esac
+SPID=$(printf '%s\n' "$AREPLY" | sed -n 's/.*mac-\([0-9][0-9]*\).*/\1/p')
+[ -n "$SPID" ] || fail session "the reply carries no shell pid: $AREPLY"
+gssh 60 >/dev/null <<G || fail session "shell $SPID is not a child of daemon $DPID"
+. ./os_oracle.sh
+pid_children $DPID | grep -qx $SPID
+G
+ok session "mux a run answered under marks; shell $SPID is a child of daemon $DPID"
+# ---- leg 8: stop — and the runtime socket goes with it -----------------
+gssh 60 >/dev/null <<'G' || fail stop "mux d stop was refused on the guest"
+./mux d stop
+G
+END=$(gssh 60 <<G
+. ./os_oracle.sh
+_i=0
+while [ \$_i -lt 30 ]; do
+    pid_alive $DPID || break
+    sleep 0.1; _i=\$((_i + 1))
+done
+pid_alive $DPID && echo "alive=yes" || echo "alive=no"
+[ -e $SOCK ] && echo "sock=present" || echo "sock=gone"
+G
+)
+printf '%s\n' "$END" | grep -qx 'alive=no' ||
+    fail stop "daemon $DPID survives mux d stop by 3 s: $END"
+printf '%s\n' "$END" | grep -qx 'sock=gone' ||
+    fail stop "$SOCK outlives the daemon that bound it: $END"
+ok stop "daemon $DPID is gone within 3 s and took $SOCK with it"
+# ---- the pin ----------------------------------------------------------
+# A literal, test/vm.sh's style: adding a leg means editing this by hand,
+# so a leg that stops running cannot pass by not being counted.
+[ "$OK_COUNT" = "8" ] || {
+    echo "mac FAIL: $OK_COUNT legs ran, the pin says 8 —"
+    echo "         a leg was added (update the pin) or silently lost"
+    exit 1
+}
+echo "mac OK ($OK_COUNT legs on $VM_RUN, a pristine macOS on $MAC; boot ${VM_MS}ms)"