
louise
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
ADR 0085: std/command runs another program to its end: argv only, nothing inherited, bounded, killed with its process group
Status: Proposed (2026-11-16); needs engineering review (#44).
Context
- A Louise program cannot run another program.
std/processis the actor runtime,std/oshas the environment, arguments, exit and signals, and nothing starts an OS process (issue #467). - toki2 needs well-known tools it will not rewrite: a page archiver
(headless Chromium, monolith),
pdftotext,tesseract,yt-dlp,ffmpeg(toki2#57). Several are not libraries, so C bindings are not an option. - Running programs from a server is a classic hole: a shell that interprets an argument, an inherited environment that leaks secrets, a program that never ends, output that fills memory, children left behind when the server restarts.
- The runtime blocks SIGTERM, SIGINT and SIGHUP in every thread and takes
them on a signal thread (ADR 0060). A child inherits a blocked mask
across
exec; ADR 0060 already noted that a child "should reset it". - Rust's
std::process::Commandkeeps the parent's mask in the child on both its spawn paths (posix_spawnandfork; toolchainstd/src/sys/process/unix/unix.rs). A child started with it ignores SIGTERM, so a timeout could only ever SIGKILL it. - The scheduler parks actors on a mio reactor (sockets,
net.rs), and a kill wakes an actor parked on it. The blocking pool cannot be woken by a kill (Wait::Blocking), so a run must not wait there. - ADR 0084 (capability roots, unmerged) moves files and sockets behind
fsandnetroots. It excludes OS process powers on purpose.
Decision
std/command.run :: Command -> Result<Output, Error> / <io> runs a
program to its end. command.new program args gives the defaults; a
field changes with Command(..cmd, field: value).
No shell.
argsreach the program as they are. A program named without a/is looked up in thePATHofenv, absolute entries only, never in the caller's.Nothing inherited. The environment is exactly
env. Every descriptor the runtime opens is close-on-exec, so the child gets only its three pipes.Bounded.
- Output past
max_stdoutormax_stderr(16 MiB and 64 KiB by default) is read and dropped, so the program never blocks on a full pipe. The run says it was cut. - At
timeout_ms(30 s) the child's process group gets SIGTERM, and SIGKILLgrace_ms(2 s) later.TimedOut(signal)names the last one sent. - When the program ends, what is left of its group is killed, and the
pipes are drained for at most
grace_ms: a descendant that left the group withsetsidmay hold them open.
- Output past
Scratch.
Scratch(inputs, outputs, max_file)runs the program in a fresh0700directory under the temporary directory:- inputs are written with
O_EXCL|O_NOFOLLOW; - the listed outputs are read back, regular files only, opened
O_NOFOLLOW|O_NONBLOCKand at mostmax_filebytes each (Found,TooLarge,Absent); - the directory is then removed.
A caller that only has bytes thus never touches the file system itself, and
std/fileneeds no directory operations for this.- inputs are written with
posix_spawndirectly (runtime/louise_rt_prims/src/command.rs), not Rust'sCommand:- an empty signal mask, every disposition back to its default, and a
process group of the child's own (
POSIX_SPAWN_SETSIGMASK,SETSIGDEF,SETPGROUP); - the pipes become the child's 0, 1 and 2, and
addchdir_npsets its working directory; - everything is built before the call, so the child runs no Rust.
glibc's
posix_spawnusesCLONE_VFORK, so no copy of a large heap is made.
- an empty signal mask, every disposition back to its default, and a
process group of the child's own (
Never blocking a scheduler thread.
- The child's pipes, a pidfd (its exit) and a timerfd (the next deadline) are registered with the reactor under one token, and the actor parks on it as on a socket.
- Each wake-up does what can be done without waiting: drain the pipes,
feed stdin, check the pidfd with
waitid(P_PIDFD, WNOHANG), send the signal that is due. - Stdin is written with SIGPIPE blocked on the thread, and a pending
one taken, so a program that stops reading gives
EPIPE, never the end of ours. - The interpreter runs the same driver, waiting with
poll(2). A run is unrepeatable for the test cache.
No zombies, no orphans.
- A killed actor drops its run, which kills the group and reaps the
child. A child that does not die at once (uninterruptible sleep) is
reaped by a
louise-reaperthread, never an actor's. - The runtime keeps the groups still running, and an
atexithandler kills them when the program exits, bymain's end,os.exitor a signal's default action.
- A killed actor drops its run, which kills the group and reaps the
child. A child that does not die at once (uninterruptible sleep) is
reaped by a
<io>, likestd/os. Running a program is OS authority, which ADR 0084 leaves out of its roots. A sixth root would also spill past the six value registers of actor entry (0084'sMAX_ACTOR_CAPS).commands, an effect for tests.run_commandmirrorsrun;command.nativelyruns for real andcommand.scripted answeranswers from a function. This is thelogpackage's idiom: code that runs programs is tested without running anything.Raw boundary. One extern,
tl_command_run, takes plain values (texts, lists,Bytes,Ints) and answers tuples.std/commandbuilds its own types, so the runtime does not depend on their layout. It isunwinds(), notblocking.
Consequences
- Linux 5.3 or later (
pidfd_open), as the runtime is Linux only (ADR 0011). - glibc 2.29 or later for
posix_spawn_file_actions_addchdir_np, in programs that usestd/command(others drop it at link time). - A run holds everything it reads in memory, up to its caps. A
program that writes gigabytes writes them to a scratch file, and the
caller raises
max_filedeliberately. - Real time. A run takes a reactor token, which switches a native
program's clock to real time, as a first socket does (unless
LOUISE_VIRTUAL_TIMEis set). A program that talks to the outside world cannot be replayed anyway. - Concurrency is the caller's. Nothing limits how many programs run
at once; a server bounds its tools itself (toki2 with
resilience.gate). - One test file per backend.
tests/run/command.lseruns interpreted and native.crates/louise/tests/command.rschecks what only a real process shows:- a killed actor and an exiting program leave no child;
- a child sees only descriptors 0 to 2;
- 200 runs leak no descriptor;
- a subscribed SIGTERM still arrives while children run.
Open questions for the engineering review
- Capability. Should running programs become a capability once ADR
0084 lands (a
commandroot, or a narrowedosone)? And should remote actors be denied it, as they are files and sockets? PR_SET_PDEATHSIG. Children are killed by theatexithandler, not if the program is SIGKILLed. Parent-death signals needfork(notposix_spawn) and are tied to the spawning thread.closefrom.posix_spawn_file_actions_addclosefrom_np(glibc 2.34) would also close descriptors a C binding opened withoutO_CLOEXEC. It is left out to keep the glibc floor at 2.29.- Streaming. A variant that hands output over as it comes, for programs whose output should not be held in memory.