From b28ddb9210125d33b1b522db0733bc78cd1c353d Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Thu, 20 Aug 2026 17:34:45 +0200 Subject: [PATCH] (eed7309) Die quietly on a truncated pipe, and bump to 0.3.1 Rust sets SIGPIPE to SIG_IGN at startup, so a write to a closed pipe returned EPIPE and println panicked on it. `worklane ls | head -3` printed a panic and a backtrace on stderr instead of three lines, which reads as a real fault and is not what any other tool in a pipeline does. main now restores the default disposition before any output, the same six lines frig carries for the same reason. The cost is that a truncated pipe kills the process with signal 13, so a shell reports 141 rather than 101. That is what head and sort do, and it is now in the README next to the other exit codes. The tests drop the read end rather than racing head for it, over a listing large enough to exceed the 64 KiB a pipe holds, since a smaller one lands entirely in the buffer and proves nothing. A shell pipeline into head is covered too, and the exit codes for a real error and a usage mistake are pinned so the reset cannot quietly change them. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 1 + Cargo.lock | 3 +- Cargo.toml | 3 +- README.md | 13 ++++ src/main.rs | 21 ++++++ tests/broken_pipe.rs | 173 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 212 insertions(+), 2 deletions(-) create mode 100644 tests/broken_pipe.rs diff --git a/AGENTS.md b/AGENTS.md index 28ad6e4..f1c90a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,6 +37,7 @@ - Reset color with `\x1b[0m` after colored text - Bold uses `\x1b[1;35m` (magenta bold) - Always test color output works correctly in both terminal and pipe modes +- `quiet_broken_pipe()` runs first in `main`, restoring the default `SIGPIPE` disposition. A truncated pipe therefore kills the process with signal 13, which a shell reports as 141, instead of making `println!` panic. Do not wrap prints to handle write errors and do not reinstate `SIG_IGN`; the exit codes are documented in the README ### Color Guideline - UUID → red (31) diff --git a/Cargo.lock b/Cargo.lock index 9e25868..c155934 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1029,13 +1029,14 @@ dependencies = [ [[package]] name = "worklane" -version = "0.3.0" +version = "0.3.1" dependencies = [ "anyhow", "assert_cmd", "assert_fs", "chrono", "clap", + "libc", "tempfile", "uuid", ] diff --git a/Cargo.toml b/Cargo.toml index 928ff06..eb80556 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.3.0" +version = "0.3.1" edition = "2024" [dependencies] @@ -8,6 +8,7 @@ clap = { version = "4", features = ["derive"] } anyhow = "1" uuid = { version = "1", features = ["v4"] } chrono = { version = "0.4", features = ["serde"] } +libc = "0.2" [dev-dependencies] assert_cmd = "2" diff --git a/README.md b/README.md index ba3be74..9d90e67 100644 --- a/README.md +++ b/README.md @@ -11,3 +11,16 @@ Worklane is a local Kanban flow for agentic software development. | `worklane show ` | Shows ticket by UUID prefix (8+ chars) or title substring | | `worklane mv --status [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions | | `worklane comment ` | Adds a comment to a ticket by UUID or title | + +## Exit codes +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | An error, such as no matching ticket or an ambiguous search | +| 2 | A usage mistake, such as an unknown flag | +| 141 | Output was piped to a reader that stopped early, for example `worklane ls \| head -3` | + +141 is 128 + 13, the shell's way of reporting death by `SIGPIPE`. Worklane restores +the default signal disposition so a truncated pipe is quiet, the way `head` and +`sort` are, rather than printing a panic. A script using `set -o pipefail` will see +141 for a case that is not a failure, so guard for it there. diff --git a/src/main.rs b/src/main.rs index 7756165..5c2ec80 100644 --- a/src/main.rs +++ b/src/main.rs @@ -9,7 +9,28 @@ use command::*; use handlers::*; use util::*; +/// Die quietly when stdout is closed early, the way every other Unix tool does. +/// +/// Rust sets `SIGPIPE` to `SIG_IGN` at startup, which turns a closed pipe into an +/// io error that `println!` panics on. So `worklane ls | head -3` printed a panic +/// and a backtrace instead of three lines, which is both alarming and easy to +/// mistake for a real fault. Restoring the default handler makes `| head` behave. +/// +/// The cost is that a truncated pipe now kills the process with signal 13 rather +/// than returning a code, so `pipefail` sees 141 instead of 101. That is what +/// `head` and `sort` do, and it is recorded in the README. +fn quiet_broken_pipe() { + // SAFETY: setting a signal disposition to the default is always valid, and + // this runs before any thread is spawned. + unsafe { + libc::signal(libc::SIGPIPE, libc::SIG_DFL); + } +} + fn main() -> Result<()> { + // Before any output, so no write can beat it to a closed pipe. + quiet_broken_pipe(); + let cli = Cli::parse(); let start = std::env::current_dir()?; diff --git a/tests/broken_pipe.rs b/tests/broken_pipe.rs new file mode 100644 index 0000000..224dcf2 --- /dev/null +++ b/tests/broken_pipe.rs @@ -0,0 +1,173 @@ +use assert_fs::TempDir; +use assert_fs::fixture::{PathChild, PathCreateDir}; +use std::fs; +use std::os::unix::process::ExitStatusExt; +use std::process::{Command, Stdio}; + +const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane"); + +/// What a truncated pipe costs: the process dies by signal rather than returning a +/// code, so a shell reports 128 + 13. Asserted here so the README and the code stay +/// honest about what `pipefail` sees. +const SIGPIPE: i32 = 13; + +/// A pipe holds 64 KiB on Linux before a write blocks. Below that the whole listing +/// lands in the buffer, the writer never notices the reader is gone, and a test +/// proves nothing. Every ticket here is one `ls` row of roughly a hundred bytes. +const TICKETS: usize = 1200; + +fn setup_crowded_board(temp: &TempDir) -> std::path::PathBuf { + let worklane = temp.child(".worklane"); + worklane.create_dir_all().unwrap(); + + for dir in ["backlog", "committed", "reviewing", "done"] { + worklane.child(dir).create_dir_all().unwrap(); + } + + let backlog = worklane.path().join("backlog"); + for i in 0..TICKETS { + let id = format!("{:08x}-0000-4000-8000-000000000000", i); + let title = format!("A ticket with a title long enough to fill a row {}", i); + fs::write( + backlog.join(format!("{}_ticket-{}.md", id, i)), + format!( + "# {}\n\n## Metadata\n\n\ + - **ID**: {}\n\ + - **Owner**: someone with a name\n\ + - **Status**: backlog\n", + title, id + ), + ) + .unwrap(); + } + + temp.path().to_path_buf() +} + +fn panic_text(stderr: &str) -> bool { + stderr.contains("panicked") + || stderr.contains("failed printing to stdout") + || stderr.contains("Broken pipe") +} + +/// The reader closed before the writer finished: dropping the read end here is the +/// same thing `head` does when it has seen enough, without the timing luck. +fn run_with_stdout_dropped(dir: &std::path::Path, args: &[&str]) -> std::process::Output { + let mut child = Command::new(BIN_NAME) + .args(args) + .current_dir(dir) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .unwrap(); + + drop(child.stdout.take().unwrap()); + child.wait_with_output().unwrap() +} + +#[test] +fn ls_says_nothing_when_the_reader_goes_away() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + let output = run_with_stdout_dropped(&dir, &["ls", "backlog"]); + let stderr = String::from_utf8_lossy(&output.stderr); + + assert!(!panic_text(&stderr), "stderr was {stderr:?}"); + assert_ne!(output.status.code(), Some(101), "panicked instead of dying"); + assert_eq!( + output.status.signal(), + Some(SIGPIPE), + "expected death by SIGPIPE, got {:?}", + output.status + ); +} + +#[test] +fn show_says_nothing_when_the_reader_goes_away() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + // A ticket carrying more comments than a pipe will hold, since the comment list + // is the longest thing show prints and the last thing it reaches. + let comments = temp + .path() + .join(".worklane") + .join("comments") + .join("00000000-0000-4000-8000-000000000000"); + fs::create_dir_all(&comments).unwrap(); + for i in 0..800 { + fs::write( + comments.join(format!("2026082{}_120000_{:06}.md", i % 10, i)), + format!( + "**Comment**\nA comment body long enough to be worth buffering, number {}.\n\n\ + **Author**: someone\n**Time**: 2026-08-20 12:00:00\n", + i + ), + ) + .unwrap(); + } + + let output = run_with_stdout_dropped(&dir, &["show", "00000000-0000-4000"]); + let stderr = String::from_utf8_lossy(&output.stderr); + + assert!(!panic_text(&stderr), "stderr was {stderr:?}"); + assert_ne!(output.status.code(), Some(101), "panicked instead of dying"); + assert_eq!( + output.status.signal(), + Some(SIGPIPE), + "expected death by SIGPIPE, got {:?}", + output.status + ); +} + +/// The real invocation, through a shell into `head`, which is how this was found. +/// Whether the writer gets far enough to notice is up to the scheduler, so this +/// asserts only what must hold either way: `head` gets its lines and nothing +/// alarming reaches stderr. +#[test] +fn a_shell_pipeline_into_head_prints_lines_and_not_a_panic() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + let output = Command::new("sh") + .arg("-c") + .arg(format!("{} ls backlog | head -3", BIN_NAME)) + .current_dir(&dir) + .output() + .unwrap(); + + let stdout = String::from_utf8_lossy(&output.stdout); + let stderr = String::from_utf8_lossy(&output.stderr); + + assert_eq!(stdout.lines().count(), 3, "stdout was {stdout:?}"); + assert!(!panic_text(&stderr), "stderr was {stderr:?}"); +} + +/// The reset must not touch anything else: a real failure still returns its code. +#[test] +fn real_exit_codes_are_unchanged() { + let temp = TempDir::new().unwrap(); + let dir = setup_crowded_board(&temp); + + let ok = Command::new(BIN_NAME) + .args(["ls", "backlog"]) + .current_dir(&dir) + .output() + .unwrap(); + assert_eq!(ok.status.code(), Some(0)); + + let missing = Command::new(BIN_NAME) + .args(["show", "no-such-ticket-anywhere"]) + .current_dir(&dir) + .output() + .unwrap(); + assert_eq!(missing.status.code(), Some(1)); + + let misuse = Command::new(BIN_NAME) + .arg("--bogus") + .current_dir(&dir) + .output() + .unwrap(); + assert_eq!(misuse.status.code(), Some(2)); +}