docs(exec-runners): what an exec runner is, and where the cache key is drawn

[raphaelvigee]

Doc only — no code. Phase 0 is #405 on top of this.

What

docs/EXEC_RUNNERS.md: a short reference for ExecRunner / ExecSession, a driver-independent answer to "in what environment is this target's process created?", with devenv.sh as the first non-trivial implementation (shipped as a cdylib plugin).

The ask was: let a target run inside the devenv shell and inherit its tools; make it general rather than a pluginexec feature; spawn the shell once and have many targets run in it.

It covers the model and the surface, how a runner reaches the cache key, the environment layering rules, the three session modes, devenv, Go, and diagnosability. It documents what the stack ships — the phasing lives in the PRs.

The shape

A runner reference is a target reference. Its identity then reaches the cache key through the existing dependency mechanism instead of a new hash component — and ordering, failure attribution and cycle checking all come along for free. In particular the runner target is built during hashin, before any worker permit is held, so "opening a session may require building a target" cannot deadlock against the execute semaphore.

Selection is a workspace-level defaultRunner: plus a per-target runner =.

Reviewed by the standing board

product-vision SHIP WITH CHANGES · compatibility COMPATIBLE 6/7 · feature-quality BLOCKED · hermeticity NOT HERMETIC · code-quality BLOCKED.

The model survived; the execution details did not. The findings that most altered it:

• prepare(spec) -> Spec is the seam, not a trait-objectified process factory. Direct and Wrap are pure spec transformations, so proc_exec keeps its synchronous spawn, its Handle invariants and its PTY handling untouched.
• Six of eight process-creation sites are proc_exec::output, which cannot be built on spawn — its drain is unbounded because nothing consumes until the wait returns. A go list over 512 KiB routed through spawn + wait wedges on darwin and passes on linux.
• The "content-addressed toolchain" claim for snapshot mode was empirically false. Measured in this repo's own devenv shell: 38 of 107 PATH entries are outside /nix/store, and DEVENV_ROOT / $HOME / DEVENV_CMDLINE would all have entered the snapshot — under-hashing mutable host tools while over-hashing the checkout path and the literal command line used to enter the shell. (feat(plugin-devenv): capture a devenv environment and run targets in it #413 corrects the source of that measurement; the rule it produced stayed.)
• runtime_pass_env = ["*"] sat above the runner's PATH, so a target could build with host tools under a key asserting devenv, then push that to the shared cache. Now a hard error.
• A runner target with zero outputs is invisible to hashin — two different environments would share a cache key. Now rejected at resolution.
• runner in transitive was removed: transitive is dependency-directional, so as specified, adding a dep would silently change a target's execution environment, with an iteration-order winner when two deps disagreed.

Decisions recorded as the user's

• The snapshot's PATH is store-only and fails loudly. Host tools must become explicit tools = deps.
• Snapshot artifacts are remote_enabled = false, matching the plugin-nix precedent ("wrappers point at host-local /nix/store").

Left open and flagged rather than assumed: manifest provenance, which is a cache-format change needing its own compatibility consult. (Whether enterShell / shell functions / services are load-bearing in your devenv.nix was settled by shipping both modes — see #414.)

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}