Handle SIGPIPE properly for one-shot commands
+Overview
+braid list | head panics with “failed printing to stdout: Broken pipe”.
+Rust’s runtime sets SIGPIPE to ignore, so a write to a closed pipe returns
+EPIPE and println! panics. The standard Unix behavior is to die quietly
+on SIGPIPE (ls | head exits 141 with no message).
A global signal(SIGPIPE, SIG_DFL) in main is not the design: braid
+has long-lived paths (braid serve, braid mcp over stdio), and
+SIGPIPE disposition is process-wide, not per-fd. Rust ignores it so that
+writes surface as Err the code can handle.
Design: restore SIG_DFL only for an allowlist of read-only commands
+that print their result to stdout. An allowlist fails safe: a new command
+added later keeps Rust’s default (a panic on | head, the status quo)
+rather than silently gaining kill-on-EPIPE semantics.
Key audit finding (see Details): every data command syncs (open_skein
+dials and pulls), so “commands that don’t sync” is nearly empty. What makes
+the read commands safe is different: they all call session.shutdown()
+(repo.stop(), which flushes the cache) before their first stdout
+write. So the kill can only land after sync and cache flush are finished.
Rejected alternative: convert every println! in commands.rs (73 sites) to
+a helper that treats ErrorKind::BrokenPipe as a clean exit. More
+invasive, and a new println! reintroduces the bug (a clippy.toml
+disallowed-macros entry could guard that). Its one real advantage is
+that it also fixes Windows; see “Windows” under Details. Revisit if
+Windows | head matters.
Corrections to the DeepWiki answer this plan started from: main is
+async fn main() returning () (crates/braid/src/main.rs:294), not
+anyhow::Result<()>; mcp.rs uses stdout as its protocol channel; libc
+is in Cargo.lock (0.2.191) but is not yet a direct dependency of
+crates/braid.
Phase 1: tests first
+-
+
+
+
+
+
+
+
+
Phase 2: implement
+-
+
+
+
+
+
Phase 3: docs and verification
+-
+
+
+
+
+
+
+
+
+
Details
+Phase 1 audit (done)
+Every command except the config-only ones goes through
+Session::open → open_skein (ops.rs:256, skein.rs:73), which dials
+the server (connect, skein.rs:116) and pull()s (skein.rs:131). So
+list/show/ready/etc. all sync. The read commands then call
+session.shutdown() → repo.stop() (ops.rs:335, skein.rs:201) before
+printing (commands.rs list ~1138, show, ready, blocked,
+search, dep_list, dep_cycles, dep_tree, export ~945).
Classification:
+| Command + | +Opens sync? + | +Prints after shutdown? + | +SIG_DFL? + | +
|---|---|---|---|
list, show, ready, blocked, search, dep list/tree/cycles, export
+ |
+yes + | +yes + | +allow + | +
agents-info (no --install), secret, config
+ |
+no + | +n/a + | +allow + | +
agents-info --install
+ |
+no + | +writes a file + | +allow is harmless; keep out for simplicity + | +
create, update, close, reopen, defer, undefer, comment, delete, dep add/remove, import, init, rotate, sync
+ |
+yes + | +prints around push/confirm + | +exclude (mutating; SIGPIPE mid-write/push is the real risk) + | +
mcp, serve, ui
+ |
+yes, long-lived + | +stdout is a protocol channel (mcp) or one startup line (serve)
+ |
+exclude + | +
secret and config print many small lines; a kill partway through is
+harmless.
Why a kill after shutdown() is safe: cache writes go through samod’s
+storage, which writes atomically (temp file + rename, cache.rs:262-274),
+and the flush has completed by then. Network sockets are not a SIGPIPE
+source on the paths we ship: std sends with MSG_NOSIGNAL on Linux
+(library/std/src/sys/net/connection/socket/mod.rs:433) and mio sets
+SO_NOSIGPIPE on Apple targets (mio/src/sys/unix/net.rs:39). So the
+websocket/TCP sync path is already immune, and the real SIGPIPE exposure
+is stdout/stderr only. That is why a global reset would be survivable for
+serve, but the allowlist is still the right conservative default, and
+for mcp a silent kill on host disconnect is a behavior change.
Other writers and children
+ui.rs, serve.rs, and skein.rs only use eprintln! (plus one startup
+println! in serve). Panics on eprintln! to a closed stderr are a
+separate, unaddressed case. build.rs and tests run Command::new (npm,
+bash, tar); no production code spawns children, so no pipe interaction.
+xtask is a dev tool, out of scope.
Windows
+Windows is built, tested (ci.yml windows job), and released
+(release.yml x86_64-pc-windows-msvc, install.ps1). With the signal
+approach, Windows keeps the current panic on | head (accepted: the
+no-op is explicit). If Windows matters, the helper approach is the only
+one that covers it (BrokenPipe / ERROR_NO_DATA).
Third option: panic hook / catch_unwind
+Possible (a hook that matches “failed printing to stdout” and exits 141), +but it depends on matching panic message text, and the panic fires inside +tokio’s runtime context. Not recommended over either alternative.
+