Plugin panes: identity (plugin.pane.list), documented HERDR_PLUGIN_STATE_DIR, restore across restarts

[andykram]

We maintain two plugin panes (a code-review sidebar and a messaging sidebar) on herdr 0.7.3 / protocol 16, and three tightly-related gaps in the plugin-pane lifecycle force fragile workarounds. Filing them together because one design pass probably covers all three.

1. No way to identify your own panes. plugin.pane.open's response returns the created pane, but there is no plugin.pane.list, and PaneInfo carries no plugin_id/entrypoint. So a toggle/close action has to find its pane by label string equality — which breaks if the user renames the pane, and can close an unrelated pane the user happened to name the same. Either a plugin.pane.list method or plugin_id + entrypoint fields on PaneInfo would make toggle/close exact.

2. HERDR_PLUGIN_STATE_DIR is provisioned but undocumented. The env var is passed to plugin processes, but its semantics (creation, retention across reinstalls/updates, survival across live handoff) aren't documented anywhere we could find. We'd like to use it for exactly the kind of state that shouldn't live in the config dir — last-selected item, pane-id bookkeeping for gap 1, draft recovery — but can't rely on undocumented behavior. A short docs section would unblock this.

3. Plugin panes don't survive server restarts. Agent integrations get resume_agents_on_restore, but plugin panes silently disappear across herdr update/restarts, so a "sidebar that's always there" contract breaks invisibly. Restoring plugin panes (or an opt-in manifest flag for it) would close the loop.

Happy to provide more detail from our plugins or test preview builds.

[oborchers]

I have a concrete stateful application use case for the restore part of this proposal.

I maintain Proqi, an agent-optimized terminal scratchpad for follow-up prompts next to coding-agent sessions. Each Proqi pane owns one durable board. It can resume safely only from its exact Proqi SessionId and state root.

I tested this with Herdr 0.8.2. After a cold server restart, the plugin pane’s layout slot returns as a fresh shell, but its declared command does not restart. A startup hook can try to recover it, but the current public plugin contract cannot reliably establish:

• The exact application state belonging to the restored pane
• Whether the user intentionally closed the application or Herdr interrupted it
• One process owner across crashes, updates, live handoff, and multiple independent panes
• Bounded readiness, shutdown, retry, and restart-loop behavior
• Separation from coding-agent prompt and status semantics

A manifest flag that reruns a saved command would restore the process, but it would leave those ownership questions unresolved. Native agent restore covers some related mechanics, but its identity, status, prompt, and resume semantics are specific to coding-agent harnesses.

Is the intended direction to give stateful plugin panes a lifecycle contract, or to introduce a separate restartable application or managed-companion role? I have exact 0.8.2 source findings and an isolated experiment matrix that I can share if useful.

[LeaveMyYard]

+1 from another plugin: herdr-panorama opens a sidebar panel next to each agent in every tab. After an unexpected server stop (crash, kill, power loss), on 0.9.3 each panel comes back in place but as a plain shell with leftover text, so every tab shows a dead terminal where the sidebar was. After a live herdr update --handoff they come back fine; only the cold restore loses them.

We can't relaunch our command in the restored pane, and nothing marks the pane as having been ours (point 1 here). So today we close those shells ourselves, but only when we can tell no one has typed in them; otherwise the stale shell stays. Restoring plugin panes as plugin panes (point 3 here), or at least marking a restored pane with the plugin that opened it, would remove all of that.