stdio

Releases

1. ▸▾0.4.020 Jul 2026

   api: trim the sink hierarchy; symmetric adopt; conflict-semantics har…

   api: trim the sink hierarchy; symmetric adopt; conflict-semantics har…

   Open source →

   Additional notes

   Pre-publish consolidation: correctness fixes at the fd layer plus a final API finalization pass (breaking — 0.4.0 was never published).

   Correctness

   • stop() now restores the saved descriptors' original file-status flags. The mirror-to-original path sets O_NONBLOCK on the saved fds, and the flag lives on the open file description — shared with the fd 1/2 handed back on stop (and with the parent shell when the target is the tty) — so post-stop writes could EAGAIN, and the leak outlived the process.
   • maxLineBytes is now enforced on newline-terminated lines too: a long line arriving within one read chunk previously bypassed the cap entirely. Runs are split byte-exactly into cap-sized pieces (an exactly-cap-sized line stays whole); the README's split guarantee is now unconditionally true.
   • A reader-isolate death mid-session now restores fd 1/2 immediately (previously they stayed pointed at pipes nobody drained, and the app's next ~64 KiB of prints wedged the main isolate in a blocking write()). pause()/resume()/startProcess/adopt throw StateError on a degraded session; readerError + closed streams remain the signal.
   • Saved-fd mirror overflow drops are now counted on the new dedicated mirrorDroppedBytes counter (they were silent; they are a separate channel from the line counters, which they deliberately do not pollute).
   • droppedLines/droppedBytes now count exactly the lines missing from history: reader-side backpressure drops PLUS history-ring evictions (evictions were previously uncounted, making the documented totals wrong).
   • close() is no longer retried on EINTR (on Linux/macOS the fd is deallocated regardless, so the retry was a double-close that could hit an unrelated reallocated fd).
   • stop()'s drain-timeout path no longer closes fds a wedged-but-alive reader may still be blocked in read()/poll() on (deliberate bounded leak instead of fd-reuse byte theft), and the backstop Isolate.kill(immediate) is now issued only on that path — it can no longer race a healthy reader's cleanup.
   • startProcess()/adopt() after stop() now throw StateError instead of silently discarding the child's output.
   • A throwing classify callback no longer burns reader send credits (which permanently stalled the live feed after ~8 throws): the line is treated as unclassified and the first error is surfaced once on readerError.
   • open(2) is bound through VarArgs like the other variadic syscalls.
   • StdioRedirect.stop() releases the process-wide slot in a finally, so a (nearly impossible) restore failure can no longer wedge the package with no way to start a fresh session.

   Breaking API changes

   • Renamed the main class StdioCapture → Stdio, so the entry points read as Stdio.capture / Stdio.start / Stdio.redirectToFile (matching the package name).
   • Captured is now Captured<T> with a value field: Stdio.capture<T>() returns the body's result alongside the transcript, and stop() returns Future<Captured<void>>. Captured also gained droppedLines / droppedBytes (lines missing from lines).
   • Stdio.capture() accepts historyLines / maxLineBytes / mirrorToFile / classify, forwarded to start().
   • startProcess() returns CapturedProcess (the process plus a drained future that completes on full delivery); adopt() now returns CapturedProcess too (it was the bare drain future — ambiguous at the call site) and throws a clear StateError when the child's streams were already claimed (adopted twice / listened before adopt).
   • Renamed mirrorToSavedFds: → mirrorToOriginal: (introduced unpublished after 0.3.0), with real documentation and, new in this release, drop accounting (mirrorDroppedBytes) and end-to-end tests.
   • terminal is now typed StdoutTerminalSink — an IOSink with the terminal accessors and a concrete Stdout — and the redundant terminalStdout is gone (it was a second mutable-encoding handle to the same fd). terminalStderr (introduced unpublished after 0.3.0) stays, as the saved fd 2 counterpart. The abstract TerminalSink interface is gone too: it had no consumers and both implementations are final, so FdTerminalSink is now the documented base type (nullable-safe columns/rows; StdoutTerminalSink adds the throwing Stdout-contract terminalColumns/terminalLines view of the same data).
   • CapturedLine gained seq, a monotonic per-session sequence number stamped as each line enters the transcript — the robust history→stream stitch across awaits (the constructor now requires it).
   • CapturedLine.text strips one trailing \r (CRLF output reads clean); bytes stays byte-exact. StdoutTerminalSink.writeln honors lineTerminator (payload \ns still pass through untranslated).
   • StdioException moved to its own library and is now exported (the 0.4.0 pre-release changelog wrongly called the non-export deliberate: callers could neither catch it by type nor read readerError usefully).
   • New Stdio.anyActive static — advisory "is any capture/redirect holding fd 1/2" probe for coordination; the uncoordinated second start() still throws StateError.
   • pubspec: platforms: linux, macos declared explicitly (POSIX-only).

   Docs

   • The README and library summary are general-purpose — capturing native and child output is the headline; the terminal handle is one use among several.
   • Honest transcripts: stop()/capture() return the retained transcript (the last historyLines lines; see droppedLines) — the docs no longer claim everything is guaranteed present, and note that a throwing capture() body loses the transcript (use start()/stop() for post-mortems).
   • Documented: main-isolate-only entry points, the double-start StateError on every entry point, redirectToFile moving BOTH descriptors, the FIFO-mirror caveat, readerError carrying the stringified isolate error, the gap-free history→subscribe recipe (and seq stitching), and the sink flush/close no-op semantics on the sink type itself.
   • dart run stdio:verify is mentioned as the platform self-check.