ac7f24d4

docs: step 3 plan for the Darwin arm, and the hardware findings amendment to the spec

a73x 2026-09-03 15:58

Commit message

docs: step 3 plan for the Darwin arm, and the hardware findings amendment to the spec

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

@@ @@ -0,0 +1,693 @@ @@
+# macOS Port, Step 3: the Darwin Arm — Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** `mux` builds, passes its unit suite and serves a real session on an Apple Silicon Mac, from the same tree that ships the Linux binary.
+**Architecture:** Two new child files, `src/os/server_os_macos.zig` and `src/os/client_os_macos.zig`, fill the `.macos` arm of the two contract roots that step 2 left as a compile error. `sockpath.runtimeDir` gains its Darwin spelling. A shadow-SDK shim under `deps/` works around the one toolchain defect found on hardware (below), the Makefile learns it is on Darwin, the shell oracle grows a `Darwin` arm, and `test/mac.sh` drives the Mac over ssh the way `test/vm.sh` drives the VM.
+**Tech Stack:** Zig 0.15.2 (vendored, `deps/zig/zig` on BOTH boxes), `@cImport` of `util.h` / `sys/un.h` / `sys/sysctl.h` for the libc calls `std.c` does not declare on Darwin, POSIX sh + lsof/ps/stat(1) BSD spellings in the harness.
+**Spec:** `docs/superpowers/specs/2026-09-03-macos-port-design.md` — sections "Step 3: the macOS arm", "Testing", "Deferred", plus the amendment "Hardware findings, 2026-09-03" that this plan's rulings come from.
+## Global Constraints
+- **The root is the contract, the arm is spellings only.** Every operation in `server_os_macos.zig` and `client_os_macos.zig` has the exact signature the root declares; no new `pub` name appears in an arm that the root does not call. Rules the root owns (server `peerCred` pid ≤ 0 → null, born-stale image, `openPtyPair` test-only) stay in the root.
+- **Folder rule 7 stands:** `std.os.linux`, `/proc`, `memfd`, `close_range`, `exit_group`, `so.peercred`, `so_peercred`, `iocsptlck`, `iocgptn`, `nosignal` appear under `src/os/` only. A Darwin arm that needs none of them still lives there.
+- **Rule 6 (`posix.fork(`) gains a second excepted file** and nothing else: `src/os/server_os_macos.zig`. The `except` field becomes a list.
+- **The Linux outcome does not change.** `make ci` green on Linux after every task; no Linux syscall, flag or message changes. A test that must differ by OS branches on `builtin.os.tag` inside the test, never by deleting the Linux assertion.
+- **Ask the OS about the OS.** Every Darwin test asserts against a real child, pty, socket or file; a Darwin oracle helper is graded by `oracle_selftest` exactly as the Linux one is.
+- **The hardware is `squirtle`** (Apple M1, macOS 26.6.2, Xcode 26.x, ssh key auth from this box; brew at `/opt/homebrew/bin`, NOT on the non-interactive ssh PATH). The repo is at `~/code/rad/mux` there, pushed from here with `git push squirtle:code/rad/mux <branch>` (the remote has `receive.denyCurrentBranch=updateInstead`, so push the branch and `git checkout` it there). It may be unreachable for stretches; a task whose verification needs it records `BLOCKED: squirtle unreachable` rather than skipping the check. Every ssh is `ssh -o BatchMode=yes squirtle '…'`, and every remote command that builds spells `export PATH=$HOME/code/rad/mux/deps/mac-sdk/bin:/opt/homebrew/bin:$PATH` first (Task 1 creates that dir).
+- **Toolchain defect, stated once:** Xcode 26.4+ ships a macOS SDK whose `libSystem.B.tbd` lists `arm64e-macos` and no `arm64-macos`; zig 0.15.2's Mach-O linker matches only the latter and every libSystem symbol goes undefined, for the BUILD RUNNER too, so `zig build` cannot even start (Codeberg ziglang/zig#31658; upstream fix is in 0.16, not in any 0.15 release, and ghostty pins 0.15). Measured 2026-09-03 on squirtle: native `zig build-exe h.zig -lc` fails; `-target aarch64-macos` (zig's bundled stub) links and runs; brew zig 0.16 links. The workaround is a shadow SDK: a directory of symlinks to the real SDK with `usr/lib/libSystem{,.B}.tbd` replaced by zig's own `lib/libc/darwin/libSystem.tbd`, reached through an `xcrun` shim on PATH that answers `--show-sdk-path` with the shadow. Proven: with the shim, the full `zig build` on squirtle compiles ghostty and its three C++ deps and stops at exactly the three step-3 `@compileError`s.
+- **Focused unit runs are `deps/zig/zig build test`** (whole suite); there is no `-Dtest-filter`, and a standalone `zig test FILE` does not link on either box.
+- **Commit subjects are `type: what changed`**, no scope; the types are `feat fix refactor test docs build chore`.
+---
+## Rulings carried from the hardware probes (2026-09-03)
+. **Build host: native on the Mac, over ssh.** Cross-compiling from Linux stays blocked by ghostty's `apple_sdk.addPaths` resolving the host libc; a native build needs only the shadow-SDK shim. The shim retires itself: it passes `xcrun` through untouched when the real SDK's stub lists `arm64-macos`.
+. **The pty master answers on Darwin.** `tcgetattr`, `TIOCGPGRP`, `TIOCSWINSZ` and `TIOCGWINSZ` on the master all returned 0 against a forked child with the slave as its controlling tty. The Linux arm's shape is reused; nothing reopens the slave by name.
+. **Runtime dir: `$XDG_RUNTIME_DIR` when set, else `/tmp/mux-<uid>`, created `0700`.** The spec's three candidates all overflow the 104-byte `sun_path` at the longest name mux creates, which is `<dir>/mux-agent-<pid>-<12 hex>/agent-<32-char session>.sock` = dir + 68 + pid digits. Measured on squirtle: `$TMPDIR` is 48 bytes (121 total), `~/Library/Caches/mux` 34 (107), `~/.local/state/mux/run` 36 (109); `/tmp/mux-501` is 12 (85). `/tmp` is `/private/tmp`, sticky and world-writable, so the per-uid subdirectory carries the privacy the way tmux's `/tmp/tmux-UID` does, and the same owner-and-mode check guards it. Honouring `XDG_RUNTIME_DIR` first is what keeps every isolated rig (`make e2e`, `soak`, hand rigs) isolated on both OSes from one line.
+. **Upgrade carrier on Darwin: `mkstemp` in `/tmp`, unlinked before return, mode `0600`.** Private by file mode rather than by anonymity; the unlink window is the microsecond between the two calls and the file is empty then.
+. **Darwin `sendNoSig` sets `SO_NOSIGPIPE` on the fd per call** before a plain `send`. No adopt-socket hook in the roots: one `setsockopt` on a socket that already has the option is a no-op, and the two accept sites stay outside the platform rows.
+. **`forkDetached`'s test asserts a NEW session, not a leader pid.** macOS `ps` prints no numeric session id; `ps -o sess=` prints an opaque token that is equal within a session on both OSes. The Linux-only `sid == $$` claim stays under `if (builtin.os.tag == .linux)`.
+---
+## File Structure
+| File | Responsibility |
+|---|---|
+| `deps/mac-sdk.sh` (new) | Builds `deps/mac-sdk/{sdk,bin/xcrun}` on a Darwin host; no-op when the real SDK is linkable; prints nothing on success. |
+| `deps/quic/build-deps.sh` | Already patched in the tree (uncommitted): repo zig first, `-march` only on x86_64, Darwin native fences. Task 1 commits it. |
+| `Makefile` | Darwin detection: `MUX_TARGET` default, PATH prefix for the shim, `mac-sdk` target, `mac` target for the journey. |
+| `.gitignore` | `deps/mac-sdk` |
+| `src/sockpath.zig` | Darwin `runtimeDir` arm + `ensureRuntimeDir`-style guard; the "unset" message names the right variable per OS. |
+| `src/os/server_os_macos.zig` (new) | Darwin spellings of the 14 server operations. |
+| `src/os/client_os_macos.zig` (new) | Darwin spellings of the 9 client operations. |
+| `src/os/server_os.zig`, `src/os/client_os.zig` | `.macos` import arm; two test bodies branch on OS. |
+| `build.zig` | rule 6 `except` list; nothing else. |
+| `test/os_oracle.sh` | `case "$(uname)"` Darwin arm for every helper; `now_ms`. |
+| `test/e2e_lib.sh`, six `e2e_*.sh`, `test/throughput.sh` | `date +%s%N` → `now_ms`. |
+| `test/mac.sh` (new) | The `make mac` journey against squirtle. |
+| `docs/decisions.md`, `README.md`, `CLAUDE.md` | The record. |
+---
+### Task 1: The shadow-SDK shim, the Makefile on Darwin, and the dep-script fix
+**Files:**
+- Create: `deps/mac-sdk.sh`
+- Modify: `Makefile` (top, `install`, new targets), `.gitignore`
+- Commit (already modified in tree): `deps/quic/build-deps.sh`
+**Interfaces:**
+- Produces: `deps/mac-sdk/bin/xcrun` on PATH makes `zig build` link on squirtle. Every later task's remote command exports that PATH.
+- [ ] **Step 1: Write `deps/mac-sdk.sh`**
+```sh
+#!/bin/sh
+# deps/mac-sdk.sh — a shadow macOS SDK for zig 0.15.2, built on a Darwin host.
+#
+# Xcode 26.4 and later ship a libSystem.B.tbd whose `targets:` line lists
+# arm64e-macos and no arm64-macos. zig 0.15.2's Mach-O linker matches the
+# bare arm64 slice only, so against that SDK every libSystem symbol is
+# undefined — for the build runner too, which is why `zig build` cannot
+# even start (ziglang/zig#31658 on Codeberg; fixed in 0.16, which ghostty's
+# pin cannot use). zig's own lib/libc/darwin/libSystem.tbd is what a
+# `-target aarch64-macos` build links against, and it works. This script
+# builds an SDK that is the real one in every path but usr/lib/libSystem*,
+# where zig's stub stands in, and an `xcrun` shim that answers
+# --show-sdk-path with it — zig finds the SDK by running `xcrun` off PATH
+# (std/zig/system/darwin.zig), and so does ghostty's apple_sdk helper.
+#
+# Self-retiring: when the real SDK's stub lists arm64-macos again, no shadow
+# is built and the shim, if a stale one is on PATH, passes straight through.
+# Idempotent and cheap: the marker check is the first thing it does.
+#
+#   ./deps/mac-sdk.sh            builds deps/mac-sdk/{sdk,bin/xcrun}
+set -eu
+[ "$(uname)" = Darwin ] || exit 0
+SELF="$(cd "$(dirname "$0")" && pwd)"
+OUT="$SELF/mac-sdk"
+ZIG_STUB="$SELF/zig/lib/libc/darwin/libSystem.tbd"
+REAL="$(/usr/bin/xcrun --sdk macosx --show-sdk-path)"
+if grep -m1 '^targets:' "$REAL/usr/lib/libSystem.B.tbd" | grep -q 'arm64-macos'; then
+    rm -rf "$OUT"      # the SDK is linkable again; leave nothing to shadow it
+    exit 0
+fi
+[ -f "$ZIG_STUB" ] || { echo "deps/mac-sdk: no zig stub at $ZIG_STUB (is deps/zig in place?)" >&2; exit 1; }
+# Marker: the shim exists AND points at this SDK. A new Xcode moves REAL.
+if [ -x "$OUT/bin/xcrun" ] && [ "$(readlink "$OUT/sdk/usr/include")" = "$REAL/usr/include" ]; then
+    exit 0
+fi
+rm -rf "$OUT"
+mkdir -p "$OUT/sdk/usr/lib" "$OUT/bin"
+for e in "$REAL"/*; do b=$(basename "$e"); [ "$b" = usr ] || ln -s "$e" "$OUT/sdk/$b"; done
+for e in "$REAL"/usr/*; do b=$(basename "$e"); [ "$b" = lib ] || ln -s "$e" "$OUT/sdk/usr/$b"; done
+for e in "$REAL"/usr/lib/*; do
+    b=$(basename "$e")
+    case "$b" in libSystem.tbd | libSystem.B.tbd) ;; *) ln -s "$e" "$OUT/sdk/usr/lib/$b" ;; esac
+done
+cp "$ZIG_STUB" "$OUT/sdk/usr/lib/libSystem.tbd"
+cp "$ZIG_STUB" "$OUT/sdk/usr/lib/libSystem.B.tbd"
+cat > "$OUT/bin/xcrun" <<EOF
+#!/bin/sh
+# Shim from deps/mac-sdk.sh: only --show-sdk-path is answered here.
+case "\$*" in
+    *--show-sdk-path*) [ -d "$OUT/sdk" ] && { echo "$OUT/sdk"; exit 0; } ;;
+esac
+exec /usr/bin/xcrun "\$@"
+EOF
+chmod +x "$OUT/bin/xcrun"
+echo "deps/mac-sdk: shadow SDK over $REAL (zig 0.15.2 cannot link the Xcode 26.4+ stub)" >&2
+```
+- [ ] **Step 2: Makefile — Darwin wiring**
+At the top, after the `ZIG ?=` line:
+```make
+# On a Mac the pinned zig cannot link against Xcode 26.4+'s SDK (see
+# deps/mac-sdk.sh). The shim dir goes FIRST on PATH for every recipe here,
+# and `mac-sdk` builds it; both are no-ops on Linux and on a Mac whose SDK
+# is linkable. MUX_TARGET follows the host: a Mac installs a Mac binary.
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Darwin)
+export PATH := $(CURDIR)/deps/mac-sdk/bin:/opt/homebrew/bin:$(PATH)
+MUX_TARGET ?= aarch64-macos
+endif
+MUX_TARGET ?= x86_64-linux-musl
+```
+Remove the existing `MUX_TARGET ?= x86_64-linux-musl` line further down (the `?=` above now owns it). Add:
+```make
+mac-sdk:
+	sh ./deps/mac-sdk.sh
+# The `make vm` of the macOS port: user journeys on the Mac, over ssh.
+mac: build
+	sh ./test/mac.sh
+```
+Make `build`, `check`, `test`, `install` depend on `mac-sdk`:
+```make
+build: mac-sdk
+	$(ZIG) build
+```
+(and the same `: mac-sdk` prerequisite on `check`, `test`, `install`, `throughput`). `.PHONY` gains `mac-sdk mac`.
+- [ ] **Step 3: `.gitignore`** — add `deps/mac-sdk` under the `deps/zig` block with a one-line comment (`# Shadow SDK from deps/mac-sdk.sh, Darwin only.`).
+- [ ] **Step 4: Verify on Linux**
+Run: `sh -n deps/mac-sdk.sh && make build >/dev/null && echo ok` → `ok`; `sh deps/mac-sdk.sh; echo rc=$?` → `rc=0` with no output (the `uname` gate). `make check` green.
+- [ ] **Step 5: Verify on squirtle** (skip with `BLOCKED` if unreachable)
+```sh
+git push squirtle:code/rad/mux HEAD:refs/heads/macos-step3 && ssh -o BatchMode=yes squirtle 'cd ~/code/rad/mux && git checkout -q macos-step3 && export PATH=$HOME/code/rad/mux/deps/mac-sdk/bin:/opt/homebrew/bin:$PATH && make mac-sdk && ls -l deps/mac-sdk/bin/xcrun && xcrun --show-sdk-path && rm -rf .zig-cache && make build 2>&1 | grep -c "no server platform arm\|no client platform arm\|no default runtime directory"'
+```
+Expected: the shim path printed as the SDK, and the final count is `3` — the three step-3 compile errors and NO `undefined symbol` line (`grep -c "undefined symbol"` → `0`).
+- [ ] **Step 6: Commit**
+```sh
+git add deps/mac-sdk.sh deps/quic/build-deps.sh Makefile .gitignore
+git commit -m "build: a Mac builds natively through a shadow SDK, and the dep script follows the host"
+```
+---
+### Task 2: `sockpath.runtimeDir` on Darwin
+**Files:**
+- Modify: `src/sockpath.zig` (`runtimeDir`, the "unset" message near line 37, tests)
+**Interfaces:**
+- Produces: `runtimeDir()` returns `?[]const u8` on Darwin exactly as on Linux; new `pub fn runtimeDirFrom(env: ?[]const u8, uid: std.posix.uid_t, buf: *[32]u8) ?[]const u8` (pure, tested on Linux) and `fn ensureOwnedDir(path: []const u8, uid: std.posix.uid_t) bool` (creates `0700` if missing; then `lstat`: directory, not a symlink, owner `uid`, mode `0700`).
+- [ ] **Step 1: Failing tests** (append to `src/sockpath.zig`)
+```zig
+test "runtimeDirFrom: the env var wins on every OS, and Darwin falls back to /tmp/mux-UID" {
+    var buf: [32]u8 = undefined;
+    try std.testing.expectEqualStrings("/run/user/7", runtimeDirFrom("/run/user/7", 501, &buf).?);
+    if (builtin.os.tag == .linux) {
+        try std.testing.expect(runtimeDirFrom(null, 501, &buf) == null);
+    } else {
+        try std.testing.expectEqualStrings("/tmp/mux-501", runtimeDirFrom(null, 501, &buf).?);
+    }
+}
+test "ensureOwnedDir: creates 0700, accepts its own creation, refuses a symlink and a group-readable dir" {
+    var tmp = testtmp.init();
+    defer tmp.deinit();
+    var b: [std.fs.max_path_bytes]u8 = undefined;
+    const uid = std.c.geteuid();
+    const fresh = try std.fmt.bufPrint(&b, "{s}/rt", .{tmp.path()});
+    try std.testing.expect(ensureOwnedDir(fresh, uid));
+    const st = try std.posix.fstatat(std.posix.AT.FDCWD, fresh, 0);
+    try std.testing.expectEqual(@as(u32, 0o700), @as(u32, @intCast(st.mode & 0o777)));
+    try std.testing.expect(ensureOwnedDir(fresh, uid)); // second call is a check, not a mkdir
+    var b2: [std.fs.max_path_bytes]u8 = undefined;
+    const loose = try std.fmt.bufPrint(&b2, "{s}/loose", .{tmp.path()});
+    try std.posix.mkdir(loose, 0o750);
+    try std.testing.expect(!ensureOwnedDir(loose, uid));
+    var b3: [std.fs.max_path_bytes]u8 = undefined;
+    const link = try std.fmt.bufPrint(&b3, "{s}/link", .{tmp.path()});
+    try std.posix.symlink(fresh, link);
+    try std.testing.expect(!ensureOwnedDir(link, uid));
+}
+```
+`testtmp` is already a test import of `sockpath` (check `build.zig`'s row; add `.test_imports = &.{"testtmp"}` if it is not).
+- [ ] **Step 2: Run** `deps/zig/zig build test 2>&1 | tail -5` → fails: `runtimeDirFrom` undefined.
+- [ ] **Step 3: Implement**
+```zig
+/// The directory the default daemon socket and every per-wall socket live
+/// in, or null. `$XDG_RUNTIME_DIR` wins on every OS, because that is how
+/// every isolated rig (make e2e, soak, a hand rig) keeps its sockets apart
+/// from the user's. Linux has NO fallback: a guess cannot make two binaries
+/// agree on one daemon, so the caller names it with --sock. Darwin falls
+/// back to /tmp/mux-<uid>, created 0700 and checked on every ask — the
+/// spec's three candidates ($TMPDIR, ~/Library/Caches, ~/.local/state) all
+/// overflow sun_path at the longest name mux creates (dir + 68 + pid
+/// digits against 103; measured 2026-09-03, docs/decisions.md), and /tmp
+/// is sticky and world-writable, so the per-uid directory is what carries
+/// the privacy, as tmux's /tmp/tmux-UID does.
+pub fn runtimeDir() ?[]const u8 {
+    const env = std.posix.getenv("XDG_RUNTIME_DIR");
+    if (builtin.os.tag == .linux) return env;
+    const uid = std.c.geteuid();
+    const dir = runtimeDirFrom(env, uid, &darwin_dir_buf) orelse return null;
+    if (env == null and !ensureOwnedDir(dir, uid)) return null;
+    return dir;
+}
+var darwin_dir_buf: [32]u8 = undefined;
+fn runtimeDirFrom(env: ?[]const u8, uid: std.posix.uid_t, buf: *[32]u8) ?[]const u8 {
+    if (env) |e| return e;
+    if (builtin.os.tag == .linux) return null;
+    return std.fmt.bufPrint(buf, "/tmp/mux-{d}", .{uid}) catch null;
+}
+/// True when PATH is a directory this uid owns with mode 0700 and no
+/// symlink in the last step — the check tmux makes of /tmp/tmux-UID, for
+/// the same reason: in a sticky world-writable /tmp, another uid can plant
+/// a symlink or a loose directory at our name before we get there, and a
+/// socket bound through either is theirs to connect to.
+fn ensureOwnedDir(path: []const u8, uid: std.posix.uid_t) bool {
+    std.posix.mkdir(path, 0o700) catch |e| if (e != error.PathAlreadyExists) return false;
+    const st = std.posix.fstatat(std.posix.AT.FDCWD, path, std.posix.AT.SYMLINK_NOFOLLOW) catch return false;
+    return std.posix.S.ISDIR(st.mode) and st.uid == uid and (st.mode & 0o777) == 0o700;
+}
+```
+Update the "unset" message (line ~37) so on Darwin it reads `"{s}: no runtime directory: XDG_RUNTIME_DIR is unset and /tmp/mux-<uid> is not a 0700 directory owned by you (name a socket with --sock)\n"`; keep the Linux text byte-for-byte.
+- [ ] **Step 4: Run** `deps/zig/zig build test 2>&1 | tail -3` → pass; `make check` green.
+- [ ] **Step 5: Commit** — `git commit -m "feat: the Darwin runtime dir is XDG_RUNTIME_DIR, else /tmp/mux-UID checked like tmux does"`
+---
+### Task 3: `server_os_macos.zig`
+**Files:**
+- Create: `src/os/server_os_macos.zig`
+- Modify: `src/os/server_os.zig` (import arm; the `forkDetached` test), `build.zig` (rule 6 `except` list)
+**Interfaces:**
+- Consumes: every `pub fn` the root calls through `impl`: `getpid peerCred sendNoSigNoWait sockType forkPty exitNow forkDetached closeFrom ptyMode ptyFgPgid setWinsize anonFd`. (`noteBootImage`/`selfImageStale` live in the root.)
+- [ ] **Step 1: The arm**
+```zig
+//! Darwin arm of `server_os`. Spellings only; the contract is in the root.
+//! Three behaviours differ from Linux on purpose and are recorded in
+//! docs/decisions.md (2026-09-03): `closeFrom` walks the fd table,
+//! `anonFd` is an unlinked mkstemp file, and `sendNoSigNoWait` sets
+//! SO_NOSIGPIPE on the fd per call because Darwin has no MSG_NOSIGNAL.
+const std = @import("std");
+const root = @import("server_os.zig");
+const c = @cImport({
+    @cInclude("util.h"); // forkpty
+    @cInclude("sys/ioctl.h");
+    @cInclude("sys/socket.h");
+    @cInclude("sys/un.h"); // LOCAL_PEERPID
+    @cInclude("unistd.h"); // getpeereid, getdtablesize
+    @cInclude("stdlib.h"); // mkstemp
+});
+pub fn getpid() std.posix.pid_t {
+    return std.c.getpid();
+}
+pub fn peerCred(fd: std.posix.socket_t) ?root.PeerCred {
+    var uid: c.uid_t = undefined;
+    var gid: c.gid_t = undefined;
+    if (c.getpeereid(fd, &uid, &gid) != 0) return null;
+    var pid: c.pid_t = 0;
+    var len: c.socklen_t = @sizeOf(c.pid_t);
+    // SOL_LOCAL is 0 on Darwin; LOCAL_PEERPID answers the peer's pid for a
+    // unix socket the way SO_PEERCRED's pid field does on Linux.
+    if (c.getsockopt(fd, 0, c.LOCAL_PEERPID, &pid, &len) != 0) return null;
+    return .{ .uid = uid, .pid = pid };
+}
+fn noSigPipe(fd: std.posix.socket_t) void {
+    const on: c_int = 1;
+    _ = c.setsockopt(fd, c.SOL_SOCKET, c.SO_NOSIGPIPE, &on, @sizeOf(c_int));
+}
+pub fn sendNoSigNoWait(fd: std.posix.socket_t, bytes: []const u8) std.posix.SendError!usize {
+    noSigPipe(fd);
+    return std.posix.send(fd, bytes, std.posix.MSG.DONTWAIT);
+}
+pub fn sockType(fd: std.posix.fd_t) error{NotASocket}!u32 {
+    var t: c_int = undefined;
+    var len: c.socklen_t = @sizeOf(c_int);
+    if (c.getsockopt(fd, c.SOL_SOCKET, c.SO_TYPE, &t, &len) != 0) return error.NotASocket;
+    return @intCast(t);
+}
+pub fn forkPty(ws: root.Winsize) error{ForkPtyFailed}!root.ForkedPty {
+    var master: c_int = undefined;
+    var cws: c.struct_winsize = .{ .ws_row = ws.row, .ws_col = ws.col, .ws_xpixel = 0, .ws_ypixel = 0 };
+    const pid = c.forkpty(&master, null, null, &cws);
+    if (pid < 0) return error.ForkPtyFailed;
+    return .{ .pid = pid, .master = master };
+}
+pub fn exitNow(code: u8) noreturn {
+    std.c._exit(code);
+}
+pub fn forkDetached(
+    exe: [*:0]const u8,
+    argv: [*:null]const ?[*:0]const u8,
+    stdin_fd: std.posix.fd_t,
+    out_fd: std.posix.fd_t,
+) error{ForkFailed}!std.posix.pid_t {
+    const pid = std.posix.fork() catch return error.ForkFailed;
+    if (pid != 0) return pid;
+    _ = std.c.setsid();
+    std.posix.dup2(stdin_fd, std.posix.STDIN_FILENO) catch exitNow(127);
+    std.posix.dup2(out_fd, std.posix.STDOUT_FILENO) catch exitNow(127);
+    std.posix.dup2(out_fd, std.posix.STDERR_FILENO) catch exitNow(127);
+    std.posix.execveZ(exe, argv, std.c.environ) catch exitNow(127);
+    unreachable;
+}
+pub fn closeFrom(first: std.posix.fd_t) void {
+    // No close_range on Darwin: one close per slot up to the table size,
+    // which is thousands of cheap EBADFs once per session start. Between
+    // fork and exec, so nothing else is opening fds underneath the walk.
+    var fd: std.posix.fd_t = first;
+    const top: std.posix.fd_t = c.getdtablesize();
+    while (fd < top) : (fd += 1) _ = std.c.close(fd);
+}
+pub fn ptyMode(master: std.posix.fd_t) std.posix.TermiosGetError!root.PtyMode {
+    // Measured 2026-09-03: Darwin's master answers tcgetattr for the slave's
+    // line discipline, so this is the Linux shape and not a reopen by name.
+    const t = try std.posix.tcgetattr(master);
+    return .{ .icanon = t.lflag.ICANON, .echo = t.lflag.ECHO };
+}
+pub fn ptyFgPgid(master: std.posix.fd_t) error{IoctlFailed}!std.posix.pid_t {
+    var pgid: c.pid_t = 0;
+    if (c.ioctl(master, c.TIOCGPGRP, &pgid) < 0) return error.IoctlFailed;
+    return @intCast(pgid);
+}
+pub fn setWinsize(master: std.posix.fd_t, ws: root.Winsize) error{IoctlFailed}!void {
+    var cws: c.struct_winsize = .{ .ws_row = ws.row, .ws_col = ws.col, .ws_xpixel = 0, .ws_ypixel = 0 };
+    if (c.ioctl(master, c.TIOCSWINSZ, &cws) < 0) return error.IoctlFailed;
+}
+pub fn anonFd(name: [*:0]const u8) error{CarrierFailed}!std.posix.fd_t {
+    // No memfd on Darwin. A 0600 file this uid creates and unlinks before
+    // anyone could open it by name is private by mode where memfd is
+    // private by having no name; the window is the two calls below, on an
+    // empty file. /tmp rather than the runtime dir because this file
+    // imports nothing of ours and must not learn the socket directory.
+    var tmpl: [64]u8 = undefined;
+    const t = std.fmt.bufPrintZ(&tmpl, "/tmp/mux-{s}-XXXXXX", .{std.mem.span(name)}) catch return error.CarrierFailed;
+    const fd = c.mkstemp(t.ptr);
+    if (fd < 0) return error.CarrierFailed;
+    std.posix.unlink(std.mem.sliceTo(t, 0)) catch {
+        std.posix.close(fd);
+        return error.CarrierFailed;
+    };
+    // mkstemp opens O_CLOEXEC on modern Darwin; the candidate must inherit it.
+    const flags = std.c.fcntl(fd, std.posix.F.GETFD, @as(c_int, 0));
+    _ = std.c.fcntl(fd, std.posix.F.SETFD, flags & ~@as(c_int, std.posix.FD_CLOEXEC));
+    return fd;
+}
+```
+- [ ] **Step 2: Root import arm** in `src/os/server_os.zig`:
+```zig
+pub const impl = switch (builtin.os.tag) {
+    .linux => @import("server_os_linux.zig"),
+    .macos => @import("server_os_macos.zig"),
+    else => @compileError("mux has no server platform arm for " ++ @tagName(builtin.os.tag)),
+};
+```
+- [ ] **Step 3: The `forkDetached` test** — replace its script and assertions:
+```zig
+    // `sess` is the one column both ps's print: the numeric sid on procps
+    // (== the leader's pid) and an opaque token on Darwin, equal within a
+    // session on both. A new session is the claim; the leader pid is a
+    // Linux-only strengthening.
+    const argv = [_:null]?[*:0]const u8{ "/bin/sh", "-c", "ps -o sess= -p $$ | tr -d ' '; ps -o sess= -p $PPID | tr -d ' '; echo $$" };
+    …
+    const sess = lines.next() orelse return error.NoOutput;
+    const parent_sess = lines.next() orelse return error.NoOutput;
+    const shpid = lines.next() orelse return error.NoOutput;
+    try std.testing.expect(!std.mem.eql(u8, sess, parent_sess));
+    if (builtin.os.tag == .linux) try std.testing.expectEqualStrings(shpid, sess);
+    try std.testing.expectEqual(pid, try std.fmt.parseInt(std.posix.pid_t, shpid, 10));
+```
+Bump `buf` to `[128]u8`.
+- [ ] **Step 4: Rule 6 in `build.zig`** — `except: ?[]const u8` → `except: []const []const u8 = &.{}`; the check at line ~457 becomes a loop (`for (ban.except) |ex| if (std.mem.eql(u8, path, ex)) { skip = true; }`); rule 6's entry: `.except = &.{ "src/os/server_os_linux.zig", "src/os/server_os_macos.zig" }`. Update the rule's `why` with one sentence: "one fork per OS arm, and the arm's file is named here so a third file that forks is caught".
+- [ ] **Step 5: Linux verify** — `deps/zig/zig build test 2>&1 | tail -3` pass; `make check` green (rule 6 now walks a list; `test/bans.sh` still plants its needle and reads the fatal).
+- [ ] **Step 6: squirtle verify** — push, then:
+```sh
+ssh -o BatchMode=yes squirtle 'cd ~/code/rad/mux && git checkout -q macos-step3 && export PATH=$HOME/code/rad/mux/deps/mac-sdk/bin:/opt/homebrew/bin:$PATH && make build 2>&1 | grep -c "no client platform arm"'
+```
+Expected `1` or more and zero `no server platform arm` lines. (The client arm is Task 4; the build still cannot link.)
+- [ ] **Step 7: Commit** — `git commit -m "feat: the daemon's Darwin arm"`
+---
+### Task 4: `client_os_macos.zig`
+**Files:**
+- Create: `src/os/client_os_macos.zig`
+- Modify: `src/os/client_os.zig` (import arm)
+- [ ] **Step 1: The arm**
+```zig
+//! Darwin arm of `client_os`. Spellings only; the contract is in the root.
+const std = @import("std");
+const root = @import("client_os.zig");
+const c = @cImport({
+    @cInclude("util.h"); // openpty (test-only through the root)
+    @cInclude("sys/ioctl.h");
+    @cInclude("sys/socket.h");
+    @cInclude("sys/un.h");
+    @cInclude("sys/sysctl.h"); // kinfo_proc for parentOf
+    @cInclude("unistd.h");
+});
+pub fn getpid() std.posix.pid_t {
+    return std.c.getpid();
+}
+pub fn peerCred(fd: std.posix.socket_t) ?root.PeerCred {
+    var uid: c.uid_t = undefined;
+    var gid: c.gid_t = undefined;
+    if (c.getpeereid(fd, &uid, &gid) != 0) return null;
+    var pid: c.pid_t = 0;
+    var len: c.socklen_t = @sizeOf(c.pid_t);
+    if (c.getsockopt(fd, 0, c.LOCAL_PEERPID, &pid, &len) != 0) return null;
+    return .{ .uid = uid, .pid = pid };
+}
+pub fn sendNoSig(fd: std.posix.socket_t, bytes: []const u8) std.posix.SendError!usize {
+    const on: c_int = 1;
+    _ = c.setsockopt(fd, c.SOL_SOCKET, c.SO_NOSIGPIPE, &on, @sizeOf(c_int));
+    return std.posix.send(fd, bytes, 0);
+}
+/// sysctl KERN_PROC_PID: the kernel's own record of the process, the
+/// Darwin answer to /proc/PID/stat. A pid the kernel no longer has is 0,
+/// as on Linux.
+pub fn parentOf(pid: std.posix.pid_t) std.posix.pid_t {
+    var mib = [_]c_int{ c.CTL_KERN, c.KERN_PROC, c.KERN_PROC_PID, pid };
+    var kp: c.struct_kinfo_proc = undefined;
+    var len: usize = @sizeOf(c.struct_kinfo_proc);
+    if (c.sysctl(&mib, mib.len, &kp, &len, null, 0) != 0 or len == 0) return 0;
+    return kp.kp_eproc.e_ppid;
+}
+pub fn geteuid() std.posix.uid_t {
+    return std.c.geteuid();
+}
+pub fn winSize(fd: std.posix.fd_t) ?std.posix.winsize {
+    var ws: std.posix.winsize = undefined;
+    if (c.ioctl(fd, c.TIOCGWINSZ, &ws) != 0) return null;
+    return ws;
+}
+pub fn setWinSize(fd: std.posix.fd_t, ws: std.posix.winsize) error{Unsupported}!void {
+    var w = ws;
+    if (c.ioctl(fd, c.TIOCSWINSZ, &w) != 0) return error.Unsupported;
+}
+pub fn openPtyPair() error{Unsupported}!root.PtyPair {
+    var master: c_int = undefined;
+    var slave: c_int = undefined;
+    if (c.openpty(&master, &slave, null, null, null) != 0) return error.Unsupported;
+    return .{ .master = master, .slave = slave };
+}
+```
+- [ ] **Step 2: Root import arm** — add `.macos => @import("client_os_macos.zig"),` beside the Linux line.
+- [ ] **Step 3: Linux verify** — `deps/zig/zig build test 2>&1 | tail -3`; `make check`.
+- [ ] **Step 4: squirtle verify — the first link**
+```sh
+ssh -o BatchMode=yes squirtle 'cd ~/code/rad/mux && git checkout -q macos-step3 && export PATH=$HOME/code/rad/mux/deps/mac-sdk/bin:/opt/homebrew/bin:$PATH && make build 2>&1 | tail -20; ls -l zig-out/bin/mux && ./zig-out/bin/mux --version'
+```
+Expected: a `mux` binary that prints its version. Whatever else fails here (a ghostty link line, a framework, a `std.c` name Darwin lacks) is THIS task's to fix, and each fix is one line in the report so Task 8 can record it.
+- [ ] **Step 5: Commit** — `git commit -m "feat: the client's Darwin arm, and mux links on a Mac"`
+---
+### Task 5: `zig build test` green on the Mac
+**Files:**
+- Modify: whatever the run names. Expected: `src/os/spawn.zig` (nothing — its Linux branch is gated), `src/client/client.zig:2397` (`readlink /dev/fd/2` is not a symlink on Darwin: the test wants the fd's TARGET; use `ls -l /dev/fd/2 | sed 's/.*-> //'` on Linux vs … simplest portable form is `test -w /dev/fd/2 && echo open > FILE` if the assertion is only "stderr was the pipe"; read the test and keep its claim), `src/sockpath.zig:150` (already gated), any test spelling `/proc` inside a `test` block.
+- [ ] **Step 1: Run on squirtle**
+```sh
+ssh -o BatchMode=yes squirtle 'cd ~/code/rad/mux && export PATH=$HOME/code/rad/mux/deps/mac-sdk/bin:/opt/homebrew/bin:$PATH && deps/zig/zig build test 2>&1 | grep -v "^\s*$" | tail -40'
+```
+- [ ] **Step 2: Fix each failure at its cause**, one commit per distinct cause when they are unrelated, keeping every Linux assertion. A unit test that cannot hold on Darwin because the OS has no such fact (not because the spelling differs) is gated on `builtin.os.tag == .linux` with a one-line comment saying which fact Darwin lacks.
+- [ ] **Step 3: Both suites green** — squirtle `zig build test` exit 0 (capture `$?` on the ssh, not the tail); Linux `make check` green.
+- [ ] **Step 4: Commit(s)** — `test: the unit suite holds on Darwin` (or one per cause).
+---
+### Task 6: The oracle's Darwin arm and the harness's GNU spellings
+**Files:**
+- Modify: `test/os_oracle.sh`, `test/e2e_lib.sh` (`now_ms`, `_os` marker → the first real `case`), `test/e2e_01_boot.sh`, `e2e_04_handoff.sh`, `e2e_10_agent.sh`, `e2e_11_select.sh`, `e2e_14_upgrade.sh`, `test/throughput.sh` (`date +%s%N` → `now_ms`), `test/e2e_03_side.sh`, `e2e_14_upgrade.sh`, `e2e_16_push.sh` (`readlink -f` → `real_path`).
+**Interfaces:**
+- Produces: `now_ms` (epoch milliseconds), `real_path PATH` (canonical path), and a Darwin arm for every existing helper. Group files call only names in `os_oracle.sh`.
+- [ ] **Step 1: The Darwin arm.** Restructure `os_oracle.sh` as ONE `case "$(uname)"` with the whole Linux block in the `*)` arm unchanged, and this `Darwin)` arm above it:
+```sh
+Darwin)
+    # lsof is the fd oracle (no /proc): -Fn prints one `n<target>` line per
+    # fd, -Ft its type, -a ANDs the filters. ps's BSD columns answer the
+    # rest. Each helper asks the kernel (lsof and ps both read it through
+    # libproc), never a daemon.
+    pid_alive() { kill -0 "$1" 2>/dev/null; }
+    pid_exe() { lsof -p "$1" -a -d txt -Fn 2>/dev/null | sed -n 's/^n//p' | head -1; }
+    pid_comm() { basename "$(ps -o comm= -p "$1" 2>/dev/null)"; }
+    pid_args() { ps -o args= -p "$1" 2>/dev/null; }
+    pid_children() { pgrep -P "$1" 2>/dev/null; }
+    pid_fd_count() { lsof -p "$1" -Ff 2>/dev/null | grep -c '^f[0-9]' || true; }
+    pid_fd_targets() { lsof -p "$1" -Fn 2>/dev/null | sed -n 's/^n//p'; }
+    pid_holds_fd_kind() {
+        case "$2" in
+            socket)    lsof -p "$1" -a -U -Ff 2>/dev/null | grep -c '^f[0-9]' || true ;;
+            carrier)   lsof -p "$1" -Fn 2>/dev/null | grep -c '^n/tmp/mux-.*XXXXXX\|^n/private/tmp/mux-' || true ;;
+            ptymaster) lsof -p "$1" -Fn 2>/dev/null | grep -c '^n/dev/ptmx' || true ;;
+            *) echo "pid_holds_fd_kind: no such fd kind '$2'" >&2; return 1 ;;
+        esac
+    }
+    pid_holds_unix_sock() { lsof -p "$1" -a -U -Fn 2>/dev/null | grep -qx "n$2"; }
+    pid_rss_kb() { ps -o rss= -p "$1" 2>/dev/null | tr -d ' ' || echo 0; }
+    udp_local_bound() { lsof -iUDP -P -n -Fn 2>/dev/null | grep -q "^n.*:$(printf '%d' "0x${1##*:}")$"; }
+    udp_table() { lsof -iUDP -P -n 2>/dev/null; }
+    file_mode() { stat -f %Lp "$1"; }
+    file_size() { stat -f %z "$1"; }
+    sha256_of() { shasum -a 256 "$1" | cut -d' ' -f1; }
+    real_path() { python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$1"; }
+    now_ms() { python3 -c 'import time; print(int(time.time()*1000))'; }
+    ;;
+```
+and in the Linux arm add `real_path() { readlink -f "$1"; }` and `now_ms() { echo $(( $(date +%s%N) / 1000000 )); }`. The `udp_local_bound` Linux helper takes the hex form; the Darwin one is handed the same argument and converts. Read the two callers in `e2e_lib.sh` before settling the argument shape — the group file must not know which OS it is on.
+The unlinked carrier: lsof prints an unlinked file's last path; verify the exact spelling in Task 6 Step 4 on the Mac and fix the pattern to what it prints.
+- [ ] **Step 2: `now_ms` and `real_path` in the group files** — replace each `date +%s%N` arithmetic and each `readlink -f` with the helper. Keep the Linux output identical (ms, not ns — adjust the arithmetic at each site).
+- [ ] **Step 3: Linux gate** — `make check` (bans.sh, `sh -n` on every script) and `E2E_ONLY=01_boot make e2e`, `E2E_ONLY=14_upgrade make e2e`, `E2E_ONLY=03_side make e2e` green; then the whole `make e2e` once.
+- [ ] **Step 4: Darwin oracle self-test on squirtle**
+```sh
+ssh -o BatchMode=yes squirtle 'cd ~/code/rad/mux && export PATH=/opt/homebrew/bin:$PATH && brew list coreutils >/dev/null 2>&1 || brew install coreutils; sh -c ". test/os_oracle.sh; . test/e2e_lib.sh 2>/dev/null; OUT=/tmp/oracle TIME_SCALE=1 oracle_selftest && echo ORACLE_OK"'
+```
+(`oracle_selftest` needs `defer_kill`, `wait_until`, `OUT`; if sourcing the lib whole is not possible without its argv, extract the self-test into `test/oracle_selftest.sh` that both `e2e_lib.sh` and this call source — a refactor, not a second copy.) Expected `ORACLE_OK`. `gtimeout` comes from coreutils; the existing `timeout` fallback covers it.
+- [ ] **Step 5: Commit** — `test: the OS oracle answers on Darwin, and the harness spells time and paths through it`
+---
+### Task 7: `test/mac.sh` — the `make mac` journey
+**Files:**
+- Create: `test/mac.sh`
+- Modify: `Makefile` (`mac` target from Task 1 already points here)
+**Interfaces:**
+- Consumes: `MUX_MAC` (default `squirtle`), the repo at `~/code/rad/mux` on the box, `deps/mac-sdk/bin` on PATH there.
+- [ ] **Step 1: The script**, shaped like `test/vm.sh` (same header contract: real box, every claim asserted by a separate ssh through the Darwin oracle, `set -eu`, BatchMode). Legs, each a named step with its own failure line:
+. `push` — `git push "$MAC:code/rad/mux" HEAD:refs/heads/mac-journey` then remote `git checkout -q mac-journey`.
+. `build` — remote `make build` and `make check`, rc captured.
+. `unit` — remote `deps/zig/zig build test`, rc captured.
+. `daemon` — remote, under `XDG_RUNTIME_DIR=$(mktemp -d /tmp/muxj.XXXXXX)` exported for every later leg: `zig-out/bin/mux d start -d`; assert via `pid_holds_unix_sock DPID $XDG_RUNTIME_DIR/muxd.sock` from the oracle, and `pid_exe DPID` equals `real_path zig-out/bin/mux`.
+. `session` — `zig-out/bin/mux a run --sock … 'echo mac-$$'`-style (use whichever `mux a` verb the README documents for a one-shot command) and read the pid back off the grid; assert the pid is a child of the daemon via `pid_children`.
+. `attach` — `zig-out/bin/ptyclient` drives `mux --sock …` on a real pty, types `printf JOURNEY-%s\\n ok`, waits for `JOURNEY-ok` in the snapshot (the e2e lib has the wait; mirror its shape), detaches with the chord.
+. `stop` — `mux d stop`; assert `pid_alive DPID` false within 3 s, socket path gone.
+. Cleanup trap: `mux d stop` on the rig socket if still alive; `rm -rf` the rig dir.
+- [ ] **Step 2: Run it** — `make mac` from this box; every leg prints its name and `ok`; exit 0.
+- [ ] **Step 3: Commit** — `test: make mac drives the Mac over ssh the way make vm drives the VM`
+---
+### Task 8: `make e2e` on the Mac — the verdict, and the record
+**Files:**
+- Modify: `docs/decisions.md`, `README.md`, `CLAUDE.md`
+- [ ] **Step 1: Run the e2e suite on squirtle** with the shim PATH and `brew`'s coreutils present:
+```sh
+ssh -o BatchMode=yes squirtle 'cd ~/code/rad/mux && export PATH=$HOME/code/rad/mux/deps/mac-sdk/bin:/opt/homebrew/bin:$PATH && make e2e 2>&1 | tail -40; echo rc=$?'
+```
+Then per group: `for g in $(ls test/e2e_[0-9]*_*.sh | sed 's,test/e2e_,,;s,\.sh,,'); do E2E_ONLY=$g make e2e >/tmp/e2e-$g.log 2>&1; echo "$g rc=$?"; done`. Fix a group only when the cause is a harness spelling (one more oracle helper, a BSD flag); a group that fails on a PRODUCT difference is recorded, not patched here.
+- [ ] **Step 2: `docs/decisions.md`** — one dated entry (2026-09-03, "macOS port step 3: the Darwin arm"), plain sentences: the Xcode 26.4 stub finding with the measurements from the Global Constraints; the pty-master probe result; the sun_path measurements and the `/tmp/mux-UID` ruling; the four deliberate Darwin differences (`closeFrom`, `anonFd`, `sendNoSig` per call, the `sess` test); every fix Task 5 made; the per-group e2e verdict table; what is NOT done (x86_64-macos, universal binary, cross-compile).
+- [ ] **Step 3: `README.md`** — a "macOS" section: aarch64 only, `make build` on the Mac needs Xcode CLT + cmake (brew), the shadow-SDK note in one paragraph, the runtime dir spelling, `make install` puts an aarch64 binary in `~/.local/bin`.
+- [ ] **Step 4: `CLAUDE.md`** — the toolchain block gains the Mac line (`deps/zig` on the Mac is the aarch64 0.15.2 tarball; `make mac-sdk`; `MUX_TARGET` follows the host); the layout table's `src/os/` row names the two `_macos` children; rule 6's excepted files are two; the invariants gain one line under the sun_path bullet about `/tmp/mux-UID`. Re-measure the `wc -l` figures the reading section quotes.
+- [ ] **Step 5: `make ci` on Linux**, then commit — `docs: the Darwin arm, its measurements and the Mac e2e verdict`
+---
+## 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.
+- **Placeholders:** none; every step has its code or its exact command. Task 5 is a discovery task by design and says what "fix" means.
+- **Type consistency:** `runtimeDirFrom(env, uid, buf)` (Task 2) is used only inside `sockpath.zig`; `now_ms`/`real_path` (Task 6) are the only new harness names and Task 7 uses `real_path`; the rule 6 `except` list type (Task 3) is the one `build.zig` change. Arm signatures were copied from the roots' `pub fn` lines on 2026-09-03.

docs/superpowers/specs/2026-09-03-macos-port-design.md

@@ @@ -293,3 +293,44 @@ worth doing and is not this work. @@
+**x86_64-macos and a universal binary** are one more target word each and
+are out of scope until someone has the hardware.
+## Hardware findings, 2026-09-03 (amendment after step 2)
+Measured on `squirtle` (Apple M1, macOS 26.6.2, Xcode 26.x) the day step 2
+merged. Each of these settles a question the sections above left open, and
+the step-3 plan (`docs/superpowers/plans/2026-09-03-macos-port-step3-darwin-arm.md`)
+carries them as rulings.
+- **Build host: native on the Mac, over ssh.** Not by choice among the
+  three options in "Deferred" but by finding: zig 0.15.2 cannot link a
+  NATIVE target against the SDK Xcode 26.4+ ships, because that SDK's
+  `libSystem.B.tbd` lists `arm64e-macos` and no `arm64-macos`, and the
+.15 Mach-O linker matches the bare slice only (ziglang/zig#31658 on
+  Codeberg; fixed upstream in 0.16, which ghostty's pin cannot take). The
+  build runner is a native link, so `zig build` cannot start. An explicit
+  `-target aarch64-macos` links against zig's bundled stub and runs, which
+  is the whole fix: a shadow SDK — the real one by symlink except
+  `usr/lib/libSystem{,.B}.tbd`, where zig's stub stands in — reached through
+  an `xcrun` shim on PATH. With it the full `zig build` compiled ghostty and
+  its three C++ dependencies natively and stopped at exactly the three
+  step-3 `@compileError`s. The QUIC stack built natively in about a minute
+  once the dep script's `native` word stopped assuming an x86 host.
+- **Probe 1, the pty master:** `tcgetattr`, `TIOCGPGRP`, `TIOCSWINSZ` and
+  `TIOCGWINSZ` on the master all answered 0 against a forked child holding
+  the slave as its controlling tty. The Linux arm's shape is reused; nothing
+  reopens the slave by name, and `openPty` need not record it.
+- **Probe 2, the socket directory:** the longest path mux creates is
+  `<dir>/mux-agent-<pid>-<12 hex>/agent-<session>.sock`, dir + 68 bytes +
+  pid digits at `session_name_max` 32, against 103 usable. `$TMPDIR` is 48
+  bytes on this box (121), `~/Library/Caches/mux` 34 (107),
+  `~/.local/state/mux/run` 36 (109): none of the three fits. `/tmp/mux-501`
+  is 12 (85). The Darwin spelling is therefore `$XDG_RUNTIME_DIR` when set
+  (every isolated rig sets it, on both OSes) and otherwise `/tmp/mux-<uid>`,
+  created `0700` and re-checked on every ask for owner, mode and no symlink
+  — tmux's `/tmp/tmux-UID` rule, for tmux's reason.
+- **The upgrade carrier** on Darwin is a `mkstemp` file in `/tmp`, mode
+  `0600`, unlinked before `anonFd` returns; "private by mode" replaces
+  "private by having no name" for the width of two syscalls on an empty file.
+- **Darwin `sendNoSig` sets `SO_NOSIGPIPE` per call.** No adopt-socket hook
+  is added to the roots: the option is idempotent and the accept sites stay
+  outside the platform rows.