herdr 패인에서 에이전트 상태가 멈출 때, 어디를 보나

herdr 에이전트 상태가 사이드바에서 멈춰 보이면, 먼저 herdr agent explain으로 현재 감지 스냅샷과 매칭된 규칙·폴백 이유를 확인합니다. 그다음 클라이언트 detach와 서버·세션 재시작을 구분하고, agent read / pane read로 실제 터미널 출력을 읽습니다.

이 글은 패인·워크스페이스에서 상태가 stuck처럼 보이거나 idle로 오진될 때의 점검 순서만 다룹니다. 설치·후기·가격은 다루지 않습니다. 근거는 herdr 공식 Agents·CLI 문서입니다.

상태가 안 바뀌면 어디를 보나?

한 줄 답: herdr agent explain <대상>으로 최종 상태, 매칭 규칙, idle 폴백 이유를 먼저 봅니다.

Herdr는 패인마다 포그라운드 프로세스를 감지한 뒤, 에이전트별로 **하나의 상태 권위(status authority)**를 둡니다. 라이프사이클 훅이 완전히 보고하는 통합이 있으면 그 보고가 권위이고, 그렇지 않으면 패인 버퍼 하단(live bottom-buffer) 화면 스냅샷에 TOML 매니페스트를 맞춰 idle / working / blocked를 분류합니다.

상태가 안 바뀌어 보일 때 공식 문서가 가리키는 첫 도구는 다음과 같습니다.

herdr agent explain <pane-or-agent>
herdr agent explain --verbose
herdr agent explain --json

Explain 출력에는 에이전트 종류, 최종 상태, 매니페스트 출처·버전, 매칭된 규칙과 근거, 스크린 감지를 건너뛴 이유, 규칙이 없을 때 idle로 떨어진 폴백 이유가 포함됩니다. 알려진 에이전트인데 규칙이 안 맞으면 default_known_agent_idle_fallback으로 idle이 됩니다. blocked는 승인·질문·권한 UI가 보이는 스냅샷에만 엄격히 붙습니다.

추가로 확인할 항목입니다.

herdr agent list / herdr agent get으로 API가 보는 상태가 사이드바와 같은지 확인합니다.
herdr integration status로 설치한 통합이 outdated인지 봅니다. 필요하면 herdr integration install <agent>로 맞춥니다.
로컬 매니페스트 오버라이드를 수정했다면 herdr server reload-agent-manifests로 서버 캐시를 다시 읽힙니다.
VM·샌드박스 래퍼가 실제 에이전트 프로세스를 가리면 HERDR_AGENT=<kind> 힌트가 필요할 수 있습니다(예: HERDR_AGENT=claude).

화면 기반 감지는 최신 하단 버퍼를 봅니다. 에이전트 앱이 alt-screen으로 승인 UI를 가리거나, 커스텀 매니페스트에 skip_state_update 같은 규칙이 있으면 사이드바가 실제 작업과 어긋날 수 있습니다. 이때도 explain의 skipped-update·fallback 필드가 단서입니다.

재시작과 detach 차이는?

한 줄 답: 클라이언트 detach는 서버와 패인 에이전트를 살려 두고 보기만 끊는 것이고, 서버·세션 정지는 패인 프로세스를 함께 끝낼 수 있습니다.

공식 개념상 Herdr 세션의 서버와 에이전트는 클라이언트를 닫거나 분리해도 계속 실행됩니다. 직접 attach한 경우 detach는 ctrl+b q입니다(리터럴 ctrl+b는 ctrl+b ctrl+b). herdr agent attach <name>은 UI 전체가 아니라 한 에이전트 터미널에만 붙는 경로입니다.

재시작·정지로 오해하기 쉬운 명령은 역할이 다릅니다.

동작	의미
클라이언트 detach / UI 닫기	서버·패인·에이전트는 유지. 다시 `herdr`로 attach
`herdr session stop`	해당 세션 중지
`herdr server stop`	헤드리스 서버 중지. 서버가 소유한 패인 프로세스도 종료될 수 있음
`herdr pane close` / `herdr workspace close`	레이아웃·워크스페이스 상태 정리(워크트리 체크아웃 삭제가 아님)
`herdr server reload-config`	패인을 죽이지 않고 재로드 가능한 설정만 적용

상태가 “멈춘” 것처럼 보일 때 바로 서버를 죽이면, 실제로 돌고 있던 에이전트 턴도 함께 끊깁니다. 먼저 explain·read로 표시 오진인지 프로세스 정지인지를 가른 뒤, 필요하면 세션/서버를 재시작합니다.

로그는 어디서 보나?

한 줄 답: 에이전트 화면은 herdr agent read / pane read로 보고, Herdr 자체 디버그는 HERDR_LOG와 herdr status·플러그인 로그를 사용합니다.

터미널에 남은 실제 출력은 다음으로 읽습니다.

herdr agent read <target> --source detection
herdr agent read <target> --source recent-unwrapped --lines 120
herdr pane read <pane_id> --source recent --lines 80

읽기 소스 의미는 공식 CLI에 정리되어 있습니다.

visible: 지금 렌더된 화면(UI 피드백용)
recent / recent-unwrapped: 최근 스크롤백(로그용은 unwrapped가 유리)
detection: 스크린 감지에 쓰는 하단 버퍼 스냅샷

Herdr 프로세스 로그 필터는 HERDR_LOG(예: HERDR_LOG=herdr=debug)로 조절합니다. 서버·클라이언트 상태는 herdr status, herdr status server, herdr status client로 확인합니다. 플러그인을 쓰는 경우 herdr plugin log list로 액션 로그를 볼 수 있습니다.

정리하면 순서는 ① agent explain → ② detach인지 서버 정지인지 구분 → ③ agent/pane read와 status·HERDR_LOG입니다. 사이드바만 보고 에이전트를 재시작하기 전에, 감지 스냅샷과 실제 하단 화면이 일치하는지 먼저 확인하시기 바랍니다.

출처

Agents — 상태 권위, blocked 엄격성, explain, 통합 설치
CLI reference — agent/pane read, session·server, HERDR_LOG, attach/detach