Remote capture fails for all documented selection paths on a headless Herdr server #23

Summary

On a headless remote Herdr server, none of the selection paths currently documented by Herdr Annotate delivers text to annotate.capture:

1. Herdr mouse selection followed by prefix+a
2. Herdr Copy Mode selection followed by prefix+a
3. Neovim Visual selection followed by the documented <leader>a mapping

The action runs, but HERDR_PLUGIN_CONTEXT_JSON has no selected_text. Annotate then falls back to reading the server's graphical clipboard, which is unavailable on a headless host, and exits with:

No supported clipboard reader is available

This makes the documented remote setup unusable for capturing new annotations, even though the manager and other plugin actions work.

Environment

• Herdr: 0.8.2, stable
• Herdr Annotate: 0.3.0, lite, resolved commit fb93a1318f960792452cef6cde72a2c4f4591241
• Server: Ubuntu 24.04 LTS, headless (DISPLAY and WAYLAND_DISPLAY unset)
• Client: Linux, Ghostty, attached with herdr --remote devbox-hz --remote-keybindings server
• xclip is installed on the server, but there is no graphical display/clipboard to read

Remote server configuration:

[ui]
copy_on_select = false

[keys]
prefix = "ctrl+b"

[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "annotate.capture"
description = "annotate text"

This matches the documented remote setup.

Reproduction

1. Mouse selection

1. Attach using server keybindings.
2. Drag-select text in a pane and release the mouse button.
3. Confirm the selection remains highlighted because copy_on_select = false.
4. Press Ctrl+B, release it, then press a.

The selection disappears and Annotate reports No supported clipboard reader is available.

2. Herdr Copy Mode

1. Press Ctrl+B, release it, then press [.
2. Press v, move with $ so that text is visibly selected.
3. While the selection is still visible, press Ctrl+B, release it, then press a.

The selection disappears before annotate.capture receives its context. The action again falls back to the unavailable server clipboard.

Using y first does not help: it exits Copy Mode and sends the copied text to the viewing client, while the plugin still executes and reads the clipboard on the remote server.

3. Neovim Visual mode

Install the documented mapping:

vim.keymap.set("x", "<leader>a", function()
  vim.cmd('normal! "+y')
  vim.fn.jobstart({
    "herdr",
    "plugin",
    "action",
    "invoke",
    "annotate.capture",
  })
end, { desc = "Annotate in Herdr" })

1. Select text in Neovim Visual mode.
2. Press <leader>a.

The OSC 52 yank reaches the viewing client's clipboard, but the plugin action runs on the remote server. The CLI invocation does not include the Visual selection as selected_text, so Annotate falls back to the unavailable remote clipboard and fails.

Actual result

Recent plugin logs for the failed captures contain:

{
  "action_id": "capture",
  "status": "failed",
  "exit_code": 1,
  "stderr": "No supported clipboard reader is available\n"
}

annotate.manage succeeds in the same installation, confirming that the plugin runtime and keybindings are otherwise working.

Expected result

At least one documented remote selection path should deliver the selected text to annotate.capture without requiring a graphical clipboard on the server.

If remote capture is not currently supported on a headless server, the Remote sessions and Neovim integration sections should say so instead of stating that prefix+a and the Visual-mode mapping work remotely.

Related upstream behavior

These Herdr reports cover parts of the failure but not the complete user-facing problem:

• herdrdev/herdr#3353: mouse selection is absent from plugin context after mouse-up with the default copy_on_select = true. The documented false setting avoids that exact mouse-up path, but the following prefix input still clears the retained selection.
• herdrdev/herdr#2011: direct plugin keybindings lose selected_text before context construction. It was closed administratively without a fix.

For Copy Mode, Herdr currently cancels Copy Mode before invoking a prefix custom command, which clears the selection before the plugin context is built:

• navigate.rs
• copy_mode.rs

For Neovim, Herdr's socket API can represent explicit context.selected_text, but herdr plugin action invoke and the documented mapping do not expose that text channel. Annotate consequently uses its server-side clipboard fallback.

I am filing this here because it is the extension's documented end-to-end workflow. The underlying fixes may require Herdr changes, an Annotate-side helper/integration that passes explicit text, or documentation changes.