From 38b7b540e1d1e5cdcd8fcc31bc8bcf1cde44b603 Mon Sep 17 00:00:00 2001 From: Can Celik Date: Thu, 30 Jul 2026 15:14:27 +0300 Subject: fix: add opt-in child-group process detection (#2052) * fix: add opt-in child-group process detection refs #1982 * fix: preserve lifecycle probes without foreground groups refs #1982 --- docs/next/CHANGELOG.md | 1 + docs/next/website/src/content/docs/agents.mdx | 2 ++ docs/next/website/src/content/docs/cli-reference.mdx | 1 + docs/next/website/src/content/docs/configuration.mdx | 1 + 4 files changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md index 1fc8b6f0..d3f9f8e9 100644 --- a/docs/next/CHANGELOG.md +++ b/docs/next/CHANGELOG.md @@ -8,6 +8,7 @@ ### Fixed - Vibe and other Kitty-keyboard pane applications now receive shifted letters and punctuation when they request associated text. (#2020) +- Linux runtimes without terminal foreground process groups can opt into child-group agent detection with `HERDR_PROCESS_DETECTION=child-groups`. (#1982) - Installing the Herdr agent skill with the `skills` CLI no longer copies the entire repository. (#2022) - Agent prompts now wait briefly after sending text before pressing Enter, preventing prompts from remaining in agent composers without starting a turn. (#1878) - Empty clipboard writes from pane applications no longer erase existing clipboard contents or show a copied confirmation. (#1893) diff --git a/docs/next/website/src/content/docs/agents.mdx b/docs/next/website/src/content/docs/agents.mdx index f5a4ac48..e7764d84 100644 --- a/docs/next/website/src/content/docs/agents.mdx +++ b/docs/next/website/src/content/docs/agents.mdx @@ -51,6 +51,8 @@ Claude Code, Codex, GitHub Copilot CLI, Droid, Qoder CLI, Cursor Agent CLI, and On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint is scoped to that foreground process; setting it only inside a VM or container is not visible to Herdr, and you should avoid exporting it globally unless every inherited foreground process should be treated as that agent. +Some restricted Linux runtimes do not expose a terminal foreground process group. Start the Herdr server with `HERDR_PROCESS_DETECTION=child-groups` to opt into direct child-process-group inference when native detection is unavailable. Native detection remains preferred, and the default `native` mode never performs this inference. The opt-in mode is best effort: a newer background job can be mistaken for the foreground job. The variable is read by the server and requires a restart; set it in the remote server environment rather than on an attaching client. + ## Blocked state Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output. diff --git a/docs/next/website/src/content/docs/cli-reference.mdx b/docs/next/website/src/content/docs/cli-reference.mdx index a49a4212..2aa008f5 100644 --- a/docs/next/website/src/content/docs/cli-reference.mdx +++ b/docs/next/website/src/content/docs/cli-reference.mdx @@ -479,6 +479,7 @@ These meanings apply to reads. For `pane wait-output` only, both `recent` and `r | `HERDR_CONFIG_PATH` | Override the config file path. | | `HERDR_SESSION` | Select a named session for CLI commands. | | `HERDR_SOCKET_PATH` | Low-level socket path override. | +| `HERDR_PROCESS_DETECTION` | Linux process detection strategy: `native` (default) or opt-in `child-groups`. | | `HERDR_ENV` | Set to `1` inside Herdr-managed pane processes. | | `HERDR_PANE_ID` | Public pane id for the running pane process. | | `HERDR_TAB_ID` | Public tab id for the running pane process. | diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx index df6dc8d3..bd908765 100644 --- a/docs/next/website/src/content/docs/configuration.mdx +++ b/docs/next/website/src/content/docs/configuration.mdx @@ -452,6 +452,7 @@ On Windows, support is currently limited to the Korean IME. With an IME for any | `HERDR_CONFIG_PATH` | Override the config file path. | | `HERDR_SESSION` | Select a named session for CLI commands. | | `HERDR_SOCKET_PATH` | Low-level socket path override. | +| `HERDR_PROCESS_DETECTION` | Linux process detection strategy: `native` (default) or opt-in `child-groups`. | | `HERDR_LOG` | Set log filtering, for example `HERDR_LOG=herdr=debug`. | | `HERDR_DISABLE_SOUND` | Disable sound playback even when `[ui.sound] enabled = true`. | -- cgit v1.2.3