refactor(security,concurrency): resolve structural issues, enforce Claude permission skip, update docs

2026-06-23 08:03:43 +09:00
parent 12dceb14b2
commit 99ac8b3ce4
7 changed files with 209 additions and 45 deletions
@@ -33,6 +33,63 @@ Tmux와 MQTT 브로커를 기반으로 구축된 고신뢰성 **다중 에이전

 ---

+## 📐 전체 아키텍처 구성 (Big-Picture Architecture)
+
+이 시스템은 크게 두 가지 계층(Layer)을 통해 다중 워크스페이스에서 작동하는 LLM 에이전트들을 조율합니다:
+
+1. **Layer A — Tmux 오케스트레이션 (lib.sh + status/resume/stop/create)**: 워크스페이스별 에이전트 세션을 독립된 tmux 인스턴스로 분리 실행하고, `.mam/agent-sessions.yaml` 및 SQLite 데이터베이스(`.mam/agent-sessions.db`)를 통해 에이전트 세션 메타데이터의 단일 참조 지점(Single Source of Truth)을 유지합니다.
+2. **Layer B — 비동기 잡 위임 (delegate-job)**: 에이전트에 특정 태스크를 전송하고 비동기 이벤트 채널(MQTT)을 통해 진행 상황과 완료 여부를 모니터링합니다.
+
+두 레이어는 파일 I/O 처리를 위한 하나의 핵심 관문인 `lib.sh::atomic_dump_yaml`을 공유합니다. 모든 YAML/DB 쓰기 작업은 독점 파일 락(`flock`)과 데이터 스키마 유효성 검증을 거칩니다.
+
+### 데이터 흐름 개요 (Data Flow)
+
+```text
+  +-----------+   register_job    +-------------------+
+  | delegator | ---------------> | .mam/jobs/<id>.json|  <-- 실시간 잡 정보
+  +-----------+                   +---------+---------+
+                                                |
+                                                | atomic rename + fsync
+                                                v
+                                       +-----------------+
+                                       |   audit log     |  <-- 추가 전용
+                                       | .mam/delegate_  |      events.ndjson
+                                       |  job_logs/<id>/ |
+                                       +--------+--------+
+                                                ^
+                                                | (최선 노력 미러링)
+                                                |
+  +-----------+   publish_event    +-----+-----+      +---------+
+  |  agent    | ---------------> | MQTT broker | <--- | monitor |
+  | (claude)  |                   +-------------+      +----+----+
+  +-----------+                                            |
+       ^                                                  v
+       | 구독자(subscriber)                           atomic_dump_yaml
+       | (job_subscriber.py)                          (.mam/agent-sessions.yaml)
+       |                                                  ^
+       +-------- 위임 대기 영역 -----------------+        |
+                                                   +---+---+
+                                                   | reconcil|
+                                                   |  e.sh  |
+                                                   +--------+
+```
+
+### 🔒 Tmux 서버 격리 (Tmux Server Isolation)
+
+에이전트 세션 간의 충돌 및 시스템 전역 tmux 프로세스와의 혼선을 막기 위해 독립된 서버 소켓 환경을 보장합니다:
+*   **워크스페이스별 심(Shim):** `_init_tmux_isolation` 및 `_resolve_real_tmux_path` 함수가 `/tmp/multi-agent-tmux-shim/<TMUX_SERVER_NAME>/tmux` 경로에 독립된 심 디렉터리를 구성하고, 일반 tmux 명령 실행 시 자동으로 `tmux -L <server>` 형태의 독립 소켓 서버를 사용하게 만듭니다.
+*   **PATH 환경변수 변조:** 자식 프로세스를 생성할 때 `PATH` 변수 맨 앞에 심 디렉터리 경로를 삽입합니다. 이로 인해 에이전트의 내부 셸에서 수행되는 모든 `tmux` 명령어는 해당 격리 서버 소켓으로 강제 제약됩니다.
+*   **환경 복구:** `TMUX_SERVER_NAME`을 `default`로 설정하는 경우 PATH 오버라이드가 정리되고 기본 전역 tmux 서버를 사용하게 됩니다.
+
+### 🛡️ 동시성 설계 및 쓰기 직렬화
+
+여러 에이전트가 동시에 실행될 때의 레이스 컨디션을 방지하기 위해 락 기반의 실행 패턴을 고수합니다:
+*   **POSIX 파일 락 (`flock`):** `agent-sessions.yaml` 또는 SQLite 레지스트리에 쓰기 연산을 진행할 때, 반드시 `lib.sh` 내부의 `atomic_dump_yaml` 함수를 거쳐 `.mam/agent-sessions.yaml.lock` 파일에 독점 락(`flock`)을 획득하도록 직렬화합니다.
+*   **이중 인터프리터 분리 구조:** 라이브러리 간 의존성 충돌과 실행 도구의 안정성을 보장하기 위해 환경을 이원화했습니다. MQTT 및 비동기 작업 통신에는 가상환경 `.venv` (paho-mqtt 필요)의 Python을 사용하고, YAML 직렬화 쓰기 및 유효성 검증을 담당하는 `atomic_dump_yaml`은 시스템 전역 `python3` (시스템 PyYAML 필요)을 호출합니다.
+*   **NFS 및 네트워크 파일시스템 대응:** 네트워크 디바이스(NFS, CIFS, SSHFS)에서는 `flock`이 무력화되는 특성이 있습니다. `lib.sh`는 쓰기 대상 파일시스템 경로의 마운트 타입을 체크하여, 네트워크 파일시스템 감지 시 경고 로그를 출력하고 SQLite의 저널 모드를 `WAL`에서 `DELETE`로 자동 전환해 동시성 안전을 강화합니다.
+
+---
+
 ## 📐 아키텍처 및 조정 루프 (Review Loop)

 Project Manager(PM), Worker, Reviewer 역할 간의 협업 구조는 엄격한 교차 검증 루프를 따릅니다: