feat(exec-runner): Agent and Wrap sessions

[raphaelvigee]

Phase 2b of #404, on top of #413 — the last of the stack's core work. mode = "session" holds a devenv shell open and forks every target's process from inside it; WrapSession covers container/chroot runners.

Proved end to end

Against this repo's own devenv, the distinction the second mode exists for:

shell function under mode = "snapshot"	NOT available
shell function under mode = "session"	available

Agent mode is a spec transformation, not an overridden spawn

The first sketch had ExecSession::spawn overridden for Agent. It cannot be: spawn returns a proc_exec::Handle, which can only be built for a child of this process — and the whole point of an agent is that the child is forked by something else. Returning a trait object instead would undo the reason prepare is the seam at all.

So Agent is also a pure spec transformation. The spec is rewritten to run heph __runner-exec, which heph spawns as its own ordinary child:

  heph ──spawn──> client ──unix socket──> agent (inside `devenv shell`)
                    │        SCM_RIGHTS         │
                    └── its own 0/1/2 ──────────┴──fork/exec──> the target

Handle, the bounded drain, the PTY and the supervisor keep working unchanged, and the child's stdio are the same descriptors — passed, not proxied. That is the property the fd-passing protocol exists to protect: a proxy would insert a copy loop between the target and the terminal, breaking PTY semantics and interactive output. Cancellation falls out: heph kills the client's process group, the agent sees the socket close.

Two bugs the first end-to-end run found

The agent must env_clear. It lives inside the devenv shell, so inheriting its environment would put the developer's ambient GOFLAGS/RUSTFLAGS/PATH tail into every build — unhashed, under a key reporting as lockfile-pinned. That hole was missed when session mode was first analysed.

Shell functions must be export -f'd. Otherwise they're defined in a shell the target never runs in: pluginexec invokes every target through its own bash -c, and functions aren't inherited by a child shell unless exported. The first run reported the function still missing.

SNAPSHOT_FORMAT_VERSION → 2 for the prelude change, and it earned its keep immediately: without the bump the fix was invisible behind a cached v1 snapshot.

WrapSession

Prepends a wrapper command. WrapEnv distinguishes wrappers that exec the inner program (chroot, bwrap, nix develop --command — the spec's env carries through) from those that create it elsewhere (docker exec — the environment must be rendered into the wrapper's own argv, or the container process sees none of it). The second kind reports no enumerable environment rather than handing back the host-side map as if it described what the inner process will see.

Teardown is now wired — it wasn't

Nothing called teardown(). ExecSessionPool now runs every session's teardown explicitly, and idempotently: an orderly-only teardown leaks exactly when things aren't orderly, which is the docker run -d container and the devenv shell surviving Ctrl-C. Regression-tested (runs once, and not while the session is still in use).

Tests

20 in exec-runner (SCM_RIGHTS round-trip proving descriptors arrive open on the far side, stale-vs-live socket handling, Wrap argv/env rendering, Agent spec rewrite, teardown handed over at most once), 9 in plugin-devenv, 4 in runner_agent (the -- boundary, so a target's own --socket can't retarget the client), 12 e2e. lint clean — the fd-passing code is one unsafe operation per block, each with its own safety condition.

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