Module escalate 

Privilege escalation that works with or without a controlling terminal.

zlayer daemon-management verbs need root (system service unit, launchd plist, SCM registration). When invoked from a real terminal we re-exec under sudo -E; when there is no TTY (a GUI launcher, a desktop tray, an IDE task) a bare sudo dies with “a terminal is required”. This module bridges the gap by routing the headless case through the platform’s graphical escalator: sudo -A -E with an osascript askpass on macOS, polkit on Linux (pkexec, or sudo -A against a graphical askpass), and UAC on Windows (Start-Process -Verb RunAs). The macOS native auth dialog (osascript ... with administrator privileges) remains a fallback for when sudo is unavailable.

A graphical escalator is only attempted when something can actually render it: a real Aqua login session on macOS (launchctl print gui/<uid>), or an X11/Wayland display on Linux. Over SSH, in a container, or on a CI runner — no TTY and no GUI — a dialog has nowhere to draw, so we never pop one (it would hang). There we fall back to non-interactive sudo -n when sudo needs no password (passwordless sudoers or a warm timestamp), and otherwise fail fast with an actionable error rather than block on a prompt that can’t appear.

Caveat on macOS: a sudo spawned here does NOT inherit a timestamp a parent shell primed. With no controlling terminal the default timestamp_type=tty degrades to a per-parent-PID record, so our sudo -A (parented to this process) authenticates on its own and pops a dialog even if the calling installer just ran sudo -v. Callers that want a single prompt must do their privileged work under their own cached ticket, not lean on this path being a cache hit.

Two layers are exposed:

• root_command builds the program+args to run argv as root for a given interactivity, leaving the actual spawn (exec-replace, blocking, or async) to the caller.
• run_as_root is the blocking convenience: detect the TTY, build, spawn, and hand back the child’s ExitStatus.

Structs

RootCommand

Ready-to-spawn invocation that runs the target command as root.

Enums

EscalationError

Failure modes for root_command / run_as_root.

Functions

applescript_quote

Quote a string as an AppleScript string literal.

root_command

Build the invocation that runs argv as root.

run_as_root

Run argv as root and return the child’s exit status. Detects whether a terminal is attached and escalates accordingly. Unlike a sudo exec, this never replaces the current image — the graphical escalators spawn a fresh root process, so the caller gets the status back.

shell_quote

Quote a string for safe interpolation into a /bin/sh command line.