docs: add seminar scripts & assets, update Herdr guide and multi-agent documentation

.gitignore

@@ -9,3 +9,7 @@
 
 # Multi-Agent Mux (MAM) runtime databases and isolation cache
 /.mam/
+
+# OS metadata
+.DS_Store
+**/.DS_Store

docs/herdr_manual/herdr_guide.md

@@ -2,7 +2,34 @@
 
 ## 소개
 
-Herdr는 "코딩 에이전트를 위한 tmux"라고 볼 수 있는 터미널 워크스페이스 매니저(agent multiplexer)입니다. 여러 AI 코딩 에이전트(Claude Code, Codex 등)를 각각 실제 터미널 pane에서 실행하면서, 어떤 에이전트가 작업 중인지 / 입력을 기다리는지(blocked) / 끝났는지를 사이드바에서 한눈에 확인할 수 있고, detach해도 백그라운드에서 계속 실행됩니다. Rust로 작성된 로컬 바이너리이며 별도의 GUI 앱이나 클라우드 계정이 필요 없습니다.
+### TMUX란?
+
+**TMUX(Terminal Multiplexer)**는 하나의 터미널 창/세션 안에서 여러 개의 가상 터미널(Window 및 Pane)을 생성, 접근, 제어할 수 있게 해주는 텍스트 기반 터미널 다중화(Multiplexing) 도구입니다.
+
+#### 등장 배경
+- **세션 유실 문제**: 기본 터미널 환경에서는 SSH 원격 접속이 끊어지거나 터미널 창을 닫으면 실행 중이던 장시간 작업(서버 실행, 빌드, 데이터 처리 등)이 강제 종료되는 한계가 있었습니다.
+- **멀티태스킹의 불편함**: 단일 원격 세션에서 여러 작업을 동시에 모니터링하고 제어하려면 매번 새 SSH 접속을 추가로 열어야 했습니다.
+- 이러한 한계를 극복하고 **세션의 지속성(Persistence)**과 효율적인 터미널 멀티태스킹을 지원하기 위해 등장했습니다.
+
+#### 주요 기능
+- **세션 분리 및 재연결 (Detach & Attach)**: 터미널 접속이 끊겨도 백그라운드에서 프로세스가 계속 실행되며, 언제든 기존 세션에 다시 재연결(Attach)하여 이전 상태 그대로 작업을 이어갈 수 있습니다.
+- **화면 분할 및 창 관리 (Window & Pane)**: 하나의 터미널 화면을 상하/좌우 패널(Pane)로 자유롭게 분할하거나 여러 탭(Window)을 생성하여 다중 작업을 한눈에 관리할 수 있습니다.
+- **세션 공유**: 동일한 tmux 세션에 여러 사용자가 동시 접속하여 실시간 화면 공유 및 원격 협업이 가능합니다.
+
+### HERDR란?
+
+**Herdr**는 AI 코딩 에이전트 다중화 및 상태 관리에 특화된 **터미널 워크스페이스 매니저(Agent Multiplexer)**입니다. "코딩 에이전트를 위한 tmux"로서 여러 AI 에이전트(Claude Code, Codex 등)를 개별 터미널 패널(Pane)에서 병렬로 실행하고 통합 제어할 수 있는 Rust 기반 로컬 바이너리 도구입니다.
+
+#### 등장 배경
+- **AI 에이전트 모니터링의 복잡성**: 기존 tmux 환경에서는 여러 AI 에이전트를 동시 실행할 때 각 패널의 입출력 및 완료/대기 상태(`blocked`, `working`, `done`)를 한눈에 파악하기 어려웠습니다.
+- **오케스트레이션 및 자동화 한계**: 스크립트나 외부 오케스트레이터가 개별 터미널 패널과 프로그래밍 방식으로 상호작용(명령 입력, 결과 캡처, 상태 대기)할 표준 인터페이스가 부족했습니다.
+- 이러한 한계를 극복하여 **AI 에이전트 중심의 상태 모니터링**과 **소켓 기반 프로그래밍 제어**가 가능한 터미널 작업 환경을 제공하기 위해 등장했습니다.
+
+#### 주요 기능
+- **에이전트 상태 모니터링 사이드바**: 각 패널에서 실행 중인 에이전트의 상태(`working`, `blocked`, `done`, `idle`)를 사이드바에서 한눈에 확인 가능합니다.
+- **소켓 API & CLI 프로그래밍 제어**: CLI 및 소켓 인터페이스를 통해 명령 전송(`pane run`), 결과 읽기(`pane read`), 상태 대기(`wait agent-status`) 등 자동화 연동을 지원합니다.
+- **세션 지속성 및 원격 재연결 (Detach & Attach)**: 클라우드 계정이나 GUI 없이 백그라운드 세션을 유지하여 SSH/원격 접속 시에도 기존 에이전트 세션에 그대로 재연결할 수 있습니다.
+- **워크스페이스/세션 격리**: 프로젝트 단위의 워크스페이스(Workspace)와 독립 세션(Session) 분리를 통해 복수의 코딩 작업을 완전히 격리하여 운용할 수 있습니다.
 
 공식 사이트: [herdr.dev](https://herdr.dev)
 
@@ -17,13 +44,12 @@ Herdr는 "코딩 에이전트를 위한 tmux"라고 볼 수 있는 터미널 워
 ## 개념 정리
 
 | 개념        | 설명                                                                                                                |
-|---|---|
+| --------- | ----------------------------------------------------------------------------------------------------------------- |
 | Session   | 지속되는 Herdr 서버 하나(런타임 인스턴스). `herdr`는 기본 세션에 붙고, `herdr --session <name>`으로 named session을 launch-or-attach 할 수 있음 |
 | Workspace | 세션 안의 최상위 프로젝트 컨테이너. 보통 repo/작업 단위로 하나씩                                                                           |
 | Tab       | workspace 안의 레이아웃                                                                                                 |
 | Pane      | 실제 터미널 하나                                                                                                         |
 | Agent     | Herdr가 pane 안에서 인식하는 프로세스 (Claude Code, Codex 등). 상태: blocked/working/done/idle/unknown                           |
-| Channel | Herdr 바이너리 자체의 업데이트 트랙 (stable/preview) — session과 무관한 별개 개념 |
 
 ## 주요 단축키
 
@@ -68,7 +94,7 @@ Herdr의 세션은 launch-or-attach 모델이라 이 한 줄로 세션이 없으
 attach된 pane 안에서:
 
 ```bash
-claude
+claude --dangerously-skip-permissions
 ```
 
 (테스트용으로 권한 프롬프트를 건너뛰려면 `claude --dangerously-skip-permissions`. 신뢰된 환경에서만 사용 권장.)
@@ -85,7 +111,7 @@ herdr --session new_session agent get claude
 텍스트 입력 + Enter 제출을 원자적으로 수행:
 
 ```bash
-herdr --session new_session pane run <pane_id> "정렬 프로그램을 작성해줘"
+herdr --session new_session pane run <pane_id> "파이썬으로 정렬 프로그램을 작성해줘"
 ```
 
 ### 4. Claude의 결과 화면 출력

docs/introduction to a2a protocol/agent2agent-protocol_combined_kr.md

@@ -6,10 +6,6 @@ AI 에이전트 간의 소통이 단절되는 상황을 방지하기 위해 왜
 
 ![](lab/canary_projects/multi-agent-paper/docs/introduction%20to%20a2a%20protocol/assets/images/agent2agent-protocol_01_01_why-agents-need-a-protocol_01.svg)
 
-**프로토콜**은 이러한 혼란을 방지하는 플레이북입니다. 프로토콜은 에이전트가 자신을 소개하는 방식(기능), 작업을 요청하는 방식(요청), 진행 상황을 공유하는 방식(스트리밍), 안전하게 실패하는 방식(에러), 권한을 증명하는 방식(권한 부여)을 표준화합니다. 프로토콜이 준비되면 팀들은 시스템을 한 번만 구축하여 어디서나 재사용할 수 있으므로, 전체 프로세스가 투명하고 안전하며 예측 가능해집니다. 그리고 이것이 바로 A2A가 해결하고자 하는 핵심 과제입니다.
-
-**시작하기에 앞서, 간단하게 생각해 보겠습니다:** A2A는 에이전트들이 예기치 못한 문제 없이 서로 도움을 요청하고 결과를 공유할 수 있도록 마련된 공통 규칙의 집합입니다.
-
 ## A2A란 무엇인가요?
 
 **Agent2Agent (A2A) 프로토콜**은 본래 구글에서 개발된 오픈 표준으로, 서로 다른 팀이나 프레임워크로 구축된 AI 에이전트들이 안전하고 효율적으로 서로를 검색하고 소통하며 협업할 수 있도록 지원합니다. 이 프로토콜은 공통 언어와 상호작용 모델을 제공하여 에이전트들이 서로의 비공개 메모리, 도구, 또는 내부 정보에 직접 접근하지 않고도 구조화된 데이터, 텍스트, 파일을 교환하며 정보를 공유하고 작업을 관리하며 유저의 목표를 달성할 수 있도록 돕습니다.
@@ -821,20 +817,15 @@ curl http://0.0.0.0:8000/.well-known/agent-card.json
 향후 실무형 고급 에이전트를 설계할 때도 다음 핵심 수칙들을 기억하고 준수해 주시기 바랍니다.
 
 - **모든 요소에 고유 ID 배포:** 추적 및 디버깅을 원활하게 하기 위해 태스크, 메시지, 컨텍스트 전체에 UUID 등의 고유 ID를 부여해야 합니다.
-
 - **안정적인 예외 처리:** 서버 다운이나 비정상 실행 시 생으로 에러를 뿜게 두지 말고, 클라이언트가 식별할 수 있도록 규격에 맞춰 에러 객체를 리턴해야 합니다.
-
 - **스펙 완벽 준수:** A2A 프로토콜의 진정한 매력은 강력한 규칙 일관성에서 나옵니다. 조그마한 스펙 일탈도 에이전트 간 상호 호환성을 파괴할 수 있습니다.
-
 - **태스크 중심 설계:** 단순 연산조차 태스크 구조에 감싸서 리턴해 버릇하면 로깅, 모니터링 및 향후 대규모 확장 시 시스템 통합이 매우 쉬워집니다.
-
 - **선 검증 후 로직 처리:** Pydantic 등의 모델을 사용해 최우선으로 들어오는 데이터 형식이 적합한지 검사한 뒤 비즈니스 로직에 전달하십시오.
 
 
 이제 여러분은 완성되어 작동하는 A2A 기초 시스템을 완전히 소유하게 되었습니다. 하지만 이것은 위대한 시작일 뿐입니다. 오늘 구축한 가벼운 에코 에이전트는 향후 마주할 복잡한 설계 기법들의 단단한 기반이 되어 줄 것입니다. 핵심 소통 패턴을 확실하게 익혔으니, 앞으로 마주하게 될 고급 기법들도 이미 알고 있는 지식을 바탕으로 어렵지 않게 쌓아 올리실 수 있습니다. 더 중요한 것은 여러분이 글로벌 A2A 생태계에 성공적으로 합류했다는 사실입니다. 여러분의 에이전트는 이제 규격을 준수하는 타 에이전트들과 자유롭게 통신할 수 있으며, 클라이언트는 세계 각지의 팀들이 공개한 유용한 에이전트들을 자유롭게 검색하여 협업을 요청할 수 있습니다. 이것이 바로 서로 다른 전문적인 에이전트들이 상호 작용하며 복잡한 사회적 문제를 해결해 나가는 A2A 프로토콜이 그리는 미래상입니다.
 
 ---
-
 # A2A SDK 사용법
 
 FastAPI 등을 이용한 직접 구현 방식에서 공식 A2A SDK를 사용한 에이전트 개발 방식으로 업그레이드하는 방법을 알아봅니다. `AgentExecutor`, `DefaultRequestHandler` 등 SDK의 핵심 컴포넌트들과 태스크 라이프사이클 관리법을 이해합니다. 향상된 프로토콜 처리 기능과 상용화 스펙을 갖춘 확장 가능하고 유지 관리가 용이한 에이전트를 구축하는 방법을 학습합니다.

docs/multi-agent-mux 소개/multi-agent-mux 소개.md

@@ -0,0 +1,137 @@
+# Multi-Agent Mux (MAM) Architecture & Orchestration Report
+
+## 1. 개요 (Executive Summary)
+
+현대 AI 에이전트 워크플로우는 세션 타임아웃, 프로세스 격리 부재, 터미널 뷰포트 잘림, 단일 에이전트의 자기 과신(Self-Confidence) 오류 등 다양한 문제점을 내포하고 있습니다. 
+
+**Multi-Agent Mux**는 **Tmux/Herdr** 프로세스 관리자와 **MQTT 메시징 백플레인**을 결합하여, 여러 LLM 에이전트가 안전하게 프로세스를 격리받고 비동기로 이벤트를 주고받으며 다수의 에이전트 간 자율 검증 및 교차 리뷰 루프를 수행할 수 있는 기능을 지원하는 오케스트레이션 스킬 도구 입니다.
+
+---
+
+## 2. 코어 스킬 구성 명세 (Core Skills Inventory)
+
+multi-agent-mux 도구는 다양한 스킬들로 구성되어 있습니다:
+
+*   **`multi-agent-mux-create`**
+    *   지정된 작업 공간에 최적화된 명칭으로 독립된 에이전트 세션을 새로 구동하고, 초기 메타데이터를 원자적으로 등록합니다.
+    *   에이전트 구동 즉시 워크스페이스 맥락과 자신의 역할(Role)을 스스로 파악하도록 자동 온보딩 지시서 주입을 지원합니다.
+*   **`multi-agent-mux-resume`**
+    *   이전에 중지되거나 중단된 에이전트의 대화 식별자(UUID)를 디스크 및 레지스트리에서 추적하여 이전 문맥 그대로 세션을 복원합니다.
+    *   에이전트 기동 직후 필요한 권한 우회 및 복구 수락 대화상자를 백그라운드 키스트로크 주입으로 자동 처리합니다.
+*   **`multi-agent-mux-stop`**
+    *   에이전트 TUI 화면 뷰포트를 최종 스냅샷으로 보존하고 `Safe Exit Key` ➡️ `SIGTERM` ➡️ `SIGKILL` 다단계 수순으로 안전하게 정지시킵니다.
+    *   에이전트의 대화 파일(JSONL/DB)을 디스크에 영구 보존하여 추후 언제든지 재개(`status=stopped`)할 수 있도록 상태를 기록합니다.
+*   **`multi-agent-mux-status`**
+    *   실제 실행 중인 OS 프로세스 현황과 레지스트리 기록 간의 불일치(Drift) 및 동작 상태를 안전하게 즉시 표기합니다.
+    *   데이터베이스나 프로세스 상태 변경을 유발하지 않는 순수 읽기 전용(Read-only) 모드로 시스템의 정합성을 검증합니다.
+*   **`multi-agent-mux-monitor`**
+    *   백그라운드에서 지속 구동되어 죽은 세션 격하, 신규 세션 자동 등록, 디스크 로그와 UUID 동기화를 자동 화해(Reconciliation)합니다.
+    *   운영체제 Tmux/Herdr 런타임과 YAML 레지스트리 데이터 간의 괴리를 실시간으로 자동 복구합니다.
+*   **`multi-agent-mux-delegate-job`**
+    *   타 에이전트에게 비동기 태스크를 위임하고, MQTT 메시징 백플레인을 통해 실행 상태(`started` ➡️ `completed`/`error`)를 관찰합니다.
+    *   단일 작업 위임(`direct`)부터 에이전트 간 1:1 토론(`discuss`), 검증 루프(`loop`)까지 다양한 비동기 작업 위임 패턴을 처리합니다.
+*   **`multi-agent-mux-loop`**
+    *   설계(Planner) ➡️ 구현(Creator) ➡️ 교차 검수(Reviewers)로 이어지는 자율 개발 및 검증 순환 루프를 오케스트레이션합니다.
+    *   지정되거나 자동 수집된 모든 리뷰어의 만장일치 `[VERDICT: PASS]` 판정을 얻을 때까지 자율 교정 작업을 자동 반복합니다.
+
+---
+
+## 3. Multi-Agent Orchestration을 위한 핵심 기능 및 구현 방법 (부재 시 장애 예시 포함)
+
+다중 에이전트 협업 환경을 구축하기 위해 필수적이었던 8가지 주요 기능들을 살펴봅시다:
+
+### 🔑 1) 프로세스 및 실행 환경 격리 (Environment Isolation)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *인증 및 설정 파일 오염*: 서로 다른 에이전트(예: Claude와 Agy)가 동일한 기본 홈 디렉토리(`~/.gemini`, `~/.claude`)를 공유하면, 한 에이전트가 설정을 덮어쓰거나 로그인 세션을 건드려 상대방 에이전트의 인증이 갑자기 해제되는 장애가 발생합니다.
+    *   *초기 대화상자 차단 패닉*: 예컨대 Agy 에이전트가 격리되지 않은 환경에서 구동될 경우 약관 동의(TOS)나 테마 설정 마법사 화면이 매번 출력되어 프롬프트 입력창이 상시 차단(Prompt Lockout)되는 현상이 일어납니다.
+*   **필요성**: 에이전트 간 설정 파일, 캐시, 세션 이름 및 환경 변수 충돌을 물리적으로 막아야 합니다.
+*   **구현 방법**:
+    *   `herdr --session <name>` 명령을 활용해 에이전트 그룹마다 완전히 독립된 소켓과 서버 세션을 부여했습니다.
+    *   에이전트별로 워크스페이스 내에 임시 홈 디렉토리(`.mam/agent_homes/<UUID>`)를 프로비저닝하고 `HOME` 또는 `CLAUDE_CONFIG_DIR` 환경변수를 덮어씌워 완벽히 독립된 가상 홈 디렉토리를 제공했습니다.
+
+### 🗃️ 2) 에이전트 관리를 위한 이중 레지스트리 분리 (`agent-sessions.yaml` vs `agent-sessions.db`)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *YAML 단독 사용 시*: 여러 에이전트와 모니터링 프로세스가 동시 쓰기를 감행하다 텍스트 파일이 도중에 깨져 `YAML parsing syntax error`가 발생하여 전체 시스템 레지스트리가 즉시 마비됩니다.
+    *   *DB 단독 사용 시*: 바이너리 데이터베이스로만 세션을 관리할 경우 개발자나 외부 도구가 `git status`, `cat`, 마크다운 뷰어 등으로 현재 에이전트 세션의 상태나 장애 원인을 직관적으로 디버깅할 수 없어 가시성이 완전 상실됩니다.
+*   **필요성**: 직관적 디버깅 가시성(Human-Readability)과 고성능 동시 트랜잭션 안전성(Transactional Integrity)이라는 두 가지 목적을 동시에 달성해야 합니다.
+*   **구현 방법**:
+    *   `.mam/agent-sessions.db` (SQLite)를 내부 동시성 제어 및 원자적 상태 변경의 진실 원천(Single Source of Truth)으로 지정했습니다.
+    *   DB 트랜잭션 커밋 완료 직후 PyYAML 기반 헬퍼 함수(`atomic_dump_yaml`)를 통해 정제된 데이터를 `.mam/agent-sessions.yaml` 파일로 원자적 동기화 덤프(`os.replace`)하여, 사람과 시스템 모두 만족하는 이중화 구조를 구축했습니다.
+
+### 🔄 3) 역할별 에이전트 페르소나 기반 자율 품질 합의 및 리뷰 루프 (Persona-based Autonomous Consensus Loop)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *단일 에이전트 자기 환각(Hallucination) 머지*: 코드 작성 에이전트 혼자 작업을 진행하고 자가 승인(Self-Approve)하도록 두면, 자신이 유발한 메모리 누수, 잘못된 예외 처리, 안 보이는 타입 오류를 "정상 구현됨"으로 착각하고 버그가 포함된 코드를 저장소에 그대로 커밋/머지하는 치명적 결과가 초래됩니다.
+*   **필요성**: 객관적인 제3의 에이전트들이 부여된 역할(Planner, Creator, Reviewer) 및 특화된 페르소나(Persona)에 따라 엄격한 품질 기준(DoD)으로 교차 검증하고 승인해야만 코드에 반영되도록 제어해야 합니다.
+*   **구현 방법**:
+    *   **Planner(설계)**, **Creator(구현)**, **Reviewers(검수)**의 페르소나와 역할을 엄격히 분리했습니다.
+    *   리뷰어 리포트 맨 마지막 단독 행에 `[VERDICT: PASS]` 또는 `[VERDICT: NOT PASS]` 토큰 입력을 규칙화하고, 파서가 모든 active 리뷰어의 만장일치 PASS를 확인할 때까지 자동으로 교정 수순을 반복(`run_loop.sh`)하도록 오케스트레이션했습니다.
+
+### 📋 4) 작업 단위 구분 및 관리를 위한 태스크 데이터 구조화 (Job Schema & Task Management)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *작업 유실 및 상태 추적 불가*: 작업 위임 데이터 모델이 정의되어 있지 않으면, Orchestrator가 어떤 에이전트에게 무슨 지시문(`brief.md`)을 전달했는지, 현재 상태가 진행 중(`running`)인지, 성공(`completed`)인지, 에러(`error`)인지 추적할 수 없어 작업이 공중에 뜬 '고아(Orphaned) 상태'로 방치됩니다.
+    *   *중복 태스크 수락 및 Race Condition*: 동일한 작업을 둘 이상의 에이전트가 동시에 중복 수락(Claim)하여 서로의 코드를 덮어쓰거나 엉뚱한 결과물을 교차 전송하는 상충 장애가 일어납니다.
+*   **필요성**: 에이전트 간 분동(Delegation)되는 작업 단위를 정형화하고, 각 태스크의 생명주기 및 충돌 없는 클레임 관리를 보장해야 합니다.
+*   **구현 방법**:
+    *   모든 위임 태스크마다 고유 ID(`job_id`)를 발급하고 `.mam/jobs/<job_id>.json` 파일에 작업 스키마(주 작업자, 부여된 역할, 실행 타입, 보안 토큰, 생명주기 상태 등)를 명확히 데이터 구조화했습니다.
+    *   `registry.py` 모듈을 통해 작업 등록 및 클레임 시 `fcntl` 파일 자문 잠금(Advisory Lock)을 적용하여 다중 세션 간 작업 중복 수락 경쟁을 원자적으로 제어했습니다.
+
+### 📡 5) 비동기 메시징 및 이벤트 백플레인 (Async Messaging Backplane)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *동기 블로킹 타임아웃 폭망*: 동기식 HTTP 요청으로 위임할 경우, 코드 구현 및 복잡한 리팩토링으로 10분 이상 소요되는 에이전트 작업을 기다리다가 오케스트레이터의 HTTP 커넥션 타임아웃이 발생하여 전체 작업이 붕괴됩니다.
+    *   *블라인드 진행 장애*: 비동기 이벤트 채널이 없으면 에이전트가 백그라운드에서 무한 루프에 빠졌는지, 정상 동작 중인지 알 수 있는 진행 표기(`progress`)를 수신할 수 없습니다.
+*   **필요성**: 위임자와 실행자 간에 커넥션을 묶어두지 않고 비동기로 실시간 이벤트 및 중간 진행 상태를 주고받아야 합니다.
+*   **구현 방법**:
+    *   경량 메시징 표준인 **MQTT 브로커**를 백플레인으로 채택하고 `publish_event.py`와 `job_subscriber.py`를 연결했습니다.
+    *   구독을 먼저 개시하는 *Subscribe-before-Publish* 규칙과 terminal 이벤트의 `retain=True` 설정으로 메시지 유실을 방지했습니다.
+    *   Payload 내에 단조 증가 시퀀스 번호(`seq`)와 HMAC-SHA256 서명을 포함시켜 리플레이 공격 및 메시지 변조를 차단했습니다.
+
+### 📸 6) 컨텍스트 보존 및 화면 유실 방지 (Pane Snapshotting & Markdown Bridge)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *뷰포트 잘림으로 인한 디버그 정보 유실*: 터미널(TUI) 스크롤백 한계(예: 2000줄)로 인해 에이전트가 출력한 핵심 디버그 스택 트레이스나 긴 린트 에러 메시지가 상단으로 밀려 올라가 유실됩니다.
+    *   *입력 깨짐 및 줄바꿈 돌발 실행*: 100줄이 넘는 복잡한 프롬프트나 한글/특수문자를 터미널 입력창에 직접 문자열로 보낼 경우, 멀티바이트 깨짐이나 줄바꿈 문자로 인해 에이전트가 입력을 받다 말고 중간에 명령어를 기습 실행하는 참사가 일어납니다.
+*   **필요성**: 장시간 터미널 출력 히스토리를 완벽하게 보존하고, 정교한 입력 데이터를 손상 없이 전달해야 합니다.
+*   **구현 방법**:
+    *   **3단계 Pane Snapshotting** (작업 전, 루프 중 주기적 캡처, 작업 종료 후)을 적용해 터미널 출력을 파일로 상시 백업했습니다.
+    *   복잡한 지시문이나 리뷰 리포트는 TUI 입력창에 직접 타이핑하지 않고, `.mam/jobs/<id>/brief.md` 또는 `report.md` 파일로 작성한 뒤 에이전트에게 마크다운 파일 경로 포인터만 전송하는 **파일 기반 통신 구조**를 구축했습니다.
+
+### 🔒 7) 이슈 트래킹 및 감사를 위한 원자적 상태 이력 관리 (Issue Tracking & Atomic Concurrency)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *이슈 추적 불능 및 블랙박스 장애*: 에이전트가 작업 도중 에러(exit code non-zero, 프롬프트 잠금, API 실패 등)로 붕괴했을 때, 어떤 세션에서 무슨 이유로 정지되었는지 이력이 남지 않아 문제 발생 지점을 찾지 못하고 원인 분석이 불가능해집니다.
+    *   *갱신 유실(Lost Update)로 인한 감사 이력 파손*: 에이전트 A가 에러 발생 원인과 감사 로그(`status=error`, `stop_reason`)를 덤프하는 순간, 다른 모니터링 프로세스가 1초 전의 예전 정상 스냅샷으로 파일/DB를 덮어씌워 장애 이력이 완전히 증발합니다.
+*   **필요성**: 에이전트 작업 도중 예외나 문제 발생 시, 이슈 트래커(Issue Tracker)처럼 어느 지점에서 어떤 원인(StackTrace, Pane Snapshot, Job Detail)으로 오류가 났는지 완벽히 추적(Traceability)할 수 있어야 하며, 이 감사 데이터가 동시 쓰기 충돌로 훼손되지 않도록 원자적으로 보호되어야 합니다.
+*   **구현 방법**:
+    *   모든 비동기 위임 작업 및 세션 상태 변경 시 고유 작업 ID(`job_id`), 담당 에이전트명, 발생 시각, 상세 원인(`detail`), 뷰포트 스냅샷(`pane.capture`)을 `.mam/jobs/<id>/` 디렉토리 및 `.mam/agent-sessions.db`에 감사 이력(Audit Trail)으로 즉시 저장하도록 설계했습니다.
+    *   SQLite의 `BEGIN IMMEDIATE` 배타 트랜잭션과 `atomic_dump_yaml`(`os.replace`)을 조합하여, 장애 원인 추적 이력 데이터가 다중 프로세스 충돌로 덮어씌워지거나 손상되지 않도록 원자적 동시성을 완벽히 제어했습니다.
+
+### 🚀 8) 자동화된 배포 환경 구성 및 프로비저닝 (Deployment Automation & Provisioning)
+*   **기능 부재 시 발생하는 문제 (구체적 장애 예시)**:
+    *   *환경설정 파편화 및 접속 불능*: 서버나 에이전트 런타임마다 필수 환경변수(`HERDR_SESSION_NAME`, MQTT 엔드포인트 등)가 누락되거나 수동 설정 오차로 인해, 에이전트 간 통신이 안 되거나 타 격리 세션에 오접속하여 운영 데이터를 덮어쓰는 시스템 파손 발생.
+    *   *배포 재현성 상실 및 임포트 에러*: 파이썬 가상환경(`.venv`)이나 필수 라이브러리(`paho-mqtt`, `pyyaml`) 설치가 누락된 채 에이전트 세션이 기동되어, 작업 위임 직후 `ModuleNotFoundError`로 파이프라인이 즉시 마비되는 장애.
+*   **필요성**: 개발, 테스트, 운영 환경 전체에서 동일한 구동 환경과 패키지 의존성을 신속히 자동 구축하고 배포 재현성을 보장해야 합니다.
+*   **구현 방법**:
+    *   `deploy/generate-env.sh` 자동화 스크립트를 제공하여 `.env` 및 `HERDR_SESSION_NAME` 환경 변수를 1초 만에 자동 생성하고 시스템에 유기적으로 주입하도록 구성했습니다.
+    *   `.venv` 가상환경 구성 및 `requirements.txt` 의존성 패키지 자동 프로비저닝 단계를 선행 통합하여 완벽히 재현 가능한 배포 체계를 구현했습니다.
+
+---
+
+## 4. 실전 트러블슈팅 및 튜닝 사례 (Troubleshooting Cases)
+
+시스템 구축 및 검증 과정에서 직접 발굴하여 해결한 주요 실전 기술 사례입니다.
+
+### 🛠️ 사례 1: Agy(Antigravity) 에이전트의 TOS/약관 동의 화면 차단 문제 해결
+*   **증상**: `agy` 에이전트를 격리 홈(`HOME=$root`)에서 실행했을 때, 구동 시마다 **"Terms of Service & Data Use" 약관 동의 및 테마 선택 마법사**가 출력되며 프롬프트 입력이 블로킹됨.
+*   **원인**: `agy` 에이전트가 약관 및 초기 설정 상태를 사용자 계정 디렉토리(`~/.gemini/antigravity`, `~/Library/Application Support/Antigravity`, macOS `Preferences` plist 등)에서 가져오는데, 기존 격리 프로비저닝 로직에서 해당 경로들의 심볼릭 링크 시딩이 누락됨.
+*   **해결**: `lib.sh::provision_isolation` 함수를 수정하여 macOS의 `Preferences`(`com.google.antigravity.plist` 등), `Application Support/Antigravity`, `Group Containers`와 Linux의 XDG 표준 경로(`~/.config/Antigravity`, `~/.local/share/Antigravity`)를 격리 홈 디렉토리로 자동 링킹하도록 확장함으로써 플랫폼에 관계없이 약관 안내 화면을 건너뛰도록 원천 해결함.
+
+### 🛠️ 사례 2: TUI 입력 버퍼 감지 오탐(False-Positive) 완화
+*   **증상**: `cline`이나 `claude` 에이전트에 긴 프롬프트(git diff 포함 지시문 등)를 주입할 때 `send_keys_safe: paste not visible` 타임아웃 오류가 발생하며 작업 위임이 중단됨.
+*   **원인**: `send_keys_safe` 유틸리티가 입력 텍스트의 끝 24글자 마커(`marker_norm`)가 화면 뷰포트에 출현했는지 검증하는데, `cline` TUI 등 일부 환경은 긴 텍스트 입력 시 입력창 스크롤로 인해 마커가 화면 밖으로 밀려나 오탐(False-Positive)이 발생함.
+*   **해결**: `cline` 및 `claude` 세션의 경우 실제 페이스트는 성공했으나 스크롤아웃으로 인해 검증이 실패하는 특성을 고려해, 엄격한 마커 노출 검사를 생략하고 C-m(엔터) 제출 대기 루프로 직행하도록 `lib.sh` 검증 조건문을 완화하여 오케스트레이션 루프의 연속성을 확보함.
+
+---
+
+## 5. 결론 및 향후 발전 방향
+
+본 프레임워크는 프로세스 격리, 파일 기반 원자적 레지스트리, 비동기 MQTT 메시징, 그리고 마크다운 파일 통신을 결합함으로써 **다종 AI 에이전트를 결합한 안정적이고 강인한 자율 협업 오케스트레이션**을 성공적으로 입증했습니다.
+
+추후 가상환경 의존성 자동 점검 강화, HMAC 보안 인증 키 자동 교환(FW-N6), 그리고 NFS 환경에서의 파일 락 추상화 레이어 보완을 통해 더욱 확장성 높은 에이전트 플랫폼으로 진화할 수 있습니다.

docs/참고 자료.md

@@ -0,0 +1,8 @@
+- https://twentytwentyone.tistory.com/454
+- Agent SDK
+	- [Claude](https://jjeongil.tistory.com/3360#google_vignette)
+	- [OpenAI](https://openai.github.io/openai-agents-python/)
+	- [Google ADK](https://github.com/google/adk-python)
+	- [Antigravity SDK](https://antigravity.google/product/antigravity-sdk)
+- [crewai a2a protocol](https://docs.crewai.com/v1.15.5/en/learn/a2a-agent-delegation)
+- [LangChain and LangGraph](https://www.youtube.com/watch?v=W_uwR_yx4-c)

lib/make_slide_for_260724_seminar/SCRIPTS.md

@@ -0,0 +1,175 @@
+# MAM demo
+
+https://git.godopu.com/tmpl/multi-agent-mux
+
+- resume
+	```bash
+	/multi-agent-mux-resume
+	```
+
+- stop
+	```bash
+	/multi-agent-mux-resume
+	```
+
+- create
+	```
+	/multi-agent-mux-create --no-isolate --onboard 다음 새로운 에이전트를 생성해줘.
+	```
+
+- delegate-job
+	```bash
+	/multi-agent-mux-delegate-job agy creator에게 파이썬 초급자를 대상으로 정렬 학습을 위한 예시 코드 작성을 지시해줘.
+	```
+
+- loop
+	```bash
+	/multi-agent-mux-loop --plan --all-reviewer /goal 생성된 예시를 바탕으로 수업에 사용할 학습 자료를 만들어줘. 다음 조건을 충족하여야해. 
+	
+	- 파이썬 초급자가 보더라도 이해하기 쉽도록 실생활 예시를 통해 상세한 설명이 수록되어야 함
+	- 모든 예시의 주요 코드에 대한 line 별 코드 설명이 있어야 함
+	```
+
+# herdr 사용법
+
+실습: 세션 생성 → Claude 실행 → 소켓으로 프롬프트 전달 → 결과 확인
+
+### 1. 현재 디렉터리를 cwd로 하는 새 세션 `new_session` 생성
+
+```bash
+cd <현재 작업 디렉터리>
+herdr --session new_session
+```
+
+Herdr의 세션은 launch-or-attach 모델이라 이 한 줄로 세션이 없으면 생성하고 동시에 attach까지 됩니다.
+
+### 2. 생성된 세션에서 Claude 실행
+
+attach된 pane 안에서:
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+(테스트용으로 권한 프롬프트를 건너뛰려면 `claude --dangerously-skip-permissions`. 신뢰된 환경에서만 사용 권장.)
+
+### 3. 다른 터미널에서 herdr 명령으로 프롬프트 전달 (직접 타이핑 아님)
+
+새 터미널에서 에이전트 목록과 pane_id 확인:
+
+```bash
+herdr --session new_session agent list
+herdr --session new_session agent get claude
+```
+
+텍스트 입력 + Enter 제출을 원자적으로 수행:
+
+```bash
+herdr --session new_session pane run <pane_id> "파이썬으로 정렬 프로그램을 작성해줘"
+```
+
+### 4. Claude의 결과 화면 출력
+
+완료될 때까지 기다렸다가 읽기:
+
+```bash
+herdr --session new_session wait agent-status <pane_id> --status idle
+herdr --session new_session pane read <pane_id> --source recent --lines 150
+```
+
+현재 화면만 바로 보기:
+
+```bash
+herdr --session new_session pane read <pane_id> --source visible --lines 80
+```
+
+`--session new_session`을 매번 붙이는 대신 `export HERDR_SESSION=new_session`으로 환경변수를 설정하면 이후 명령에서 생략 가능합니다.
+
+# a2a 실습
+## 🗺️ 5단계 학습 로드맵 (Learning Roadmap)
+
+### [Step 01] crewai를 통한 multi-agent 시작하기
+*   **디렉토리**: [lib/crewai-example/](crewai-example/)
+*   **학습 목표**: CrewAI 프레임워크와 로컬 Ollama 모델을 활용해 두 개 이상의 에이전트(기술 연구원, 작가)가 순차적으로 협업하여 분석 보고서를 도출하는 기초 워크플로우를 이해합니다.
+*   **실행**:
+    ```bash
+    ./lib/crewai-example/run.sh
+    ```
+
+- https://docs.crewai.com/v1.15.1/ko/tools/overview
+### [Step 02] a2a 기초 알아보기 (FastAPI 기반 직접 구현)
+*   **디렉토리**: [lib/a2a-echo-example/](a2a-echo-example/)
+*   **학습 목표**: SDK 도움 없이 원시 FastAPI를 사용해 JSON-RPC 2.0 프로토콜, 탐색 엔드포인트(`/.well-known/agent-card.json`), 메시지 수발신 규약을 직접 작성해보며 A2A 프로토콜의 밑바닥 동작 원리를 이해합니다.
+*   **실행**:
+    ```bash
+    # 터미널 1: 에코 에이전트 서버 구동
+    ./lib/a2a-echo-example/run.sh server
+    # 터미널 2: 테스트 메시지 클라이언트 실행
+    ./lib/a2a-echo-example/run.sh client
+    ```
+
+### [Step 03] a2a sdk 알아보기 (공식 SDK 전환)
+*   **디렉토리**: [lib/a2a_sdk/](a2a_sdk/)
+*   **학습 목표**: 정식 `a2a-sdk`를 적용하여 `AgentExecutor` 기반으로 비즈니스 에코 로직을 구현합니다. 복잡한 소통 인프라(FastAPI 라우트 마운트, 에러 처리, 큐 통신 등)가 SDK에 의해 얼마나 깔끔하게 자동화되는지 비교 체험합니다.
+*   **실행**:
+    ```bash
+    # 터미널 1: SDK 기반 에코 서버 구동
+    ./lib/a2a_sdk/run.sh server
+    # 터미널 2: SDK 규격 호환 클라이언트 실행
+    ./lib/a2a_sdk/run.sh client
+    ```
+
+### [Step 04] a2a를 이용하여 multi agent 구현해보기
+*   **디렉토리**: [lib/a2a-ollama-example/](a2a-ollama-example/)
+*   **학습 목표**: 앞선 SDK 뼈대에 실제 로컬 생성형 AI 모델인 `gemma4:31b-cloud`를 이식하여, 들어오는 질문에 지능적으로 답하는 실질적인 AI 비서 에이전트를 조립합니다.
+*   **실행**:
+    ```bash
+    # 터미널 1: Ollama 연동 AI 에이전트 서버 구동
+    ./lib/a2a-ollama-example/run.sh server
+    # 터미널 2: 질문 전송 테스트
+    ./lib/a2a-ollama-example/run.sh client "프랑스의 수도는 어디야?"
+    ```
+
+### [Step 05] 작업 할당은 어떻게 이루어질까? (오케스트레이션)
+*   **디렉토리**: [lib/advanced-a2a-ollama-example/](advanced-a2a-ollama-example/)
+*   **학습 목표**: 사용자의 복잡한 질의를 받으면 LLM을 통해 어떤 에이전트가 적합한지 동적으로 판별(분류)하고, 대상 전문 에이전트(Chat Agent 또는 Coder Agent)를 호출하여 답변을 취합하는 고급 오케스트레이션 설계 패턴을 습득합니다.
+*   **실행**:
+    ```bash
+    # 터미널 1: 두 독립 에이전트(Chat:8001, Coder:8002) 서버 동시 구동
+    ./lib/advanced-a2a-ollama-example/run.sh server
+
+    # (선택) 개별 터미널에서 서버를 분리 구동하고 싶을 때
+    # 터미널 1A: Chat 에이전트만 구동 (Port 8001)
+    ./lib/advanced-a2a-ollama-example/run.sh server chat
+    # 터미널 1B: Coder 에이전트만 구동 (Port 8002)
+    ./lib/advanced-a2a-ollama-example/run.sh server coding
+
+    # 터미널 2: 오케스트레이터 작동 및 분류 인터랙션 실행
+    ./lib/advanced-a2a-ollama-example/run.sh client "프랑스의 수도는 어디야?"
+    ```
+
+### [Step 06] 동적 라우팅과 서비스 탐색 (Dynamic Binding)
+*   **디렉토리**: [lib/advanced-dynamic-a2a-ollama-example/](advanced-dynamic-a2a-ollama-example/)
+*   **학습 목표**: 하드코딩 라우팅의 한계를 이해하고, 런타임에 분산된 에이전트들의 명세 카드(`agent-card.json`)를 동적으로 검색(Discovery)해 스킬 목록을 추출하고, 최적 매칭 노드에 실시간으로 메시지를 라우팅 및 바인딩하는 기법을 실증합니다.
+
+* **터미널 A (Chat 에이전트 - Port 9501)**:
+```bash
+OLLAMA_MODEL="gemma4:31b-cloud" ./lib/advanced-dynamic-a2a-ollama-example/run.sh server chat
+```
+
+* **터미널 B (Coder 에이전트 - Port 9502)**:
+```bash
+OLLAMA_MODEL="gemma4:31b-cloud" ./lib/advanced-dynamic-a2a-ollama-example/run.sh server coding
+```
+
+* **터미널 C (Translator 에이전트 - Port 9503)**:
+```bash
+OLLAMA_MODEL="gemma4:31b-cloud" ./lib/advanced-dynamic-a2a-ollama-example/run.sh server translate
+```
+
+* **클라이언트 질의 터미널 (오케스트레이터 클라이언트로 번역 질문)**:
+```bash
+# 오케스트레이터가 번역에 맞는 스킬을 찾아 Translator(9503 포트)로 매칭하는 것을 확인
+OLLAMA_MODEL="gemma4:31b-cloud" ./lib/advanced-dynamic-a2a-ollama-example/run.sh client "안녕하세요를 영어로 번역해줘."
+```
+

lib/make_slide_for_260724_seminar/chapters/6_summary.md

@@ -1,7 +1,6 @@
 ---
 marp: true
 ---
-
 # 특강 최종 요약
 
 ## AI Multi-Agents 오케스트레이션 기술 동향 및 사례

lib/make_slide_for_260724_seminar/lecture_summary.md

@@ -53,6 +53,6 @@
 ### <AI Multi-Agents 오케스트레이션 기술 동향 및 사례>
 * **AI 에이전트 구현을 위한 3대 핵심 엔지니어링 기법**: 프롬프트, 컨텍스트, 하네스 엔지니어링
 * **AI Agent 기능 확장**: MCP & SKILL  
-* **멀티 에이전트 협업 체계 및 오케스트레이션 인프라**: TMUX, crewAI, LangGraph 
+* **멀티 에이전트 협업 체계 및 오케스트레이션 인프라**: HERDR, crewAI, LangGraph 
 * **에이전트 상호운용성 확보를 위한 표준**: ACP, A2A
 * **지능형 사물인터넷 (AIoT) 및 gRPC 기술 동향**

paper_draft/DRAFT_PLAN.md

@@ -88,6 +88,7 @@ AIoT 서비스 환경에서 멀티 에이전트 오케스트레이션(Multi-Agen
 
 2. **연결 계층의 동적 바인딩 및 다유형 메시지 교환 장벽 (Dynamic Binding & Multi-Type Messaging Barrier - 연결 축)**
    - **동적 파라미터 바인딩 결여**: AIoT 서비스 환경에서 에이전트가 물리 장치를 제어하거나 전용 인공지능 모델(예: 스마트 팜의 질병 진단용 지도학습 모델 등)의 추론 결과를 획득하기 위해서는, 대상 시스템의 API 주소, 파라미터 규격, 제어 명령 명세를 사전에 정확히 매핑하여야 한다. 그러나 관리자가 이를 매번 수작업으로 매핑하는 것은 확장성 측면에서 비현실적이며, 새로운 에이전트가 네트워크에 진입할 때마다 물리 기기 및 추론 모델의 입력 명세를 런타임에 동적으로 연동(Binding)해주는 표준 인터페이스 계층이 요구된다.
+
    - **다유형 메시지 교환 규격 결여**: AIoT 환경에서 에이전트와 물리 계층 간에 교환되는 정보는 단순 텍스트 명령에 국한되지 않고, 고해상도 이미지·음향 주파수·센서 시계열·상태 구조체·상세 에러 트레이스 등 다양한 유형의 멀티모달 페이로드를 포함한다. 그러나 기존 MQTT나 단순 메시지 큐(MQ) 방식은 토픽 세분화와 페이로드 크기 한계로 인해 이러한 다유형 대용량 메시지를 통합 교환하는 데 병목을 겪으며, 단편적인 이벤트 알림 전송에 머무르는 규격의 한계가 존재한다. 또한 기존 에이전트 프레임워크(AutoGen·CrewAI 등)는 주로 텍스트 기반 메시지 교환을 전제로 설계되어, 이종 에이전트 간 다유형 멀티모달 페이로드를 규격화하여 교환할 표준 메시지 스키마 및 풍부한 페이로드 지원 메시징 인터페이스가 결여되어 있다.
 
 3. **상시 점유의 비효율성과 자원 최적화 한계 (Resource Allocation Inefficiency - 자원 축)**