multi-agent-mux/PLAN_HERDR.md

📋 PLAN_HERDR.md: herdr 기반 멀티플렉서 백엔드 전환 작업 계획서

이 문서는 기존 tmux 기반의 에이전트 라이프사이클 관리를 Rust 기반의 에이전트 인지형 멀티플렉서인 herdr로 전면 전환하기 위한 도입 배경, 아키텍처 전략 및 상세 작업 단계들을 정의합니다.

---

1. 🔍 도입 배경 및 필요성

현재 운영 중인 tmux 기반 백엔드는 훌륭한 호환성을 제공하지만, 다음과 같은 구조적 한계와 간헐적인 프롬프트 유실 오류(Prompt-lock)를 동반합니다.

🔴 기존 tmux 환경의 한계

• 대략적인 정적 상태 감지 (Coarse Quiescence): 입력을 주입하기 전에 터미널이 키를 수락할 수 있는 휴지 상태인지 확인하기 위해, 셸 스크립트 상에서 capture-pane을 0.1~0.5초 주기로 돌려 화면 변경 여부를 체크합니다. 이로 인해 CPU 자원이 급증하는 멀티 에이전트 구동 상황에서 입력을 유실하거나 Enter 키가 씹히는 현상이 발생합니다.
• TUI 모달 상태 기계 파싱의 비효율: 에이전트가 띄운 다이얼로그(예: 인증, 신뢰 확인)를 인식하기 위해 터미널 하단 20줄의 문자열을 정규식으로 직접 파싱하므로, 에이전트 버전업에 따른 TUI 레이아웃 변경에 매우 취약합니다.

🟢 herdr 도입 시 기대 효과

• PTY 레벨의 밀리초(ms) 단위 이벤트 제어: herdr은 Rust 네이티브로 작성되어 PTY(가상 터미널) 입출력 스트림의 유휴 상태를 서브-밀리초 레벨로 감지합니다. 이로 인해 프롬프트 주입 실패 및 명령 유실 오류가 근본적으로 제로(0)에 가깝게 줄어듭니다.
• 에이전트 상태 인지 API: 에이전트 프로세스의 상태(Working, Idle, Blocked, Done)를 멀티플렉서 레벨에서 해석해 소켓 API로 제공하므로, 지저분한 화면 파싱 코드 없이 정교한 자율 관제가 가능합니다.

---

2. 🔀 형상 관리 및 배포 전략

두 백엔드(tmux/herdr)를 단일 코드베이스에서 듀얼 스위칭(if/else) 방식으로 지원하면 코드가 과도하게 무거워지고 버그 가능성이 높아집니다. 따라서 독립된 브랜치 구조로 깨끗하게 이원화하여 제공합니다.

• main 브랜치 (tmux 기반):
  • 목표: 어디서나 즉시 실행 가능한 고호환성 프로덕션 버전.
  • 의존성: 추가 설치가 필요 없는 표준 tmux 환경.
• herdr 브랜치 (herdr 기반):
  • 목표: 대화식 락 오류가 완벽히 통제되는 워크스테이션(macOS/Linux) 최적화 고안전성 버전.
  • 의존성: herdr CLI 및 Unix 소켓 API 환경.

---

3. 🎯 상세 구현 마일스톤 및 작업 계획

📍 Milestone 1: 개발 환경 구성 및 의존성 진단

• 브랜치 격리: git checkout -b herdr 브랜치 생성 및 격리 개발 공간 확보.
• 인스톨러 개정 (deploy/install_mam.sh):
  • 호스트 의존성 체크 대상에 herdr 추가 (tmux 진단 제거).
  • herdr이 미설치된 경우, 공식 설치 가이드라인(https://herdr.dev/install.sh) 안내 출력 및 조기 종료 처리.
  • .mam/ 격리 폴더 및 환경설정 배포 규칙을 herdr 스펙에 맞게 조정.

📍 Milestone 2: 로우레벨 어댑터 전면 리팩토링 (lib.sh)

• 명령어 매핑: lib.sh 내의 모든 tmux API 호출을 herdr 명령으로 전면 개정.
  • _tmux new-session ➡️ herdr run -d --name "$SESSION_NAME" -- "$CMD_FULL"
  • _tmux capture-pane ➡️ herdr capture --name "$SESSION_NAME"
  • _tmux send-keys ➡️ herdr send-keys --name "$SESSION_NAME" "$KEYS"
  • _tmux kill-session ➡️ herdr kill --name "$SESSION_NAME"
• 정적 상태 감지 함수 재작성 (_pane_quiescent):
  • herdr이 기본 제공하는 세션 상태 조회 API를 파싱하여 PTY 정적 상태 여부를 판별하도록 대폭 경량화 및 고도화.
• 인풋 주입 엔진 고도화 (send_keys_safe):
  • 복잡한 버퍼 제어(set-buffer/paste-buffer) 대신, herdr API를 경유한 다이렉트 프롬프트 주입 방식으로 단순화.

📍 Milestone 3: 에이전트 라이프사이클 관리 도구 이관

• create_session.sh 수정:
  • herdr 기동 방식 및 pane PID 수집 로직 교체.
  • .mam/agent-sessions.yaml 메타데이터 규격을 herdr 사양(예: tmux_server ➡️ herdr_workspace)에 맞게 정렬.
• resume_session.sh 수정:
  • 죽은 herdr 프로세스를 감지하고 저장된 대화 ID와 함께 herdr run으로 복원하는 흐름 이식.
• stop_session.sh 수정:
  • 에이전트 세션의 깔끔한 graceful 종료 및 최종 TUI 캡처 흐름을 herdr 규격으로 전환.

📍 Milestone 4: 검증 및 루프 완주

• 정적 분석: bash -n 및 shellcheck 신규 경고 0건 검증.
• 오케스트레이션 루프 검증 (run_loop.sh):
  • run_loop.sh 내부의 delegate_job_safe 실행을 herdr 세션 기반으로 연동하여 100% 자율 루프 구동 확인.
  • 피어 리뷰어(cline, claude)들로부터 최종 [VERDICT: PASS] 서명 획득.

---

4. 📈 사후 관리 및 형상 병합 정책

• herdr 브랜치의 개발 및 검증이 완주되어 PASS 서명이 누적되면, deploy/INSTALL.md 및 README.md 문서를 개정하여 각 브랜치별 설치 절차를 문서화합니다.
• main 브랜치의 공통 규칙 버그 수정 사항(예: AGENTS.md 수정 등)은 주기적으로 herdr 브랜치로 git merge하여 정책적 일치성을 유지합니다.