Add a CI-checked uvloop and anyio-on-asyncio compatibility test run

Turn the event-loops.md compatibility claims into a verifiable contract: a
new tests/test_event_loops.py parametrized over the loop, an optional
event-loops dependency-group, and a dedicated CI job separate from the
main test matrix.

Author: ZelAnton

CHANGELOG.md

@@ -8,6 +8,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `Command.on_stdout_line(callback)` / `Command.on_stderr_line(callback)`: a
+  `Callable[[str], None]` invoked with every decoded line as it is produced —
+  the way to give the **synchronous** surface (`.output()`/`.run()`) live
+  progress observation during an otherwise-blocking call, without losing the
+  full capture. Also fires on the async verbs and on a streamed run
+  (`start()`/`astart()` + `stdout_lines()`/`output_events()`); at most one
+  handler per stream (a repeat call replaces the previous one); a raising
+  callback is reported via `sys.unraisablehook` rather than propagated or
+  breaking the run. Inert under `stdout("inherit")`/`stdout("null")` (resp.
+  `stderr(...)`) and, for `on_stdout_line` only, under `output_bytes()` (which
+  captures stdout raw, bypassing the line pump — stderr still goes through it,
+  so `on_stderr_line` still fires there). See
+  `docs/streaming.md#live-per-line-callbacks`.
 - A `benchmarks/` suite (`pytest-benchmark`, new `bench` dependency-group)
   measuring spawn+capture overhead against `subprocess`/`asyncio.subprocess`,
   `ProcessGroup` start/exit, line-streaming throughput, and `output_all`
@@ -34,6 +47,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   nested `outcome`, so it now mirrors `Outcome` fully — matching `code` and
   `exited_zero`, which were already exposed directly — instead of requiring
   `finished.outcome.timed_out` / `finished.outcome.signal`.
+- `Command.stdin_file(path)` — feed the child's stdin from a file, streamed in
+  chunks by the crate rather than read whole into a Python `bytes` object, for
+  large inputs (a `psql` dump, a `tar` archive, a multi-gigabyte log). Like
+  most other builder methods (`stdout_tee`/`stderr_tee` are the deliberate
+  exception), it does not touch the filesystem at build time — the path is
+  opened lazily at spawn, so a missing/unreadable file surfaces as the generic
+  `ProcessError` from the run/output verb, not `FileNotFoundError`. Reusable
+  across retries/re-runs, like `stdin_bytes`/`stdin_text`; the usual "last
+  stdin method wins" rule applies alongside `stdin_bytes()`/`stdin_text()`/
+  `keep_stdin_open()`.
+- `ProcessResult` and `BytesResult` gain `diagnostic: str | None` (stderr if it
+  carries text, otherwise stdout, otherwise `None` — the same preference order
+  as `NonZeroExit`/`Timeout`/`Signalled.diagnostic` on the exceptions) and
+  `outcome: Outcome` (the same value `RunProfile.outcome` and the checking-verb
+  exceptions expose). A result held as data (`output()`/`output_bytes()`
+  without `ensure_success()`) no longer requires re-deriving these by hand.
+  (An `output_contains_any` convenience was considered alongside these and
+  rejected: the underlying `processkit` crate has no such method, so it
+  wouldn't be parity with the crate or the exceptions like `diagnostic`/
+  `outcome` are — and it's a one-liner callers can already write themselves
+  via `combined`, e.g. `any(s in result.combined for s in needles)`.)
 
 ### Changed
 - `CliClient(default_env_fn=...)` now validates that every value in the

docs/README.md

@@ -46,6 +46,7 @@ handy before you ship: it collects every per-OS caveat in one place.
 | [Coming from subprocess](migrating.md) | Side-by-side translation of `subprocess` / `asyncio.subprocess` patterns, the exception mapping, and the whole-tree containment the stdlib can't give |
 | [Running commands](commands.md) | The `Command` builder end to end — args, env/sandboxing, stdin, stdout/stderr redirection, encodings, output caps, timeouts, privileges — and every consuming verb (`output`, `run`, `probe`, …) with its error semantics |
 | [Process groups](process-groups.md) | Kill-on-drop containment: creating groups, spawning, teardown, whole-tree signals, suspend/resume, member listing, resource limits, stats |
+| [Sandboxing untrusted tools](sandboxing.md) | The agent/LLM-tool recipe: locked-down env → bounded output → group resource limits → timeout → teardown, a checklist, and an honest threat model (what this does and does not protect against) |
 | [Streaming & interactive I/O](streaming.md) | `astart()` and the live `RunningProcess`: line streaming, interactive stdin, readiness probes (`wait_for_line` / `wait_for_port` / `wait_until`), per-run profiling |
 | [Pipelines](pipelines.md) | Shell-free command pipelines — chain with `.pipe()` or the pipe operator: wiring, pipefail attribution, chain timeouts, binary tails |
 | [Timeouts & cancellation](timeouts-and-cancellation.md) | How a deadline is *captured* vs when it raises, interrupting a blocked sync call (Ctrl+C), and asyncio cancellation that reaps the whole tree |

docs/commands.md

@@ -144,6 +144,24 @@ Command("sha256sum").stdin_bytes(b"\x00\x01\x02").run()
 The payload is written on a background task, so a large input can't deadlock
 against the child's own output; the pipe is closed afterward to signal EOF.
 
+For a large input already sitting in a file — a database dump piped into `psql`,
+an archive fed to `tar`, a multi-gigabyte log run through a filter — use
+`stdin_file(path)` instead of reading the file into Python `bytes` yourself. The
+file streams straight to the child's stdin in chunks, so it never has to fit in
+Python memory:
+
+```python
+Command("psql", ["mydb"]).stdin_file("dump.sql").run()
+Command("tar", ["-xf", "-"]).stdin_file("archive.tar").cwd("/tmp/extract").run()
+```
+
+`stdin_file()` doesn't touch the filesystem when you call it — the path is
+opened lazily when the command actually spawns, so a not-yet-existing path is
+not an error there. If the file turns out to be missing or unreadable once the
+command runs, that surfaces as a generic `ProcessError` from the run/output
+verb (not `FileNotFoundError`), since the child process has, by then, already
+spawned successfully.
+
 For a conversational, request/response exchange — write a line, read the answer,
 repeat — call `keep_stdin_open()` and drive the process through the streaming API
 instead. *Deeper: [Streaming & interactive I/O](streaming.md).*

docs/cookbook.md

@@ -93,6 +93,15 @@ out = Command("tr", ["a-z", "A-Z"]).stdin_text("hello\n").run()   # "HELLO"
 Command("sha256sum").stdin_bytes(b"\x00\x01\x02").run()
 ```
 
+## Feed a large file to stdin without loading it into memory
+
+```python
+# Streams straight from disk to the child — no full read into Python bytes,
+# so this works just as well for a multi-gigabyte dump/archive/log.
+Command("psql", ["mydb"]).stdin_file("dump.sql").run()
+Command("tar", ["-xf", "-"]).stdin_file("archive.tar").cwd("/tmp/extract").run()
+```
+
 ## Set the working directory and environment
 
 ```python
@@ -188,6 +197,30 @@ object is a deferred feature) — if you need the lines *in Python*, loop over
 `stdout_lines()` instead. See [Streaming](streaming.md#tee-output-to-a-file) for
 backpressure, the no-op conditions, and write-error isolation.
 
+## Get live progress from a synchronous run
+
+`stdout_lines()` / `output_events()` need an event loop; `on_stdout_line(callback)`
+/ `on_stderr_line(callback)` give the plain, **blocking** `.output()` / `.run()`
+call the same live view — `callback` fires on every decoded line as it streams
+in, not just once the run finishes:
+
+```python
+from processkit import Command
+
+result = (
+    Command("cargo", ["build", "--release"])
+    .on_stdout_line(lambda line: print("build:", line))
+    .output()
+)
+# capture is untouched — result.stdout still has the whole output.
+```
+
+Works the same on the async verbs and on a streamed run — one callback, every
+path. A raising callback never derails the run (it goes to
+`sys.unraisablehook` instead). See
+[Streaming](streaming.md#live-per-line-callbacks) for the no-op conditions and
+the one-handler-per-stream rule.
+
 ## Tear a standalone process down deterministically
 
 A `RunningProcess` is a context manager. Exiting the block kills the process —

docs/sandboxing.md

@@ -0,0 +1,181 @@
+# Sandboxing untrusted tools
+
+[‹ docs index](README.md)
+
+Agent/LLM frameworks routinely hand a model the ability to run a "tool" it
+picked itself, with arguments it generated itself — a shell command, a code
+interpreter, a scraper. That tool is, by construction, less trusted than code
+you wrote: it should never be able to outlive your process, exhaust the host,
+or run forever. This guide is not a new capability — it is a **composition** of
+pieces documented individually elsewhere: [Running commands](commands.md)
+(environment, output caps), [Process groups](process-groups.md) (whole-tree
+resource limits), and [Timeouts & cancellation](timeouts-and-cancellation.md)
+(deadlines). It ties them into one recipe, a checklist, and — most
+importantly — an honest statement of what this buys you and what it does not.
+
+- [The threat model](#the-threat-model)
+- [The recipe](#the-recipe)
+  - [1. Locked-down environment](#1-locked-down-environment)
+  - [2. Bounded output](#2-bounded-output)
+  - [3. Whole-tree resource limits](#3-whole-tree-resource-limits)
+  - [4. A timeout](#4-a-timeout)
+  - [5. Teardown](#5-teardown)
+- [Checklist: run an untrusted tool safely](#checklist-run-an-untrusted-tool-safely)
+- [Full example](#full-example)
+
+## The threat model
+
+Be precise about what a `ProcessGroup` sandbox is — and is not — before
+leaning on it for anything that matters.
+
+**processkit protects against:**
+
+- **Process-tree leakage.** Every process the tool spawns, and everything
+  *that* spawns, dies when the sandbox exits — enforced by the kernel
+  container (Job Object / cgroup v2 / process group), not a best-effort
+  signal to one pid. See [the no-orphan guarantee](process-groups.md#tearing-down).
+- **Resource exhaustion.** Whole-tree memory, process-count (fork bombs), and
+  CPU caps are enforced by the kernel (see
+  [Resource limits](process-groups.md#resource-limits-the-sandbox)); captured
+  output is bounded so a chatty or malicious child cannot grow the parent's
+  memory without limit (see
+  [Bounding captured output](commands.md#bounding-captured-output)).
+- **Runaway execution time.** A timeout kills the whole tree at a deadline —
+  see [Timeouts & cancellation](timeouts-and-cancellation.md).
+- **Ambient credential/environment leakage.** `env_clear()` /
+  `inherit_env([...])` starts the child from nothing rather than handing it
+  the parent's full environment, secrets included — see
+  [Environment and sandboxing](commands.md#environment-and-sandboxing). On
+  POSIX you can additionally drop privileges — see
+  [Privileges and spawn flags](commands.md#privileges-and-spawn-flags).
+
+**processkit does NOT protect against:**
+
+- **Filesystem access.** The tool can read and write anything the OS
+  permits its (possibly privilege-dropped) user to touch. processkit does not
+  chroot, bind-mount, or otherwise virtualize the filesystem.
+- **Network access.** No firewalling or network namespace is applied; a
+  sandboxed tool can still make outbound connections unless you restrict that
+  another way (a container, a network policy, an egress proxy).
+- **Syscall/namespace isolation.** This is not seccomp, and not a
+  PID/mount/user-namespace container. A Job Object, cgroup, or process group
+  bounds a *tree*'s lifetime and resource consumption — it does not restrict
+  *which* syscalls the tree may issue.
+- **Vetting the tool's behavior.** processkit does not sanitize, statically
+  analyze, or judge what the program does — it bounds the blast radius (time,
+  memory, CPU, process count, orphaned children), not the tool's actions
+  within those bounds.
+
+**In short:** this is *resource and lifetime* containment, not *security*
+isolation. If you need syscall, filesystem, or network isolation, pair
+processkit with an actual sandbox — a container, a VM, gVisor, a seccomp
+profile, a restricted service account — processkit composes cleanly with any
+of those; it just spawns and bounds whatever program you point it at. Do not
+let this guide's checklist read as "fully isolated" — it is not.
+
+## The recipe
+
+Compose these five ingredients, in this order, for a locked-down run of an
+untrusted tool:
+
+```python
+from processkit import Command, ProcessGroup, ResourceLimit, Unsupported
+
+tool = (
+    Command("untrusted-tool")
+    .env_clear().inherit_env(["PATH"])                              # 1
+    .output_limit(max_bytes=8 * 1024 * 1024, on_overflow="error")    # 2
+    .timeout(30.0)                                                   # 4
+    .kill_on_parent_death()
+)
+
+try:
+    with ProcessGroup(                                              # 3
+        max_memory=512 * 1024 * 1024, max_processes=64, cpu_quota=1.0,
+    ) as group:
+        group.start(tool)
+        ...
+    # 5. the `with` block's exit reaps the whole tree here — no orphans, ever.
+except (ResourceLimit, Unsupported) as exc:
+    ...   # no Job Object / cgroup-v2 root here (container, non-root cgroup, macOS)
+```
+
+### 1. Locked-down environment
+
+Start the child from nothing and allow-list only what it needs — never hand
+an untrusted tool the parent's full environment (which routinely carries
+credentials). Full treatment, including the ordering of `env`/`env_remove`
+on top: [Environment and sandboxing](commands.md#environment-and-sandboxing).
+
+### 2. Bounded output
+
+Cap `max_bytes` so a chatty or malicious tool cannot grow the parent's memory
+without bound (a `max_lines`-only cap does not — one newline-free flood is a
+single, unbounded line). `on_overflow="error"` turns hitting the cap into a
+failure rather than a silent drop, which is usually what you want for a tool
+you don't trust. Full treatment: [Bounding captured output](commands.md#bounding-captured-output).
+
+### 3. Whole-tree resource limits
+
+`max_memory` / `max_processes` / `cpu_quota` on the `ProcessGroup` cap the
+*whole tree* — not just the direct child — at the kernel level. This needs a
+real container (a Windows Job Object or a Linux cgroup-v2 root); where one
+isn't available, the constructor raises `ResourceLimit` rather than handing
+back a silently-unbounded group. Full treatment, including the platform
+matrix: [Resource limits: the sandbox](process-groups.md#resource-limits-the-sandbox).
+
+### 4. A timeout
+
+Untrusted code should never run unbounded. `.timeout(seconds)` kills the
+whole process tree at the deadline; pair it with `.timeout_grace(...)` for a
+graceful signal-then-kill if the tool might want to clean up first. Full
+treatment: [Timeouts & cancellation](timeouts-and-cancellation.md).
+
+### 5. Teardown
+
+Prefer the context manager (`with ProcessGroup() as group: ...` / `with
+Command(...).start() as proc: ...`) over any manual verb — its exit path is
+the no-orphan guarantee, on every platform, even if the block raises. Never
+lean on `__del__` / `atexit`: neither runs if the parent itself is hard-killed.
+Full treatment: [Tearing down](process-groups.md#tearing-down).
+
+## Checklist: run an untrusted tool safely
+
+- [ ] Environment locked down: `env_clear()` + `inherit_env([...])` (or an
+      explicit allow-list built from `env(...)` calls) — never inherit the
+      parent's full environment into an untrusted child.
+- [ ] Captured output bounded: `output_limit(max_bytes=...)` — a
+      `max_lines`-only cap does not bound memory.
+- [ ] Whole-tree resource limits set on a `ProcessGroup`: `max_memory`,
+      `max_processes`, `cpu_quota` — with `ResourceLimit` / `Unsupported`
+      handled where the kernel container isn't available.
+- [ ] A timeout set (`Command.timeout(...)`, and `Pipeline.timeout(...)` for a
+      piped chain) — untrusted code should never run unbounded.
+- [ ] Teardown via a context manager, never `__del__` / `atexit`.
+- [ ] `kill_on_parent_death()` set on the tool, so it dies even if your own
+      process crashes before teardown runs.
+- [ ] (POSIX only, if running as a privileged user) privileges dropped with
+      all three of `uid` / `gid` / `groups([...])` set together — `uid` alone
+      leaves the child holding the parent's supplementary groups.
+- [ ] Read [the threat model](#the-threat-model) above — this checklist buys
+      resource and lifetime containment, not syscall/filesystem/network
+      isolation.
+
+## Full example
+
+`examples/04_sandbox_resource_limits.py` runs this recipe end to end for an
+agent making a couple of tool calls in one sandboxed session: a locked-down,
+output-capped, per-call-timeout command; whole-tree memory/process/CPU limits
+on the shared group; and teardown on context-manager exit — degrading
+gracefully to "contained, but uncapped" where the kernel container isn't
+available (a container, a non-root cgroup, macOS).
+
+```bash
+python examples/04_sandbox_resource_limits.py
+```
+
+---
+
+Next: [Process groups](process-groups.md) · [Running commands](commands.md) ·
+[Timeouts & cancellation](timeouts-and-cancellation.md) ·
+[Cookbook](cookbook.md) · [Platform support](platforms.md)

docs/streaming.md

@@ -14,6 +14,7 @@ the tree down deterministically.
 - [Lifecycle](#lifecycle)
 - [Streaming stdout](#streaming-stdout)
 - [Tee output to a file](#tee-output-to-a-file)
+- [Live per-line callbacks](#live-per-line-callbacks)
 - [Interleaved stdout and stderr](#interleaved-stdout-and-stderr)
 - [Interactive stdin](#interactive-stdin)
 - [Readiness probes](#readiness-probes)
@@ -174,6 +175,50 @@ Things to know:
   — `output()` / `aoutput()`, `run()`, or `start()` + `stdout_lines()` /
   `output_events()`.
 
+## Live per-line callbacks
+
+`stdout_lines()` / `output_events()` are async-only — they hand back an async
+iterator, so they need an event loop to drive. `on_stdout_line(callback)` /
+`on_stderr_line(callback)` give the **synchronous** surface the same live
+observation: `callback` runs on every decoded line *as it is produced*, even
+while `.output()` / `.run()` is still blocking:
+
+```python
+from processkit import Command
+
+def log_line(line: str) -> None:
+    print("build:", line)
+
+result = Command("cargo", ["build", "--release"]).on_stdout_line(log_line).output()
+# "build: ..." printed live, one call per line, while output() was still blocking.
+print(result.stdout)   # capture is untouched — the callback observes, it doesn't consume.
+```
+
+They work identically on the async verbs and on a streamed run (`start()`/
+`astart()` + `stdout_lines()` / `output_events()`) — one callback, every path;
+adding them does not turn the sync surface async-only, and does not replace the
+streaming iterators (which stay the only way to *consume* lines one at a time
+from Python — a callback only *observes*).
+
+Things to know:
+
+- **At most one handler per stream.** A repeat call **replaces** the previous
+  one (builder semantics, like `timeout()`); compose inside a single Python
+  callable to fan out to more than one observer.
+- **A raising callback never derails the run.** An exception raised inside
+  `callback` is reported via `sys.unraisablehook` (visible on stderr, or
+  catchable in a test via a custom `sys.unraisablehook`) instead of
+  propagating — the run and its captured result are unaffected either way.
+- **No-op unless that stream's line pump runs**, same family as
+  `stdout_tee`/`stderr_tee`: `on_stdout_line` is inert under
+  `stdout("inherit")` / `stdout("null")` and under `output_bytes()` (stdout is
+  captured raw there, bypassing the line pump). `on_stderr_line` is inert under
+  `stderr("inherit")` / `stderr("null")` — but **not** under `output_bytes()`:
+  that verb only bypasses the *stdout* line pump, stderr keeps decoding through
+  it exactly as under `output()`.
+- **Runs independently of `stdout_tee`/`stderr_tee`.** Set both and both fire
+  per line — a callback and a file tee are not mutually exclusive.
+
 ## Interleaved stdout and stderr
 
 When the *interleaving* matters — a `--watch` build that prints progress to