From One Pane to Many Machines

Herdr becomes a coordination system when a person or another agent can act on the server-owned runtime without relying on the currently visible pane. This chapter applies the ownership and persistence model to the CLI, socket API, event-driven waits, Git worktrees, and SSH connections. The practical aim is not to memorize a command catalog. It is to choose the narrowest control surface for the job, preserve target scope, and understand what changes when the process lives in another workspace or on another machine.

Use the narrowest control surface

Herdr exposes the same control surface through two layers. The CLI wraps common operations for shell scripts, human debugging, and straightforward orchestration. The raw socket API uses newline-delimited JSON over a local Unix socket on Unix or a named pipe on Windows, and is useful when a tool needs direct request/response control or a long-lived event subscription. Both layers speak to the running server; neither creates a private copy of the session.

The first decision is what kind of thing the caller is trying to control. A pane is the right target for an ordinary shell command, test runner, development server, terminal input, or output read. An agent is the right target when Herdr must interpret lifecycle state or address the recognized coding process by name. An event subscription is appropriate when a long-lived tool needs to observe changes rather than repeatedly poll. A one-shot output wait belongs to a pane; an agent wait belongs to semantic lifecycle state.

That distinction matters in a simple example. If a test runner prints passed, a caller can use a pane output wait to look for that text. If a coding agent is ready for a new prompt, a caller should use an agent-aware wait rather than infer readiness from an arbitrary line in the terminal. A process can print a success message while remaining active, and an agent can display a prompt-like string while still rendering a transcript viewer. The control primitive should match the fact being observed.

Herdr's creation and control responses return JSON records with authoritative identifiers. A script should capture the pane ID returned by a split or workspace creation instead of deriving one from screen position. Managed pane processes inherit their workspace, tab, pane, and socket context, so a command running inside a pane can safely use a current-pane target when that is what it intends. Omitting a target may instead use the UI-focused pane, which can belong to a person, another client, or another part of the workspace. Explicit context reduces that hidden dependency.

The same caution applies to input. Pane commands can send literal text, logical keys, or a command that is submitted with Enter. Agent commands add lifecycle checks: an agent prompt can submit text and optionally wait for activity and a settled state. If the agent is already blocked on an approval or question, a prompt-with-wait refuses to send input. The caller must inspect the visible request and deliberately choose a response. That prevents an automation script from treating every blocked state as permission to proceed.

A prompt wait also guards against a subtler race. A successful write does not prove that the agent began a new turn.