v0.2.0 to v0.3.0

---

name: herdr-faq

description: Launch and drive coding agents (codex, claude, agy) through the Herdr CLI reliably. Use before starting or prompting a subagent via herdr agent/pane commands, and when any herdr command fails or an agent seems stuck, silently lost a prompt, or reports a wrong state.

metadata:

categories: "agents, operations"

topics: "herdr, troubleshooting, agent-orchestration, terminal-multiplexer"

upstream: "herdr@0.9.0"

openclaw:

homepage: https://github.com/tenequm/skills/tree/main/skills/herdr-faq

emoji: "🐑"

---

# Herdr FAQ

Launch and drive coding agents through [Herdr](https://herdr.dev) (>= 0.9.0) without losing

prompts. Command semantics: `herdr --skill` (the binary ships its own current doc and is the

tiebreaker for any dispute with this file). This file covers only what goes wrong and the

recipes that avoid it.

## Invariants

1. **Exit 0 is submission, never completion.** `agent prompt` writes text and Enter as one

ordered submission and reports success only after both land - that still does not prove a

turn started. `send-keys` proves nothing at all: it can return `{"type":"ok"}` for

keystrokes that never reach the pane. Confirm by effect: state moved, or the text is

visible in the pane.

2. **Screens no detection rule matches read as `idle`.** agy has no idle rule at all, so every

agy `idle` is a guess. Read the screen before the first prompt, always.

3. **`agent start` timeout = the child never launched.** Bad flag, PATH, or a wrapper process.

`pane read` has the real error; `pane process-info` and herdr's own message do not.

4. **`idle` is not "finished".** A claude turn that spawns background shells or a background

MCP task ends and reports `idle` while that work runs on. `--wait` tracks lifecycle state,

not turns: it can be satisfied by a turn already in flight, or by the idle an interrupted

turn produces a second later.

5. **The driving harness is a second gate.** Dangerous passthrough flags (`--dangerously-*`,

`danger-full-access`) get classifier-blocked, and so can ordinary brief *content* inlined

into a shell command. `sleep N; herdr ...` polling is banned - use one backgrounded

`prompt`, or wait on a file.

```bash

```

```bash

```

```bash

```

Rules: capture every ID from JSON, never predict. Names `[a-z][a-z0-9_-]{0,31}`, namespaced

(`myproj-reviewer`, never `driver`); names die with the agent - re-attach via

`agent rename <pane> <name>`. Fleets get their own workspace, `--no-focus` everywhere. After a

killed `agent start`, run `herdr agent get <name>` once to free the name reservation

(reconciliation is lazy - it can take a minute or two).

## Shapes

The facts you need while composing a command, not after it fails.

**Output modes.** `agent get`, `agent list`, `agent start`, `agent prompt`, `agent wait`,

`pane split`, `pane list`, `pane process-info`, `workspace *` return **JSON** - pipe to `jq`.

`agent read` and `pane read` return **raw pane text** with no wrapper; piping them to `jq`

dies with `parse error: Invalid numeric literal` and you silently lose the read. Use `tail`,

`grep -qF`.

**Positional vs flagged.** `pane close` takes its id **positionally** (`herdr pane close "$P"`)

- the one pane command that does, while `pane split|read|list|layout|process-info` all take

`--pane`. `workspace create` takes `--label`, not `--name`. `send-keys` takes key names only

(`enter`, `esc`, `down`, `ctrl+c`); text and slash commands go through `prompt`.

**Flag dependencies and caps.** `agent start --timeout` defaults to 30000 and is capped at

300000. `agent prompt --timeout` has **no cap** (1800000 is fine) but is rejected outright with

`--timeout requires --wait` when `--wait` is absent - and under a backgrounded call that

failure is invisible and the prompt is never written. Fire-and-forget sends take no flags.

**Sparse JSON.** `agent list` entries are partially populated: `name` is **absent** (not null)

for unnamed agents, `interactive_ready` is absent on many, and a pending start appears as

`{"agent_status":"unknown","launch_pending":true}` with no `agent` or `agent_session` key.

Null-guard every string op: `select((.name // "") | startswith("myproj-"))`.

**Env vars** go in `--env KEY=VALUE` at pane/tab/workspace creation, never

`pane run 'export ...'` (that sets them in a subshell the agent never sees). **Repeated flags

go inline** - building them in a shell variable fails, because zsh does not word-split

unquoted expansions and herdr receives the whole string as one argument:

```bash

E="--env A=1 --env B=2"; herdr pane split ... $E # WRONG: unknown option: --env A=1 --env B=2

herdr pane split ... --env "A=1" --env "B=2" # right

```

Bad flags print usage (some of it on **stdout**), so a `| jq` pipeline turns it into a

misleading parse error. Check exit status before parsing.

## Drive

```bash

# Blocking send: one call, generous timeout, backgrounded.

herdr agent prompt worker "$(cat brief.md)" --wait --timeout 1800000

# Fire-and-forget note to a working agent: no flags at all.

herdr agent prompt worker "$(cat note.md)"

# On timeout: usually false - confirm before acting, never blind-resend.

herdr agent get worker # working = still on the turn

# Mid-turn dialogs: wait for blocked, inspect, surface to the human, answer via send-keys.

herdr agent wait worker --until blocked --timeout 120000

herdr agent read worker --source detection --lines 40

# Exit: confirm positively - shell back in foreground. Never regex the prompt.

herdr pane process-info --pane "$P" && herdr pane close "$P"

```

- **Wait on the artifact, not the state.** End every non-trivial brief with "write your full

report to `<path>` and reply with only the path", and poll for the file. `idle` arrives on

interrupted turns, on fleet parents that dispatched children and ended their turn, and for

the entire multi-minute life of a claude background MCP task. A watcher written as

`[ "$s" != "working" ] && echo stopped` false-alarms on every one of those.

- `--until` defaults to `idle|done|blocked`; keep it there for turn waits, because narrowing

it is how waits hang. **One exception**: right after answering a dialog, a bare `wait`

returns the still-`blocked` state within milliseconds - a no-op that looks like the key

never landed. Gate on `--until idle done` there, or poll `agent get`. A wait ending

`agent_not_running` after the agent exited or moved is the event, not an error.

- `done` and `idle` both mean ready for input; `done` is an unseen completion, and focusing the

tab silently rewrites it to `idle`. Each TUI client tracks this independently, so its badge

can disagree with the CLI. Gate decisions on `agent_status`, never `interactive_ready`

(which stays true while blocked).

- Long text is safe through `agent prompt` - it uses bracketed paste, and 8 KB arrives intact.

The 1024-byte (macOS) tty truncation is real but applies to **`pane send-text`** and

keystrokes. Pass file paths anyway when the text is a brief: it also keeps the content out

of the shell command, where the driving harness's classifier can block on it.

- Output: `--source recent-unwrapped` for transcript, `detection` for the last screen,

- Queue follow-ups behind a working agent freely; `agent prompt` refuses blocked agents

(`agent_blocked`) before writing anything. But do not attach `--wait` to a queued follow-up:

it can be satisfied by the turn already running.

- Slash commands that open dialogs trip the fixed 5s `agent_prompt_stalled` gate - verify

those by screen read, not `--wait`.

## Failures

Triage first:

- **Any start failure** -> `herdr pane read <pane> --source visible` FIRST. The most common

cause is a bad flag: the child launched, printed `error: unknown option ...`, and exited,

leaving only the shell - so `process-info` looks innocent and herdr reports a bare

`timeout`. Then `pane process-info --pane <id>`: a foreign foreground process = busy/race;

an agent under a wrapper (`node`, a bare version string) = herdr cannot identify it ->

relaunch via `HERDR_AGENT=<kind> exec <cmd>`, then `agent rename`. An agent under

`docker exec`, `podman exec`, or `ssh -t` is permanently undetectable (WONTFIX).

- **Any wrong state** -> `herdr agent explain <target> --verbose` + `agent read --source

detection`. Matched rule null + `default_known_agent_idle_fallback` = herdr is guessing.

Stale manifest -> `herdr server update-agent-manifests` (no restart; named servers now pick

up each other's downloads). Local rule patch: `~/.config/herdr/agent-detection/<kind>.toml`.

- **Logs**: `~/.config/herdr/herdr-server.log`, `HERDR_LOG=herdr=debug`.

- **After a binary update**, do NOT reflexively `server stop`. 0.9.0 leaves a compatible server

and its running agents untouched; check `herdr status` (`endpoint_compatible`,

`restart_needed`, `server_binary_stale`) and stop only for server-side changes - stopping

kills every pane process and in-flight turn, unresumably. A **stale client** inverts the

advice: it reports the running server as "old" while `pane list` correctly says

`client protocol N is older than server`. Trust `herdr status`.

- **"herdr is stuck"** is often the terminal emulator, not herdr. A wedged surface takes no

input while panes and agents are fine in the server. Open a fresh tab before touching the

server.

**`agent_not_ready` (start)** - a dialog is on screen. Exit 1 but the agent is running and the

name is bound (documented contract). Read, answer via send-keys, wait on `--until idle done`,

prompt. A blocked launch never times out: `launch_pending` stays true and `rename` returns

`agent_launch_pending` until the dialog is answered or the process exits. Both codex's

**`timeout` (start)** - invariant 3; read the pane. `command not found` in a non-login shell:

set `[terminal] shell_mode = "login"`, recreate the pane. Under `--remote`, panes inherit the

*server's* PATH, so a `~/.local/bin` agent CLI is not found and you get a bare timeout.

**`agent_name_taken` / `agent_launch_pending`** - reservations are made before launch and

reconciled lazily: `herdr agent get <name>` once frees an expired one. Still wedged (rename ->

pending, get -> not_found, restart -> pane_busy): burn both - fresh pane, fresh name. Names are

cross-workspace and freed names get recycled - namespace them.

**`agent_pane_busy`** - "available shell" = the shell itself, alone, in the foreground. Three

cases: (a) racy - shell still running its rc files (`starship`, `direnv`); herdr retries only

2s (never on Windows) and `pane get` looks identical ready vs not, so retry with backoff and

clean up any orphaned tab; (b) genuine occupant - split a new pane, do not reclaim (killing the

occupant cascades into `pane_not_found`); (c) permanent on Windows - a profile that

chain-launches pwsh nests shells invisibly: `[terminal] default_shell = "pwsh.exe"`.

**`agent_not_found`** - downstream symptom: failed start, exited agent, or a bad name earlier

in the loop. A pane holding only a shell also returns it. A live pane can rarely lose

registration while the TUI runs fine - `agent rename <pane> <same-name>` restores it.

**`timeout` (prompt --wait / wait)** - usually the turn outlasted the timeout: `agent get`

shows `working`. Use 1800000+, background it, never resend on timeout alone.

**`agent_prompt_stalled`** - the 5s gate is fixed and now starts *after* submission, accepting

only observed `working` or `blocked`; the caller timeout includes submission time, and expiring

first returns `timeout` instead. **It is not proof of non-delivery** - the text may have landed

and been consumed. Causes in observed order: stale manifest; dialog-opening prompt; a

target-side paste modal swallowing Enter (omp's Large Paste Menu, which triggers on *line

count*, not bytes - disable it in omp `/settings`); Windows input races on long prompts. Never

blind-resend and never recover with a lone `send-keys enter` (it can silently no-op). Read the

pane, then re-send with a fresh `agent prompt` - not a keystroke:

```bash

for i in 1 2 3; do

herdr agent prompt "$A" "$TEXT" --wait --timeout 60000 && break

herdr agent read "$A" --source recent-unwrapped --lines 200 | grep -qF "${TEXT:0:80}" && break

done

```

**`agent_blocked` (prompt)** - refused before anything is written. Read detection, surface the

dialog, answer via send-keys.

**`invalid_agent_name`** - grammar above; shell loops producing uppercase are the classic

cause, and one bad name cascades into a wall of `agent_not_found`s.

**`pane_not_found` / `workspace_not_found` / `unknown option: <valid-looking value>`** - IDs are

runtime-only, never reused: re-list at session start, recreate only what is missing.

`unknown option` on a whole flag string is the shell-variable trap (see Shapes); on a lone

token it is usually an empty `$P` making the parser blame the wrong thing.

**`workspace_group_close_required`** - closing a primary workspace with open worktree

workspaces needs `workspace close --group`. Closing the last tab closes its workspace. `tab close` can likewise return

`confirmation_required` when it would close a whole worktree group.

**Harness blocks** - classifier denial on dangerous passthrough flags: put permissiveness in

the child agent's own config ("Stage 2 classifier error" is transient - retry once). Allowlist

read-only commands (`agent get/read/list/wait/explain`, `pane read/list/process-info`,

`workspace list`) or every call prompts.

Silent failures (exit 0, no error): fallback-idle prompt swallowing (invariant 2); `send-keys`

returning ok without delivering; bare `agent prompt` leaving text unsubmitted in an

out-of-view pane; tty truncation of long `send-text`; a first turn going straight

`unknown -> working -> idle` skips `done` and its notification; detection sees only the pane's

own rows (fallback 24), so a tall dialog in a short pane is partly invisible;

`pane wait-output` matches the echoed command itself - never use it for readiness;

`agent focus` can return ok without moving the viewport in 0.9.0 - use `tab focus` instead.

## Multiple machines (0.9.0)

`herdr machine` manages saved SSH endpoints, but it is a **TUI-only** surface: there is no

machine namespace in the CLI or socket API. IDs and live agent names are scoped to one server,

two machines can both hold `w1:p1` or an agent named `reviewer`, and selecting a machine in the

TUI does **not** retarget CLI commands run in your pane - they still use the inherited socket.

For automation, run the herdr CLI on the intended host over ssh and rediscover IDs there. Only

add, remove, enable, or disable profiles when the user asks; setup asks before stopping an

incompatible remote server and defaults to No - do not approve replacement without consent.

`--trust-repository` on `worktree` grants per-request Git trust and is not a routine retry.