herdr
herdr is a terminal workspace manager for running several coding agents side by side. Luna works in it unchanged, and two pieces make it better. They are independent: either works without the other.
herdr's own pi integration
herdr integration install pi
This writes herdr-agent-state.ts into pi's extensions directory. It reports whether the pane's
agent is working, blocked or idle, and which session it is. Luna does not copy it. It is managed by
herdr, so update it with herdr.
Luna's herdr extension
Enabled by the lite, balanced, long-horizon, self-improving and engagement profiles. It does
nothing unless pi runs inside a herdr pane (HERDR_ENV=1, HERDR_PANE_ID and HERDR_SOCKET_PATH
set), and never in a subagent child. It registers no tools or commands.
| Luna event | What herdr shows |
|---|---|
| A tool-firewall approval card opens | A "Luna needs you" notification, and the pane marked blocked until the card closes |
ask_human asks a question |
The same |
| An automatic verify check fails | A "Luna: a check failed" notification |
| A run of 30 seconds or longer ends | A "Luna finished" notification |
The blocked state reaches herdr through the herdr:blocked event on pi's event bus, which herdr's
pi integration turns into the pane state. Without that integration herdr still shows the
notifications, but not the blocked state from Luna.
Other extensions announce themselves on the luna:attention bus channel: a payload with a boolean
active opens or closes a blocking ask, one without it is a one-off notice. They never import the
herdr extension, so it can be removed or replaced without touching them.
| Variable | Effect |
|---|---|
PI_KIT_HERDR=off |
Disable the extension |
PI_KIT_HERDR_NOTIFY_MIN_SECONDS |
Shortest run that raises "finished" (default 30, 0 for every run) |
The agent-state file
Every Luna agent that reports its state writes one small JSON file, <id>.json, in
~/.local/state/luna/agents (override with LUNA_AGENT_STATE_DIR; never under pi's agent
directory). The schema (packages/core/shared/agent-state.ts, one writer with generated copies):
| Field | Meaning |
|---|---|
state |
working, blocked, done, failed, stopped or parked |
waitingFor |
Only while blocked: the approval or question, in a line |
tail |
The last 400 characters of what the agent said or did |
worktree, costUsd |
Where it works and what it has spent, when known |
source, pid, since, updatedAt |
session or autonomy; the process; when the state last changed; the last write |
The herdr extension writes one for its pane (pi-<pid>): done while a new session sits idle at the prompt, working when a run starts, blocked with
the approval or question while one is open, then done, stopped (aborted, or pi exiting mid-run) or failed
when it ends, or parked when a ceiling parks the run (tests/herdr-smoke.ts). Autonomous runs write autonomy-<run> and an outcome.md
(the run directory). A reader needs only the directory:
readAgentStates returns the valid files and ignores the rest. The file is a status report, not an
instruction, and a failed write never affects the agent.
Not covered: only a session inside herdr writes a file (the extension is a no-op elsewhere); the web
console does not read the files yet; there is no luna agents command. A killed process leaves its
last state in place, so check pid and updatedAt before trusting working.
tests/agent-state-smoke.ts pins the schema and the autonomy mapping; tests/herdr-smoke.ts pins
the blocked-approval state.
herdr decides whether to display a notification (it may be disabled, rate limited or have no foreground client); Luna sends it and moves on, and never waits on herdr.
Not covered: a custom profile that does not include the extension gets no notifications; add herdr
to it to enable it (it is a no-op outside herdr).
An aborted or failed run does not raise "finished". Autonomous runs (/autonomy) run in a container and do not emit attention events, so a
blocked run does not notify herdr. tests/herdr-smoke.ts pins the herdr side against a stubbed
socket; tests/firewall-approvals-smoke.ts and tests/human-console-broker-smoke.ts pin the approval
and question events. The verify-gate failure notice is not pinned by a test, and nothing tests against
a live herdr.