📑 MAM 스킬 최적화 세션 인수인계 요약서 (handoff.md)

이 인수인계서는 Multi-Agent Mux (MAM) 프로젝트에서 진행된 개발 스킬 최적화 Phase 1 및 Phase 2 일부 구현 완료 상태와, 에이전트 세션 토큰 한계(Rate limit) 및 검수 범위 제약으로 인해 보류된 나머지 잔여 최적화 과제들을 다음 차수에 연계하기 위해 작성되었습니다.

1. 🏁 현재 완료된 최적화 성과 (Phase 1 & 2 완료)

OP-1 (반응형 세션 종료 - Latency): lib.sh에 _wait_session_gone 헬퍼를 도입하여 고정 8초 대기하던 문제를 조기 종료 감지 방식으로 해결 (평균 종료 시간 8초 ➡️ 0.3초 미만). stop_session.sh에 set -e 강제 폭사 방지 || true 가드 탑재.
OP-2 (MQTT 구독 동기화 핸드셰이크 - Latency): job_subscriber.py에 on_subscribe 콜백 신호를 추가하고, delegate-job에서 SUBSCRIBED sentinel 폴링 및 kill -0 $sub_pid 프로세스 생존 검사를 병행 기입하여 WAN 환경의 이벤트 유실을 박멸하고 즉시 기동하도록 변경.
OP-3 (Event Loop CPU 점유 최적화 - Latency): reconcile.sh 백그라운드 파이썬 대기 루프를 threading.Event().wait Pacing으로 교체하여 **유휴 상태 CPU 점유율을 0%**로 단축.
OP-4 (Tmux Dispatcher 단일화 - DRY): 격리 서버 대응을 단일 canonical helper인 mam_tmux로 일원화하고, _REAL_TMUX_PATH 매핑을 강제하여 무한 재귀(Stack Overflow) 리스크를 완전히 제거.
OP-6 & OP-7 (토큰 상수화 및 zsh 소싱 가드 - Portability): 대화창 감지 정규식 토큰 단일화 및 zsh sourcing 방지를 위한 안전 경고 트랩 탑재.

두 리뷰어(Cline & Creator) 및 플래너 에이전트로부터 최종 정식 PASS 및 APPROVED 서명을 획득하여 릴리스 커밋 완수 (7eeb4b7).

⏭️ 추후 수행할 잔여 최적화 과제 (Next Action Items)

다음 세션에서 에이전트(Claude 등)에게 검수받고 실제로 이행해야 할 목록입니다:

1. OP-5: SQLite / YAML 데이터 로더 중복 제거 (DRY)

대상 파일: lib.sh (3개소), stop_session.sh:87, status.sh:42, update_yaml_resumed.sh:66, reconcile.sh:298
현황 및 원인: SQLite와 YAML에서 에이전트 병합 세션 상태를 로드하기 위한 파이썬 heredoc 블록이 7개 파일에 복사-붙여넣기되어 있습니다.
개선 방향: lib.sh 내에 load_state_json 공통 함수를 단일 구현하고 스크립트 파일들이 이를 통해 파싱된 JSON 스트림만 읽도록 개선한 뒤, 플래너/리뷰어 검수 PASS를 획득해야 합니다.

2. OP-8: Degraded 모드 복구 루프 예외 처리 강화 (Observability)

대상 파일: reconcile.sh:269
현황 및 원인: 브로커 단절 시 복구를 유도하는 루프의 에러 출력이 >/dev/null 2>&1 || true 로 차단되어 있어 데이터베이스 락 등의 심각한 영구 장애 시에도 모니터가 성공인 척 묵인됩니다.
개선 방향: 에러 출력을 캡처 및 로깅하고, 5회 연속 장애 시 복구 감시 프로세스를 종료 후 자가 재기동(Supervisor restart)하도록 보완하고 검수받아야 합니다.

3. Phase 3 이식성 보완 과제

OP-9 (POSIX NFS 탐지): GNU 전용 df --output을 POSIX 호환 df -P로 교체하여 macOS/BSD에서 flock WAL 안전 스위치가 침묵 속에서 비활성화되던 이슈 수정 (FUTURE_WORKS FW-P1/FW-D3 대응).
OP-10 (Marker-walk 루트 탐색): 깊이가 하드코딩된 ../../../../ 경로 추적을 폐지하고, 최상위 워크스페이스 마커 파일 감지 방식으로 루트 절대 경로 탐색기 적용 (FUTURE_WORKS FW-P6 대응).

4. 📂 [신규 구상] 작업 단위(Job) 중심 디렉터리 구조 재구조화 검토 및 스킬 수정 계획

개요 및 아이디어 검토:
- 현재 지시사항(brief) 파일은 다양한 경로에 산재하고 있으며, 에이전트들의 보고서 파일은 일괄적으로 .agents/reports/<agent_session_name>/ 아래에 적재되어 특정 작업(Job) 단위의 보고서 역추적이 번거롭습니다.
- 사용자 제안 아키텍처:
  1. 작업이 등록되면 .mam/jobs/<job_id>/ 라는 고유 작업 단위 폴더를 생성합니다.
  2. 해당 폴더 하위에 지시사항 brief 파일을 기록해 다른 에이전트들에게 전달합니다.
  3. 작업을 위임받아 수행한 다른 에이전트들의 결과 보고서들은 기존 공통 폴더 대신 해당 작업 폴더 내부인 .mam/jobs/<job_id>/{agent-id}-reports/ 디렉터리에 격리 저장하도록 경로를 치환합니다.
- 검토 의견 (APPROVED): 작업(Job)을 중심으로 한 지시서와 결과 보고서의 귀속성과 추적성(Audit Trail)을 극대화할 수 있는 매우 훌륭한 구조적 개선안입니다.
스킬 수정 영향 범위 및 이행 계획:
- multi-agent-mux-delegate-job 스크립트 수정: 잡 등록 시 .mam/jobs/<job_id>/ 디렉터리를 자동 생성하고 지시서 마크다운을 그 하위로 동적 출력하도록 변경.
- 리뷰어 및 크리에이터 에이전트의 구동 인자 및 스크립트 수정: 보고서 출력 경로를 환경변수 또는 인자로 전달받은 잡 하위 디렉터리($JOB_DIR/$AGENT_ID-reports/)로 치환하여 라이팅하도록 패치.

5.5 KiB Raw Blame History