A Working Model of Herdr

Herdr's architecture and agent-awareness model become useful only when they can guide a real decision involving more than one pane. This checkpoint connects server ownership, workspace topology, agent evidence, and client presentation through one multi-agent scenario. The goal is not to repeat definitions, but to let the reader tell which facts are live, which are inferred, which belong only to a particular view, and what question must be answered before the Herdr runtime stops or changes.

A selection is never just a click

Suppose a person is working on two related but separate tasks. One workspace contains an agent editing an API and a second pane running its tests. Another workspace contains an agent preparing documentation. The person attaches a Herdr client, sees both workspaces in the sidebar, and clicks the documentation agent because its state indicates that it needs attention.

That click has several meanings at once. It selects a presentation surface in the client. It identifies a workspace and tab in the current Herdr session. It resolves a pane that contains a real terminal. It may also focus an agent target, but only because Herdr has recognized a process in that pane and associated state with it. The click does not create a new documentation process, move the process to the client's machine, or turn the sidebar label into a guarantee about the quality of the agent's work.

The target's scope must be preserved through the whole action. If both a local server and a saved SSH machine contain a workspace with a similar label, the visible name is not enough to identify the runtime. A pane ID such as w1:p1 is useful only in the server that issued it. A live agent name is likewise an alias within one server. Herdr's inherited caller context and explicit machine/session routing exist because a valid command sent to the wrong server is still a valid command with the wrong consequence.

Now imagine the person asks the API to read the documentation agent's pane. The safe path is not “read whichever pane is focused.” The caller must resolve the intended server, then the workspace, then the pane or agent target. The server performs the read against the terminal runtime it owns. If the pane has moved since the caller discovered it, the response from the move operation supplies the authoritative new public handle. A process can remain alive while its location and workspace-qualified ID change.

The same scenario explains why topology and state should not be collapsed. The API agent can be working in its pane while its test pane is also running. Moving the test pane to a logs tab changes the arrangement, not the test process. The documentation agent can be blocked while the client is looking at the API workspace. Switching views changes what the person sees, not the underlying agent's state or the server that owns its terminal. The runtime is one system with multiple scopes, not a set of screenshots that happen to share a window.

A second client makes the distinction sharper.