1.6.0: wrapper pipes the BEAM's stdout, breaking TTY detection (raw mode, ANSI, stdin reads) for interactive apps

[ryanwinchester]

Host

Host OS: macOS 26.5.2
Host CPU: aarch64 (Apple Silicon)

zig version: 0.16.0
elixir -v: Elixir 1.20.3 (compiled with Erlang/OTP 29)
Burrito: 1.6.0 (Hex)

Target

Same as host.

---

Found while packaging a terminal UI app (OTP 28+ raw mode). Related to #215 but independent of it: this reproduces with a fully working ERTS supplied via custom_erts (the workaround from #215). Both problems must be fixed for interactive/TUI apps to work in a Burrito binary.

Cause

The EPIPE fix from #225 makes the Unix wrapper spawn the BEAM with its stdout as a pipe, copied to the real stdout by a thread (src/erlang_launcher.zig, .stdout = .pipe + stdoutCopyThread):

The wrapper now pipes child stdout through itself via a copy thread; when the downstream pipe breaks (EPIPE on write), the copy thread kills the child process

The BEAM therefore sees a pipe on stdout even when the user runs the binary in a terminal. OTP's prim_tty requires both stdin and stdout to be TTYs, so the tty backend is disabled entirely.

Symptoms

Probe run from Application.start/2, binary launched in a real terminal, ERTS = local OTP 29 root via custom_erts (so #215 is out of the picture):

probe	stock 1.6.0 (stdout piped)	stdout inherited (local patch)
:io_ansi.enabled() (OTP 29)	false	true
:shell.start_interactive({:noshell, :raw})	{:error, :enotsup}	:ok
:io.columns() (after raw)	{:error, :enotsup}	{:ok, 80}
:io.get_chars(:standard_io, "", 1)	never returns — keyboard input is never delivered	{:ok, "x"}

Plain writes still pass through the copy thread, so an app can draw — it just can't detect the terminal, enter raw mode, query the size, or read a single keystroke. With stdout inherited, a full TUI (alternate screen, raw keyboard input, mouse reporting) works end to end in the Burrito binary.

Suggested fix

Only interpose the pipe when it's needed: check isatty(STDOUT_FILENO) in the wrapper.

• stdout is a tty (interactive session): inherit it. The EPIPE scenario from feat: Zig 0.16.0 compatibility #225 (app | head -5) cannot occur on a tty.
• stdout is not a tty (piped/redirected): keep the feat: Zig 0.16.0 compatibility #225 copy-thread behavior.

Windows already inherits stdout, so this would also re-unify behavior across platforms. Happy to test a patch.

[ryanwinchester]

PR with the proposed fix: #235 — verified on macOS 26 arm64 for all three paths (TTY/TUI end-to-end, redirected output, and the #225 EPIPE-into-head scenario).

[JamesLavin]

I hit a similar problem attempting to upgrade from 1.5.0 to 1.6.0. I was able to compile (after this one-word bugfix), but my sidecar no longer worked properly.

Claude says:

• 1.5.0: "execve (the launched process is the BEAM)"
• 1.6.0: "spawn-a-child + a stdout copy-thread that kills the child"

Posting Claude's analysis of my problem below.

--James

Burrito 1.6.0 launcher rewrite breaks long-lived / port-owning apps (sidecars)

TL;DR — Burrito 1.5.0 execves the BEAM on Unix: the process you launched becomes the
Erlang VM (same PID), owning the port and stdio directly. Burrito 1.6.0 rewrote the launcher to
spawn the BEAM as a child and interpose a stdout copy-thread that child.kill()s the BEAM on any
stdout write error. For a long-lived app whose stdout goes to a supervising host that may pause
reading (a Tauri sidecar, a service under a process manager), this new kill-switch terminates the
BEAM mid-run — the app exits on its own, and anything waiting for it (an HTTP readiness probe) never
sees it come up.

This document is a report for the Burrito maintainers, with the simplest candidate fixes.

---

Symptom

A desktop app embeds a Burrito-wrapped Elixir "sidecar" that listens on 127.0.0.1:8888. The host
(Tauri) spawns the sidecar and polls it for readiness. Intermittently:

• The sidecar boots fully (Endpoint running at 127.0.0.1:8888, "Application started"), then exits
  on its own shortly after.
• The host's readiness probe (GET http://localhost:8888/) gets connection-refused for the whole
  window; curl http://127.0.0.1:8888/… returns 000 (nothing listening).
• The host reports "background service failed to start."
• No orphaned BEAM processes remain (the BEAM really exited); host-initiated shutdowns are clean.

It is intermittent and load-dependent — the same binary sometimes starts fine — which points at a
timing/stdout-volume race, not a deterministic crash.

Environment

• Burrito: 1.6.0 (fails) vs 1.5.0 (works)
• Zig: 0.16.0 (1.6.0) vs 0.15.2 (1.5.0)
• OS: macOS / Linux (Unix execve path). Windows was always spawn-based (no execve), so it is
  not the regression — but the 1.6.0 copy-thread is Unix-only anyway.
• Use case: a long-lived, port-owning BEAM app launched and supervised by a parent process
  that reads the sidecar's stdout and sends it a SIGTERM to stop it.

Root cause

1.5.0 — execve (the launched process is the BEAM)

src/erlang_launcher.zig (1.5.0), Unix branch:

// Unix: replace ourselves with the BEAM — same PID, direct stdio, no intermediary.
return std.process.execve(allocator, final_args, &erl_env_map);

The BEAM inherits the launcher's stdin/stdout/stderr directly. A SIGTERM from the host goes
straight to the BEAM (OTP's default handler runs init:stop()); the BEAM owns the port; nothing can
kill it out from under itself.

1.6.0 — spawn-a-child + a stdout copy-thread that kills the child

src/erlang_launcher.zig (1.6.0), Unix branch:

child = try std.process.spawn(io, .{
    .argv = final_args,
    .environ_map = env_map,
    .stdout = .pipe,                    // <- stdout piped through us, not inherited
});
copy_thread = try std.Thread.spawn(.{}, stdoutCopyThread, .{io, &child});

const term = if (builtin.os.tag != .windows)
    child.wait(io) catch {
        copy_thread.?.join();
        std.process.exit(0);            // <- if we can't wait on the child, we just exit
    }
    else try child.wait(io);

// Copies child stdout to our stdout. On a write error it KILLS the BEAM.
fn stdoutCopyThread(io: Io, child: *std.process.Child) void {
    ...
    while (true) {
        const n = std.posix.read(child_stdout_fd, &buf) catch break;
        if (n == 0) break;
        const written = std.c.write(our_stdout_fd, buf[0..n].ptr, n);
        if (written < 0) {
            child.kill(io);             // <- SIGKILL the BEAM on any stdout write error (EPIPE)
            return;
        }
    }
}

The copy-thread's stated purpose (per its comment) is to detect EPIPE for CLI pipelines like
myapp cmd | head -5, and kill the BEAM so it doesn't hang flushing standard_io to a dead pipe.

That is reasonable for a short-lived CLI. It is wrong for a long-lived, host-supervised app:

• The host reads the sidecar's stdout, but during its readiness wait (or any GC pause) it may stop
  draining for a moment; combined with a BEAM that logs heavily at boot, the wrapper→host stdout pipe
  can error → the copy-thread SIGKILLs the BEAM mid-boot.
• Even absent EPIPE, the whole model is more fragile than execve: the BEAM is no longer the process
  the host spawned, its stdout is proxied through a thread that can terminate it, and a failed
  child.wait makes the wrapper exit(0) (reporting success while the child's fate is unclear).

Net effect: the sidecar exits on its own, the port goes dead, and the host's readiness probe never
succeeds.

Minimal reproduction

1. A Burrito-wrapped Elixir app that (a) runs long-lived (e.g. a Phoenix endpoint on a fixed port) and
   (b) writes a lot to stdout at boot.
2. Launch it from a parent that captures its stdout but does not continuously drain it while it
   polls the app's HTTP port for readiness.
3. Under 1.6.0 the app intermittently exits before readiness; under 1.5.0 it stays up.

Suggested fixes (simplest first)

(A) Restore execve on Unix. The one-line 1.5.0 behavior. The launched process is the BEAM again —
direct stdio, direct signals, no kill-switch. This is the most robust for embedded/sidecar/service
use and matches every host that assumes "the PID I spawned is the BEAM." If the EPIPE-for-CLI feature
must be retained, gate it (see D).

(B) Inherit stdio on Unix instead of piping through a killing thread. Keep the spawn-based flow
(so the wrapper can still run its build/ERTS setup and propagate the exit code), but use
.stdout = .inherit (as the Windows branch already does) — the child writes straight to the host, no
copy-thread, no kill-switch. Near-execve stdio semantics with the spawn-based structure 1.6.0 wants.

(C) Make the copy-thread non-fatal. On a stdout write error, stop copying and return — do NOT
child.kill(). The child's stdout then simply blocks under back-pressure (which the BEAM handles),
instead of the wrapper terminating a healthy VM. Smallest diff; only downside is it re-opens the
original CLI "hang on flush to a dead pipe" case that the kill was added for — acceptable if (A)/(B)
aren't taken, or combine with (D).

(D) Opt-in target qualifier, e.g. long_lived: true (or inherit_stdio: true / exec_replace: true) that selects execve/inherit-stdio on Unix and skips the copy-thread. Preserves the CLI EPIPE
behavior by default while giving sidecar/service users a supported, non-fatal path. Most flexible for
maintainers who want to keep 1.6.0's default.

Our preference is (A) or (D) — the sidecar contract is "the process you launched is the BEAM,
and nothing but the host may stop it."

Workaround (what we did)

Pin to the last execve release:

{:burrito, "~> 1.5.0"}   # Zig 0.15.2; launcher `execve`s the BEAM on Unix

We would like to move to 1.6.0 / Zig 0.16.0 once the launcher no longer spawns-and-kills a long-lived
BEAM (any of A–D above).

---

Filed from a project shipping a Burrito-wrapped Elixir sidecar for a Tauri desktop app on
macOS/Windows/Linux. Sibling report/bugfix: build-time regression in the same 1.6.0 wrapper rewrite (unconditional @embedFile("musl-runtime.so") breaks custom_erts Linux builds).