Skip to content

feat(herdr): forward pane identity env into box agent (#131) - #137

Merged
pgebheim merged 2 commits into
mainfrom
pgebheim/131-herdr-pane-identity-env
Aug 20, 2026
Merged

pgebheim merged 2 commits into
mainfrom
pgebheim/131-herdr-pane-identity-env

Conversation

@pgebheim

Copy link
Copy Markdown
Collaborator

Summary

Final piece of the herdr relay chain (spike #127; #129 host vsock route, #130 guest socat listener). The herdr plugin's agent pane now forwards the pane's herdr identity into the box, so the in-guest agent's herdr hook attributes agent state (working/blocked/done) to the right pane — the pattern from scott-the-programmer/vscode-devcontainers-herdr's exec.rs, adapted for lilbox.

Two paths, both covered:

  • Provision: lilbox agent gains a repeatable --env KEY=VAL flag, applied as transient exec env on the guest agent exec (never persisted in the sandbox config, per the secrets-in-exec-env rule). The shim's ensure_box passes --env for each set identity var.
  • Attach (the pane flow): the pane provisions without a task, so the agent actually starts via lilbox ssh ... -- sh -lc '... exec claude'. The shim now exports the identity in that remote command and — since herdr relay: socat unix→vsock listener in box image + agent launch #130 only wires the unix→vsock socat listener into the task launch — brings up the listener idempotently ([ -S "/home/arch/.config/herdr/herdr.sock" ] || socat ... &), keyed off HERDR_SOCKET_PATH.

Forwarded: HERDR_SOCKET_PATH, HERDR_PANE_ID, HERDR_WORKSPACE_ID, HERDR_TAB_ID, HERDR_ENV=1 (whichever are set; absent vars are skipped). Deliberately not forwarded: HERDR_BIN_PATH — a host path, meaningless in the guest; the guest hook talks to the socket over vsock.

Closes #131

Test plan

  • cargo test --locked — 151 unit tests incl. new parse_exec_env cases (pairs, =-in-value, malformed rejection)
  • contrib/herdr/tests/run.sh — 44 assertions; new TEST=19 (agent action forwards all identity vars to lilbox agent argv + exports them on the attach path + starts the relay listener; HERDR_BIN_PATH never forwarded) and TEST=20 (nothing forwarded when not under herdr). Harness now sanitizes ambient HERDR_* so it stays hermetic when run from a herdr-hosted session.
  • cargo fmt, cargo check --locked, cargo clippy --locked --all-targets -- -D warnings — clean
  • Remaining manual step: live KVM end-to-end verification (agent in box visible in herdr agent list with correct pane association) — to be attempted by the maintainer post-merge.

Architecture

New surface: lilbox agent --env KEY=VAL (repeatable). Why transient exec env and not config: AGENTS.md's rule that secrets/identity reach guests only via transient exec env, never the persisted sandbox builder config. run_guest gained an exec_env: &[(String, String)] param applied to both the attach and exec-stream paths; other callers pass &[]. No new config files, no persisted state.

The agent pane now forwards the pane's herdr identity (HERDR_SOCKET_PATH,
HERDR_PANE_ID, HERDR_WORKSPACE_ID, HERDR_TAB_ID, HERDR_ENV=1) into the
guest so the in-box agent's herdr hook attributes state to the right pane:
- lilbox agent gains a repeatable, transient --env KEY=VAL flag (exec env
  only, never persisted sandbox config); the shim's ensure_box uses it.
- The agent pane's attach command exports the same identity and brings up
  the guest unix->vsock relay listener (a box provisioned without a task
  never starts one).
- HERDR_BIN_PATH is deliberately never forwarded (host path).
- attach-path socat keeps stderr (drop 2>&1), matching the Rust task path
- parse_exec_env validates keys as [A-Za-z_][A-Za-z0-9_]*
- README: identity env is forwarded at attach/exec time, not provision
- test: HERDR_PANE_ID with a space round-trips through %q unsplit
@pgebheim
pgebheim merged commit 33b27dc into main Aug 20, 2026
1 check passed
@pgebheim
pgebheim deleted the pgebheim/131-herdr-pane-identity-env branch August 20, 2026 18:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

contrib/herdr: forward pane identity env into box agent

1 participant