Feature request: `--events-fd <FD>` — machine-readable NDJSON recipe-execution events

[friedenberg]

Programs that supervise just runs — agent harnesses, TUIs, CI annotators — can't reliably recover which recipe is running, which command produced which bytes, or how each recipe ended from the human-oriented terminal output.

Proposal: just --events-fd <FD> <recipe> writes newline-delimited JSON to a caller-supplied file descriptor: a leading plan record, then recipe_start / recipe_command / output / recipe_complete records carrying dependency structure (depth/parent), evaluated command text with 1-indexed source lines, captured child output, and per-recipe exit status and duration. Without the flag, behavior is byte-identical to today.

$ just --events-fd 3 hello 3>events.ndjson
{"type":"plan","version":1,"recipe_count":2}
{"type":"recipe_start","tp":1,"name":"hello","namepath":"hello","depth":0,"parent":null,"doc":null,"quiet":false}
{"type":"recipe_start","tp":2,"name":"dep","namepath":"dep","depth":1,"parent":1,"doc":null,"quiet":false}
{"type":"recipe_command","tp":2,"command":"echo dep-output","line":5}
{"type":"output","tp":2,"stream":"stdout","format":"utf8","data":"dep-output\n"}
{"type":"recipe_complete","tp":2,"exit_code":0,"signal":null,"duration_ms":1}
...

We've implemented this in a fork we maintain, amarbel-llc/just-us, with:

• a normative wire-format spec: RFC 0002
• a design record with known limitations (buffered output, no PTY, unix-only): FDR 0001
• a bats conformance suite (zz-tests_bats/events_fd.bats)

We know pull requests are disabled (#3227), and this isn't an ask to merge anything — we're happy maintaining the fork. This issue just puts the use case and a worked design on record. The fork is CC0 like upstream, so if you ever want the feature, take or reimplement whatever is useful, in whatever shape you'd actually want it.

In the spirit of #3227's reasoning, full transparency: the implementation and this issue were largely written by a coding agent, supervised by @friedenberg.

---

:clown: Filed by Clown 0.4.0+cd38c2d (build commit) on behalf of @friedenberg.

[casey]

This is definitely an interesting feature. I recently implemented something similar in another project and wound up using a socket, with, e.g., --ready-address localhost:2000. I think either a socket or a file descriptor are both defensible, although a socket means you can send events over the network and without touching the file system. The reason I landed on a socket was because opening and passing a numbered file descriptor is really only ergonomic in shell, it's rough in other languages, and in Windows a socket is much much easier. I briefly tried to do a cross platform file-descriptor-ish thing on Windows, but it was super gross.

I'm very curious what use-cases people have for this, and what the demand is like, so I'll leave it open.