Skip to content

TUI: self-report lifecycle state to the herdr agent runtime - #456

Merged
sosidudku1 merged 1 commit into
mainfrom
feat/herdr-self-report
Sep 15, 2026
Merged

sosidudku1 merged 1 commit into
mainfrom
feat/herdr-self-report

Conversation

@sosidudku1

Copy link
Copy Markdown
Collaborator

What

When the TUI runs inside a herdr pane it now claims its own pane label through herdr's socket CLI: working while a turn is in flight, blocked while a tool approval or the plan hand-off waits on the human (with the tool name as the message), idle otherwise, and a release-agent goodbye on every exit path. Outside herdr the reporter is null and nothing changes.

Why

herdr (github.com/herdrdev/herdr, the "leave them running" agent runtime, 38k stars) labels every pane with the agent's live state. Atomic already runs fine in a pane, but shows up as an unnamed process. Self-reporting makes it a first-class agent there today, for every user, without waiting on the herdr team; it also backs our pending proposal to add built-in detection on their side (herdrdev/herdr#4201).

How

  • src/tui/herdr-reporter.ts: env detection (HERDR_ENV / HERDR_BIN_PATH / HERDR_PANE_ID), a pure deriveHerdrReport over the TUI state, and a fire-and-forget reporter (spawn, stdio ignored, errors swallowed, children unref'd).
  • Wired in one effect in tui-app.tsx (state observation plus unmount release) and in tui-command.ts (reporter creation, plus a release in the teardown finally for quit paths that never unmount the tree).
  • Two herdr behaviors are encoded and commented, both verified against herdr 0.9.0: sequence numbers start from epoch seconds so a restart in the same pane outranks the previous run's reports, and the release must carry the next sequence number or herdr silently drops it and the label sticks to a dead pane.

Testing

  • 15 unit tests in src/tui/herdr-reporter.test.ts; npx vitest run src/tui green (302 files / 3331 tests; the one unhandled error is the pre-existing llama-server EACCES flake in local-models-orchestrator-auto-update.test.ts, unrelated).
  • tsc --noEmit clean.
  • Live end to end against herdr 0.9.0 on macOS: pane start shows atomic · idle with no manual calls, a turn flips it to working, a file-write approval flips it to blocked, approve returns it to idle, and double ctrl+c quit leaves the herdr agent list empty.

Inside a herdr pane (HERDR_ENV markers present) the TUI claims its
pane label through the socket CLI: working while a turn runs, blocked
while an approval or the plan hand-off waits on the human, idle
otherwise, and a release-agent goodbye on every exit path, including
quits that never unmount the React tree.

Sequence numbers start from epoch seconds so a restart in the same
pane outranks the previous run's reports, and the release carries the
next number because herdr silently drops stale-sequenced releases
(both verified against herdr 0.9.0). Outside herdr the reporter is
null and everything stays inert.
@sosidudku1
sosidudku1 merged commit 1b87434 into main Sep 15, 2026
2 checks passed
@sosidudku1
sosidudku1 deleted the feat/herdr-self-report branch September 15, 2026 23:07
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.

1 participant