Herdr Dispatch

Budget -> split -> start -> brief -> collect -> verify -> clean up.

The herdr-workflow instruction decides that subagents become panes. This decides how. Policy lives there; do not restate it here.

Preconditions

test "${HERDR_ENV:-}" = 1                                  # else: not inside Herdr, stop
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

Not inside Herdr -> say so and fall back to the Agent tool. Never control a Herdr session from outside it.

Every socket-API subcommand (tab, pane, agent ...) prints a JSON envelope {id, result} on stdout by default - no flag needed, pipe to jq. The one exception is agent read, which is plain text (see Blocked).

Pane Budget

Claude Code's TUI is unusable below ~60 columns; budget at 68 so a worker can render a diff rather than merely survive. Height has a floor too - budget 20 rows, below which the transcript scrolls past faster than it can be read.

A tab splits both ways, so the budget is a grid rather than a row. Splitting only one direction wastes the other axis: four columns on a standard tab are 34 wide and unusable, while the same four as a 2x2 sit at the full 68.

Workers belong in their own tab - the user's driving pane stays uncluttered and their focus stays where they put it. Create that tab first, then measure it:

herdr tab create --workspace "$HERDR_WORKSPACE_ID" --label "workers" --cwd "$PWD" --no-focus  # -> .result.tab, .result.root_pane
herdr pane layout --pane "<root-pane-id>"                    # -> .result.layout.area.{width,height}

--workspace is not optional. Omit it and the tab is created in whatever workspace currently has focus, which is routinely not yours - the user clicks into another project and every worker tab lands there. --cwd still points the agents at the right directory, so the work itself comes out correct and the mistake shows up only as panes scattered in someone else's space. Read the id from $HERDR_WORKSPACE_ID, never assume the focused one.

Measure the worker tab's root pane, never $HERDR_PANE_ID. Your own pane is whatever the user's current split happened to leave it; a fresh tab spans the terminal. Budgeting off your pane under-counts and you spawn fewer workers than actually fit.

Budget = floor(width / 68) * floor(height / 20), minimum 1. A 136 x 43 tab is 2 x 2, so four workers. More than the budget -> a second tab, never thinner splits.

Tasks beyond the budget wait for a free pane. Reuse a finished worker's pane - an idle agent takes a new prompt - or close it and split fresh. Never queue two tasks into one live agent; it serializes them and you lose the point.

Split

Wide pane -> right. Narrow or tall -> down. Alternating is what builds the grid: a fresh tab is wide, so it splits right into two tall halves, and each half then splits down. Repeating one direction is what produces unusable slivers.

# columns first, from the worker tab's root pane
herdr pane split --pane "<root-pane-id>" --direction right --cwd "$PWD" --no-focus
# -> .result.pane.pane_id
# then rows, once per column
herdr pane split --pane "<column-pane-id>" --direction down --cwd "$PWD" --no-focus

Split from an explicit --pane, not --current, once a grid is involved. --current follows focus, and with --no-focus on every split focus never moves - so a second --current split re-splits the pane you already split.

--cwd is explicit, always. Inherited cwd is not guaranteed, and a worker in the wrong directory fails in confusing ways.

Start

herdr agent start "<name>" --kind claude --pane "<pane-id>"
# -> .result.agent.agent_status == "idle"   (~4s)

Names match [a-z][a-z0-9_-]{0,31} (herdr agent start rejects violations as invalid_agent_name) and must be unique among live agents - check herdr agent list first. A name follows the pane's current occupant and clears when that agent exits.

agent start needs a pane already sitting at its shell prompt; it never creates or moves layout. That is the split's job.

Returns agent_not_ready if the agent is blocked during startup - the name still works for agent read / agent send-keys. Wait for idle before prompting.

Different --kind (codex, gemini, ...) is the one case where a second pane buys something rerunning the same model cannot. Use it for independent review, not for throughput.

Brief

One task per agent, and per multi-agent-workflow the tasks in a wave are already independent - no task needs another's output, no file is written by two. Panes do not isolate the working tree, so that check happens before dispatch, not here.

The worker sees none of the parent conversation, so the brief carries everything:

• What to do, concretely
• Which paths it owns, and which it must not touch
• The repo's verify command
• The result contract below

herdr agent prompt "<name>" "<brief>" --wait --timeout 600000

--wait needs to observe working or blocked within five seconds of submission, else agent_prompt_stalled. A stall or timeout does not prove the prompt never landed - inspect with agent get and agent read before resending. A blind resend double-submits.

agent prompt refuses to send into a blocked agent (agent_blocked) before writing anything.

Collect

Per the herdr-workflow instruction: the result file is the completion signal, never scraped screen output. Every brief ends with -

Write your complete result as Markdown to <path>. Reply with only that absolute path, nothing else.

Then read that file. No file on disk means not done, regardless of what --wait returned.

Verify the work yourself before trusting it. A worker reporting success is a claim, not evidence.

Blocked

Read the dialog first:

herdr agent get "<name>"
herdr agent read "<name>" --source recent-unwrapped --lines 120

Park that task, keep every other worker running, and surface the pane id to the user. Never answer an approval dialog on their behalf.

Use --source detection for what Herdr classified on, --format ansi when color is the evidence. send-keys (esc, ctrl+c) is for recovering a wedged TUI, not for clicking through prompts.

Cleanup

Only after results are collected and verified:

herdr tab close "<tab-id>"

Close only what this run created. Never touch a pane, tab, or workspace the user owns. Never herdr server stop - it kills every agent on the machine.

Report every pane id spawned, including ones left running. An agent still alive with no record of why is the failure mode here.

Rules

• Read every id from JSON responses. Never guess w1:p3, never infer from sidebar order
• --no-focus on every split and tab create, and --workspace "$HERDR_WORKSPACE_ID" on every tab create
• One task per agent, one agent per pane
• Budget before spawning, on both axes. Splitting past it makes every worker unreadable, including the ones already running
• Verify before believing. Collect before closing