fix(macos): grant the inherited terminals so sandboxed TUIs can enter raw mode

[pcontrerasp]

Fixes the macOS Seatbelt profile so interactive TUIs can enter raw mode by default. Reported as #419 and #391 — both are the same root cause.

Root cause

Seatbelt matches file-ioctl rules by device path. The generated profile allows file-ioctl on the literals /dev/tty, /dev/null, /dev/zero, /dev/random, /dev/urandom and /dev/dtracehelper — but a terminal is a pty slave (/dev/ttysNNN), which the /dev/tty alias does not cover. TIOCSETA / TIOCSETAW therefore return EPERM, and nothing under srt can leave canonical mode.

Both filed symptoms follow from that. A terminal stuck in canonical + ECHO echoes whatever arrives on its input back to the display, so the application's own protocol traffic becomes visible text: capability replies such as XTVERSION and DA1 (#419), and Kitty Keyboard Protocol encodings and SGR mouse reports on every keypress (#391). Input stays line-buffered in both.

allowPty: true already fixed this, but it is documented nowhere.

What changed

The default now grants file-ioctl and only file-ioctl on the terminals the child inherits on stdin/stdout/stderr, which is all raw mode needs.

allowPty	grant
unset (default) / false	ioctl on the inherited terminals only (default)
true	(allow pseudo-tty) + read/write/ioctl on every pty, for programs that allocate their own (tmux, script, node-pty)

false behaves identically to unset; there is no separate "no rules" state, since an inherited terminal a process never touches is harmless to make ioctl-able, and a distinct false only ever broke raw mode by surprise.

Why the terminals aren't detected while wrapping

wrapWithSandbox returns a command string; the caller chooses stdio afterwards. A terminal detected at wrap time is a guess about a decision not yet made — wrap under pipes and launch into a fresh pty and the rule is missing; wrap under terminal A and launch under B and the rule names the wrong device.

So WrapWithSandboxOptions gains inheritsStdio, an assertion by the caller that it spawns with this process's stdio inherited. Only that triggers resolution. The CLI passes it; library consumers opt in.

Paths are re-validated against /^\/dev\/ttys[0-9]+$/ at the profile seam rather than trusted, since inheritedTtys is an exported parameter whose value reaches a (literal ...) rule.

Resolving the devices

Node exposes no ttyname(3), and fs.realpathSync('/dev/fd/0') returns /dev/fd/0 on macOS rather than the device. Devices are resolved by matching each tty descriptor's rdev against the /dev/ttys* entries. Every failure path logs — a silent one reproduces exactly the bug this fixes: no rule, no error, no raw mode.

Tests

test/sandbox/macos-pty-default.test.ts covers profile generation, the resolver, and end-to-end Seatbelt behaviour. Three Python helpers make the e2e cases real rather than approximate:

• pty-ctty.py — gives the child a pty that is genuinely its controlling terminal
• pty-split.py — stdin on one pty, stdout/stderr on another; the only way to exercise the multi-device path
• pty-kkp.py — the KKP escape sequences leak as literal text through sandbox-exec PTY layer on macOS #391 repro, gated on a readiness marker so a child that dies at startup fails loudly instead of passing vacuously

A hasDeps guard test prevents the Seatbelt-behaviour suite from silently degrading to string assertions if the helpers go missing.

Docs

README gains allowPty documentation (its absence is arguably the whole of #419) and a troubleshooting entry for the escape-sequence symptom. Also corrects the violation-monitoring predicate: sandbox-exec execs into the target, so violations are attributed to the child and a predicate on the sandbox-exec process name matches nothing.

Scope

macOS only. The Linux (seccomp/Landlock) and Windows paths are untouched — this is a Seatbelt profile bug and does not exist there.