Evaluate Herdr as a cross-brand AgentTUI communication backend

[Yangtze-Seventh]

Problem

Arborist can discover Codex and Claude Code sessions through the AgentTUI registry, and sendbox provides durable asynchronous handoff records. It does not currently provide a provider-neutral, visible, agent-usable delivery backend between live AgentTUI sessions.

Provider-native resume commands are asymmetric and have different visibility/reply semantics. The registry itself is intentionally static and does not deliver messages.

Candidate: Herdr

Herdr advertises lifecycle-aware support for both Claude Code and Codex, direct integrations for both providers, and terminal-backed automation such as:

herdr agent prompt <target> "<message>" --wait --timeout <ms>
herdr agent read <target> --source recent-unwrapped --lines <n>
herdr agent wait <target> --until blocked --timeout <ms>

Its agent prompt path can send to an already-working agent and is visible in the target pane, which may fill the current gap between headless provider-native resume and human relay.

Primary references:

• https://herdr.dev/docs/agent-automation/
• https://github.com/ogulcancelik/herdr

Gardener investigation requested

Please determine whether Herdr can serve as an optional cross-brand AgentTUI communication backend for Arborist:

1. Test Codex → Claude Code and Claude Code → Codex delivery between Herdr-managed panes.
2. Record whether delivery is visible in the target pane, queued while working, and correlated with the intended target turn/session.
3. Test --wait, completion/blocking detection, timeout behavior, and response retrieval for both providers.
4. Define the reachability boundary: Herdr-managed panes only, attachable external panes, or arbitrary registered sessions.
5. Determine how an Arborist registry leaf (brand, session_id, session_file) maps safely to a Herdr agent/pane identity without guessing by display name.
6. Check alternate-screen/readback limitations and define a durable-response fallback.
7. Decide whether Herdr belongs in the optional tool registry, a communication-backend capability schema, or a separate adapter layer.

Policy boundary

This must not weaken ADR-0006 or the same-brand L2→L1 execution rule.

• Message plane: cross-brand notification, question, acknowledgement, and delivery reminder may be supported.
• Execution plane: an Impler and all of its implementation/TDD/refactor/check/challenge/research subagents remain same-brand.
• Durable commitments still require sendbox; a Herdr prompt may be an additional delivery notification, not a replacement for the record.

Acceptance criteria

• A written capability/limitations matrix based on two-way live tests.
• An explicit decision: adopt, defer, or reject Herdr as the optional backend.
• If adopted, a portable tool-registry/template entry with availability and fallback behavior.
• No hard dependency on Herdr for repositories that do not install it.
• Regression coverage that prevents message-plane support from becoming cross-brand subagent routing.

[JasonJarvan]

KHS dogfood now has a verified local baseline for the gardener to compare with Herdr.

Verified two-way handshake

• Codex gardener-v2 -> Claude Code rootorc: injected into Zellij terminal_132
• Claude Code rootorc -> Codex gardener-v2: injected into Zellij terminal_131
• reply reached the active Codex turn as [ARBORIST-DIRECT:v1] ... ACK-PANE-V1 with the matching nonce
• both registry entries record actual brand and a structured pane_ref

Local adapter policy

1. active/idle + reachable runtime.pane_ref: inject a one-line sender envelope into the real ATUI pane and submit Enter
2. stopped Claude Code: claude -p --resume
3. stopped Codex: codex exec resume
4. active Codex without a reachable pane: fail closed

The fourth rule matters. Codex's current manual documents app-server turn/steer and says Enter while the CLI is working steers the active turn, but a standalone Codex TUI does not expose a registry-addressable app-server endpoint by default. We therefore rejected bare concurrent codex exec resume after rootorc challenged it.

What Herdr should improve or prove

Please test whether Herdr can replace the Zellij-specific pane_ref adapter while preserving:

• actual-brand registry identity
• visible delivery to the existing ATUI, not a second headless full-context turn
• active Codex steering/queue semantics
• target/sender/nonce correlation and reverse reply
• fail-closed behavior when a pane is stale or unreachable
• a durable fallback boundary: handoff/decision/done still require sendbox

The KHS result is a local proof-of-concept, not a request to standardize Zellij as Arborist's permanent transport.

[JasonJarvan]

Gardener investigation — pre-assessment + disposition

Thanks for the issue and the KHS dogfood baseline — the Zellij pane_ref two-way handshake is a useful concrete comparison target.

Where this stands. I've completed a desk-level study of Herdr's agent-facing surface (socket API + CLI: agent prompt/wait/read, pane split/send-*/read, events.subscribe, pane report-agent, plus the plugin manifest/event-hook model) and mapped it against Arborist's needs. I have not yet run the two-way live matrix the acceptance criteria require, so this is a pre-assessment, not an adopt/reject decision.

What the desk study already supports

• Identity mapping (point 5). herdr pane report-agent --agent-session-id <sid> --agent-session-path <path> lets an Arborist leaf (brand / session_id / session_file) bind to a Herdr pane without display-name guessing. That is the safe addressing seam.
• Placement (point 7). Keep Herdr behind a generic adapter interface (spawn / deliver / wait / subscribe / report-state) and register it as an optional tool-registry entry with an availability probe + fallback — no hard dependency for repos that don't install it. Apache-2.0 fits, and is a clean replacement for the AGPL CCB runtime that was removed.
• Policy boundary — accepted as a hard constraint. Message plane (notify / question / ack / delivery-reminder) may be cross-brand; execution plane (an Impler and its impl/TDD/refactor/check/challenge/research subagents) stays same-brand per ADR-0006 / the L2→L1 rule; durable commitments still require sendbox — a Herdr prompt is only an additional delivery notification, never the record.

What remains blocked on live two-way tests (points 1–4, 6)

• Active-Codex steer/queue semantics via agent prompt — your rule-4 fail-closed case is exactly the open question.
• Visible-in-the-existing-ATUI vs. a second headless full-context turn, for both providers.
• Alternate-screen readback limits → durable-response fallback boundary (expect detection / report-agent state to be the reliable signal, sendbox the durable fallback).
• target/sender/nonce correlation + reverse reply; and the three reachability tiers (Herdr-managed / attachable-external / arbitrary-registered).

One reconciliation this surfaces. The KHS policy (resume only for stopped sessions; active → pane injection; active Codex without a reachable pane → fail-closed) is stricter than Arborist's current ADR-0003 amendment, which loosely allowed active-peer --resume. The Herdr work should tighten the delivery-axis model along the KHS lines and fold that back into ADR-0003.

Disposition: deferred to the roadmap. This is a full gardener deliverable — install Herdr → run the two-way capability/limitations matrix → ADR + optional tool-registry/template entry with availability+fallback → regression guard against message-plane support drifting into cross-brand subagent routing. Scheduled as a future roadmap item rather than executed now; no hard Herdr dependency will be introduced in the interim. Leaving this issue open as the tracking entry.