Extending Herdr Without Losing the Boundary
Herdr's extension problem starts with a symptom: an agent row is wrong, a conversation will not resume, or a workflow needs a project-specific action. The remedy depends on the missing layer. This chapter separates lifecycle authority, native session identity, display metadata, and executable plugins, then follows each through its validation and failure surface. The practical judgment is to use the least powerful extension that fixes the actual problem—and to remember that a manifest can constrain a plugin without making its code trustworthy.
Diagnose the missing kind of state first
Consider an agent pane that appears idle while the person can see a new approval question. Several causes are possible, and they do not call for the same repair. The foreground process might not have been recognized as the intended agent. The agent might be recognized, but its screen manifest may not know the new shape of the question. A full lifecycle integration might be installed but not active for that process. Or the pane may have a useful task title that is simply unrelated to lifecycle state.
Herdr's authority model gives the operator a way to separate those causes. Start with the process. Herdr identifies the foreground job and decides which known agent, if any, occupies the pane. A wrapper or restricted runtime can make that harder by hiding the underlying process; in supported cases, a process-local agent hint can tell Herdr which existing screen manifest to use. This hint does not make every child process an agent and does not remove the possibility of a foreground-detection mistake.
If the process is recognized, inspect the live evidence. Screen-based detection reads the current bottom of the pane buffer and evaluates the active manifest for that agent. It does not treat a person scrolling through old transcript text as a new lifecycle event. A blocker must have a recognized visible shape. A new prompt may therefore appear idle until the manifest is updated. The right diagnosis is not “the sidebar is lying” in the abstract; it is “the state authority had no matching evidence for this live screen.”
The active manifest matters. Herdr ships bundled rules, can cache compatible remote rule updates, and supports local overrides. A running server loads its active rules into memory, and the explanation command can show the manifest source, version, matched rule, visible evidence, and fallback reason. If two machines or two Herdr installations behave differently, comparing those inputs is more useful than comparing their colored status dots. A local override can legitimately produce a different result from the bundled rule, but it also becomes another piece of operational configuration to maintain.
Next ask whether an integration is authoritative. Some official integrations report lifecycle transitions such as working, blocked, and idle through hooks or plugins. When a complete lifecycle authority is active for the pane, Herdr uses those reports rather than letting screen detection compete for the same fact. This avoids contradictory simultaneous authors, but it means an integration gap can be more consequential than a cosmetic issue: if the hook reports an incomplete transition, the screen fallback is not necessarily available to correct it.
Other integrations report only a native session reference. That reference is valuable after a server restart because it tells Herdr which agent conversation to launch again. It is not a current status signal.