Herdr Throwaway Reproduction

Herdr throwaway reproduction

Use a disposable named Herdr session when a reproduction needs a real Herdr server, panes, PTYs, agents, or socket API without risking the user's main session.

The temporary TUI only keeps the disposable session attached and supplies terminal geometry. Drive the reproduction from the parent session through Herdr's CLI/API. Do not manually operate the nested TUI unless the bug specifically requires client input.

Non-negotiable safety

• Never run the reproduction in the default session.
• Never stop, restart, delete, or kill the main Herdr server.
• Never use pkill, broad process matching, or guessed PIDs for cleanup.
• Create a unique session name. Never reuse or delete an unrelated named session.
• Create a new outer pane and close only that pane during cleanup.
• Read workspace, tab, pane, terminal, and agent IDs from command output. Never construct them.
• Use /var/tmp for reproduction directories and potentially large artifacts.
• Do not approve destructive or unnecessary agent actions.
• Do not spend paid agent tokens without the user's approval. Use the requested low-cost model and the smallest useful prompts.

Learn the installed interface first

The installed binary is the authority. CLI syntax may have changed since this skill was written.

Confirm the caller is inside Herdr and inspect the relevant help before doing anything:

test "${HERDR_ENV:-}" = 1
herdr --version
herdr --help
herdr session
herdr pane
herdr agent

Inspect nested command help before using unfamiliar or potentially mutating commands. Do not run bare herdr for discovery because it launches or attaches the TUI.

Record which Herdr binary and version the reproduction tests. If testing a checkout build, follow the repository's instructions for running that build instead of silently substituting the installed binary.

Create the outer pane

Create a sibling shell pane in the current tab without moving focus. Use an available Herdr layout tool when the harness provides one. Otherwise use the installed pane split command after checking its help.

Use /var/tmp or a dedicated reproduction directory as the new pane's cwd. Save the returned outer pane ID. This is the only parent-session pane that cleanup may close.

Start the disposable session

Choose a short unique name such as repro-<topic>-<timestamp>.

Before launching, explicitly allow nesting in the configuration the disposable client will actually load. HERDR_ENV=1 is inherited from the outer pane, so the launch is otherwise rejected unless [experimental].allow_nested is enabled. An isolated XDG_CONFIG_HOME does not inherit this setting from the user's global config, even when nesting is enabled there.

Create a test-only config under the reproduction directory using the file-writing tool. For a default-config reproduction, its contents can be:

[experimental]
allow_nested = true

If reproducing with the user's configuration, copy that configuration into the test directory and enable allow_nested in its existing [experimental] table (or add the table if absent). Do not create duplicate tables or keys. Never edit the user's global configuration to permit a reproduction, and do not unset HERDR_ENV to bypass the nesting check.

Pass the absolute test config path as HERDR_CONFIG_PATH when launching below. Use the same override for config validation and any commands that must load the test config. This override selects a config file; it does not isolate the saved machine catalog or other global state. Use test-only XDG_CONFIG_HOME and XDG_STATE_HOME as well when the reproduction changes saved machines, and retain those overrides on every command addressing that test environment.

Run the named session inside the new outer pane. Clear inherited session selection, socket overrides, and caller IDs so the nested runtime cannot accidentally address the parent session:

env \
  -u HERDR_SOCKET_PATH \
  -u HERDR_CLIENT_SOCKET_PATH \
  -u HERDR_SESSION \
  -u HERDR_WORKSPACE_ID \
  -u HERDR_TAB_ID \
  -u HERDR_PANE_ID \
  HERDR_CONFIG_PATH=<absolute-test-config-path> \
  herdr --session <session-name>

Add reproduction-specific environment variables to this launch command when needed. Environment variables that configure the server must be present before the named server starts.

Validate the test config with herdr config check using the same config override before launch. After launch, read the outer pane to catch startup errors such as nested herdr is disabled by default; do not assume the launch succeeded merely because pane run returned successfully.

Do not continue until the named session's API is ready. Confirm readiness by addressing that session from the parent and listing its panes.

Address only the disposable session

Every control command issued from the parent must clear inherited socket overrides and explicitly select the temporary session:

env \
  -u HERDR_SOCKET_PATH \
  -u HERDR_CLIENT_SOCKET_PATH \
  -u HERDR_WORKSPACE_ID \
  -u HERDR_TAB_ID \
  -u HERDR_PANE_ID \
  HERDR_SESSION=<session-name> \
  herdr pane list

Repeat this prefix for every command. Do not rely on shell state persisting between tool calls.

Read the disposable root pane ID from pane list. Confirm its cwd and foreground process before starting anything in it.

Named sessions isolate runtime state, sockets, panes, and persistence. They still share global Herdr configuration and agent manifest overrides by default. Check configuration provenance when it could affect the reproduction. Do not modify shared configuration merely to make the test pass.