feat(mux): herdr support

[rmarganti]

Description

This adds herdr as a supported cli.mux.backend

Changes include:

• a new Herdr session backend at lua/sidekick/cli/session/herdr.lua
• backend registration alongside tmux and zellij
• automatic defaulting to herdr when running inside a Herdr environment
• support for:
  • embedded terminal attach flows
  • external/inherited Herdr sessions
  • opening sessions in a new tab (create = "window")
  • opening sessions in a split (create = "split")
  • session discovery / reuse from existing Herdr panes
  • pane/process inspection for restoring Sidekick sessions
• health check coverage for herdr
• docs updates in README.md and doc/sidekick.nvim.txt

Related Issue(s)

• N/A

Screenshots

[willian]

Hi @rmarganti, thanks for working on this. I tested the flow against Homebrew Herdr 0.8.0 and mapped the current CLI contract. The breakage mentioned above goes beyond --cwd:

herdr agent start <NAME> --kind <KIND> --pane <ID> [--timeout <MS>] [-- [AGENT_ARG]...]

agent start now requires --kind and an existing --pane; it no longer creates a pane, and it does not accept --cwd, --no-focus, --split, or --env.

The backend architecture in this PR still looks right. I think the launch path can be adapted to 0.8.0 as a two-step flow:

1. Create the requested pane with herdr pane split (including --direction, --ratio, --cwd, --env, and --no-focus) or herdr tab create for create = "window".
2. Start a recognized agent with herdr agent start <sid> --kind <kind> --pane <pane_id> --timeout 30000. For tools outside Herdr's --kind enum, fall back to herdr pane run, with herdr agent wait <pane_id> --until idle --timeout 30000 as a best-effort readiness check.

A few related 0.8.0 details I verified:

• pane list exposes the agent as pane.agent_session.agent, not pane.agent; it also provides pane.agent_status.
• agent wait uses --until, not --state.
• pane split supports --ratio, so cli.mux.split.size can be preserved.
• terminal attach exists even though it is hidden from --help.
• create = "terminal" from inside Herdr creates a nested session, so the agent appears in the inner session rather than the current sidebar. I think that mode should warn and recommend split or window for now.

This Sidekick backend work is independent of herdrdev/herdr#803, which is the more general problem of detecting and reporting state for agents that remain embedded behind Neovim or another PTY wrapper.

I'm happy to implement the 0.8.0 changes against your branch if that would help keep this as one PR. If you do not have capacity to continue it right now, I can instead open a new Sidekick PR based on #333, with explicit credit and preserved attribution. Let me know which route you prefer.

[calops]

Thanks guys for addressing this. I'm putting this out there only as a reference if it can help, but here is my working implementation in my config until mainstream supports herdr properly: https://github.com/calops/nix/blob/df50d100021894151fae164242e16d48915cbae9/modules/programs/neovim/_config/lua/plugins/ai.lua#L5-L141

I was planning on contributing to this PR properly but not much time for it lately. I'm sure I'm missing a lot of corner cases anyway.

Note though that herdr isn't perfect as a multiplexer for this, as this workaround is needed: https://github.com/calops/nix/blob/df50d100021894151fae164242e16d48915cbae9/modules/programs/neovim/_config/lua/plugins/ai.lua#L169-L177

The method used to view a single pane is sending raw input where some things get lost in translation, while the proper frontend interprets some keybindings properly (in this case, <S-Cr>). I'm not sure there's any hopeful solution to this as it seems to be a structural program in herdr and there doesn't seem to be a way to ship multiplexer-dependent default bindings in sidekick.

[rmarganti]

Sorry for delay getting this updated. I've been entrenched in a work meetup all week. I've updated my original PR to support modern Herdr APIs. A couple notes:

• This pr does not use agent run any longer. The core issue is that Herdr must first create a pane and then launch the agent. When the agent exits, the pane remains, which is not compatible with the sidekick flow.

  Instead we use pane run exec {theAgentCommand}, which replaces the shell with the agent process, meaning the pane closes when the agent exits.

  This does also keep things more flexible for arbitary commands/tools not known to Herdr.

• calops's issue is out of scope here, since it is a translation issue between Neovim → Herdr → the agent. This issue (from what I've seen) is only when using the create = "terminal" config.