tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
245abe62c8b67dc6fcf475dbf2386916ca7975a7
multi-agent-mux/IMPROVEMENTS.md
T

13 KiB
Raw Blame History

🛠️ Multi-Agent Mux 종합 개선 및 미해결 과제 백로그 (IMPROVEMENTS.md)

  • 최종 갱신일: 2026-08-08 (B-4 시프트 ls created 포시스 타임스탬프 결함 조치 완료 반영)
  • 통합 관리 대상: 기존 CODEBASE_REVIEW_REPORT.md + OPTIMIZATION.md
  • 총 추적 미해결 과제: 11건 (아키텍처 1건, 엣지케이스 6건, 오케스트레이션 1건, 레거시 잔재 3건)
  • 완료된 과제: 10건 (A-1, A-3, A-5, B-1, B-3, B-4, C-1, C-2, O-1, O-3)

📌 개요

본 문서는 Multi-Agent Mux (MAM) 프레임워크의 코드베이스 아키텍처 결함, 런타임 엣지케이스, 레거시 잔재 및 /multi-agent-mux-loop 오케스트레이션 최적화 과제를 단일 백로그로 통합 추적하기 위한 종합 관리 문서입니다.

1. 🔴 아키텍처 결함 (Architecture Flaws — 1건)

A-2: 공개 브로커 + HMAC 인증 Off + 와일드카드 전파

  • 현상: mqtt_common.py의 기본 브로커가 공개 서버(broker.hivemq.com), HMAC 무조건 True 반환으로 설정되어 있습니다.
  • 파급 효과: 외부에서 유입되는 malicious error 이벤트 수신 시 reconcile.sh가 라이브 에이전트 pane을 kill-session으로 강제 파괴하는 치명적 보안/안정성 위험이 존재합니다.

2. 🟠 엣지 케이스 및 런타임 버그 (Edge-case Bugs — 6건)

B-5: df --output GNU 전용 플래그 사용으로 macOS NFS 감지 실패

  • macOS/BSD 환경에서 df --output 구문 오류로 NFS 감지가 실패하고 "NFS 아님"으로 오판되어 SQLite WAL 포맷을 강행합니다.

B-6: 스킬 트리에 임시 파일 복사 및 유출

  • run_loop.sh::delegate_job_safe가 래퍼 스크립트를 .agents/skills/... 트리 내부에 .tmp로 복사하여 버전 관리 트리를 오염시키고 rsync 배포 시 외부로 유출됩니다.

B-7: run_loop.sh 상대경로 cwd 의존 및 미추적 파일 누락

  • 저장소 루트 밖에서 run_loop.sh 구동 시 wait_for_job이 3900초 무음 타임아웃을 발생시키며, git diff가 Creator가 새로 추가한 미추적 신규 파일을 리뷰어에게 누락합니다.

B-8: send_keys_safe agy 경로 검증 이탈

  • agy 세션 주입 시 주입 실패 여부를 검증하지 않고 무조건 return 0을 남겨 실패 시에도 성공으로 보고됩니다.

B-9: LOGS_DIR import 시점 cwd 고정

  • mqtt_common.py 모듈 로드 시점의 cwd로 감사 로그 경로가 1회 고정됩니다.

B-10: agent_identities 쓰기 경로 부재 및 PyYAML 의존성

  • 저장소 전체에 agent_identities 를 생성·갱신하는 코드가 0건이며, lib.sh 의 PyYAML 하드 의존성으로 인해 .db 만으로 충분한 경우에도 PyYAML 부재 시 상태 조회가 무력화되는 문제가 존재합니다.

3. 🟡 오케스트레이션 최적화 과제 (Orchestration Optimizations — 2건)

O-2 (구 ISSUE-7): 동일 워크스페이스 내 중복 루프 기동 방지 락 (Race-Free Lock)

  • 현상: 동일 작업 트리에서 다수의 run_loop.sh 스크립트가 병렬 기동될 경우 SQLite DB 갱신 경합 및 YAML 데이터 오염이 일어날 수 있음.
  • 문제점: 단순 PID 파일 존재 여부만 체크할 경우, PID Rollover(프로세스 ID 재사용) 또는 mkdir과 PID 기록 사이의 생성 창(Grace Window)에서 살아있는 락을 타 프로세스가 훔쳐가는 "락 도난(Live-lock theft)" 현상 발생.
  • 해결 방안:
    1. 락 소유자 레코드를 단순 PID에서 PID + 시작시각(lstart) + 워크스페이스 3중 구조로 결합하여 PID 재사용을 결정적으로 차단.
    2. mkdir 직후 생성 창 유예 대기(Sleep Grace Period)를 부여하여 락 도난 방지.
    3. ps CLI 부재 시 Fails-Open(락 무시) 대신 Fails-Safe(락 존중 + 경고) 로 전환하여 DB/YAML 오염 원천 방지.

4. ⚪ 레거시 잔재 및 죽은 코드 (Legacy Remnants — 3건)

C-3: 격리 스텁 4종 및 stop_session.sh 미사용 isolation 코드 잔존

  • provision_isolation 등 4개 스텁 함수와 stop_session.sh 내 .mam/agent_homes 가드 코드가 호출자 0건인 채 잔존합니다.

C-4: 참조 0회 미사용 심볼 7종

  • _HERDR_SHIM_DIR_PATTERN, _REAL_HERDR_PATH, TERMINAL_STATUSES, ISOLATE, local_herdr 등 7개 미사용 심볼이 잔존합니다.

C-6: stop_session.sh 도움말 문서 구버전 표기

  • 스크립트 도움말에는 --mode soft|hard 등이 서술되어 있으나 실제 옵션 파서는 exit 2로 거부합니다.

5. 🎉 완료된 과제 (Completed Tasks — 10건)

Rev.2 (b4a1d094): 생성 시 세션 ID 자동 할당 및 Reconciler 고정/경로 정규화 프로토콜 — ✅ 완료

  • 신규 claude 세션 생성 시 mam_gen_uuid로 UUID를 즉시 생성하여 --session-id <uuid>로 전달하고, session_id_source: assigned, session_id_verified: false로 등록하는 원자적 고정 구조를 구축했습니다.
  • 첫 사용자 메시지 전달 시 디스크 트랜스크립트 .jsonl 생성을 모니터 루프(reconcile.sh drift C0)가 감지하고 session_id_verified: true, last_visible_status: pinned로 고정시킵니다.
  • 미할당 다수 후보 발견 시 무작위 고정을 금지하고 C-ambiguous 상태를 명확히 보고하도록 강화했습니다.
  • 심볼릭 링크/트레일링 슬래시/상대경로 계산 시 mam_abs_workspace 및 mam_workspace_key (cd -P && pwd -P / os.path.realpath) 경로 정규화를 전수 적용하여 100% 키 일치성을 확립했습니다.
  • 전용 단위/통합 테스트 스위트 tests/test_uuid_target.py (13/13 PASS) 및 전체 회귀 테스트 스위트를 검증 완료했습니다.

B-4: 시프트 ls의 created 동적 POSIX 타임스탬프 복원 및 재개 가드 정상화 — ✅ 완료

  • .agents/skills/lib.sh 554번 라인의 999999 하드코딩 출력을 제거하고, real herdr 또는 .mam/agent-sessions.yaml 에 기록된 세션 생성 시각(created/created_at/created_epoch) 및 동적 POSIX 타임스탬프(int(time.time()))를 리턴하도록 정제했습니다.
  • reconcile.sh drift-B 감지 시 epoch 0 및 1970-01-01 오기록 결함을 차단하여 find_workspace_uuid 재개 가드가 정상 작동하도록 해결했습니다.
  • 멀티에이전트 자율 오케스트레이션 루프(run_loop.sh --plan --all-reviewer)를 통해 Planner(claude), Creator(agy), Reviewer(cline) 3자에 의해 구현 및 교차 검증 후 [VERDICT: PASS] (만장일치 통과) 되었습니다.
  • 전용 회귀 테스트 스위트 tests/test_b4_session_created.py (21/21 PASS)를 작성하여 입증했습니다.

O-3: 조건부 오케스트레이션 위임 가드 (Invocation-Aware Scoped Guard) — ✅ 완료

  • Normal Mode(직접 소스 수정)와 Loop Active Mode(/multi-agent-mux-loop 인보크 시 run_loop.sh 자율 위임)의 역할 경계를 명확히 구분하는 스킬 인터셉터 가드레일(.agents/hooks.json & .agents/hooks/loop_delegation_guard.sh)을 구축했습니다.
  • step-type 파생명 매처(file_change|edit_notebook|write_blob)를 적용하여 가드 무발화 결함을 방지했습니다.
  • pid + lstart(프로세스 시작시각) 신원 대조 검증을 통해 PID Rollover 및 PermissionError 시 발생할 수 있는 Livelock 영구 차단 오판을 완벽히 해결했습니다.
  • run_loop.sh 마커 기록 및 delegate_job_safe 트랩 복원(_mam_release_guard)을 완료했습니다.
  • AGENTS.md, MULTI_AGENT_RULES.md (.ko.md), SKILL.md 문서를 전수 대칭 갱신했습니다.
  • 전용 단위/회귀 테스트 스위트 tests/test_o3_scoped_guard.py (22/22 PASS)를 수립하여 입증했습니다.

A-1: 워크스페이스 세션 격리 & drift-B 오등록 방지 — ✅ 완료

  • derive_workspace_slug 헬퍼 함수를 추가하여 워크스페이스 경로 기반 단일 소켓 슬러그(mam-<parent>-<work>) 도출 체계를 구축했습니다.
  • reconcile.sh drift-B 자동 등록 시 foreign cwd 차단 게이트를 구축하여 세션 오등록을 방지했습니다.

A-3: 시프트 버퍼 동시 주입 오염 & 자동 GC 체계 구축 — ✅ 완료

  • lib.sh 내 send_keys_safe 시프트 버퍼 명령의 임시 파일명을 sks_${sess}_${job_id}_$$_${RANDOM}_$(date +%s%N) 식 호출 단위 독립 토큰으로 변환하여 다중 에이전트 동시 주입 시 대화 교차 오염 및 무음 유실(T5)을 원천 차단했습니다.
  • set-buffer 시 원자적 임시 쓰기(.$buf.$$.tmp) 및 rename(mv -f) 구조를 구현하여 파티셜 레코드 관측을 방지했습니다.
  • 인터럽트/예외 종료 시 남는 stale 버퍼 파일을 자동으로 정리하는 60분 내장 GC(find -mmin +60 -delete)를 내장했습니다.
  • 전용 회귀 테스트 스위트 tests/test_a3_buffer_isolation.py (12/12 PASS)를 작성하여 입증했습니다.

C-2: 미사용 .cache/ 상태 디렉터리 생성 및 데드 코드 정돈 — ✅ 완료

  • reconcile.sh에서 아무 데이터도 저장하지 않던 미사용 .cache/multi-agent-mux-monitor 디렉터리 생성(mkdir -p) 구문 및 STATE_DIR 환경변수를 제거했습니다.
  • 레거시 환경변수 AGENT_SESSIONS_STATE_DIR 설정 시 무음 생성을 방지하고 stderr에 가이드 경고만 안내하도록 정돈했습니다.
  • deploy/remove.sh 언인스톨러에서 미사용 .cache/ 디렉터리가 비어있는 경우 안전하게 제거(rmdir .cache)하도록 개선했습니다.
  • 전용 단위/회귀 테스트 스위트 tests/test_c2_no_stale_cache_dir.py (5/5 PASS)를 작성하여 입증했습니다.

A-5: HERDR_SESSION_NAME 네이티브 전환 — ✅ 완료

  • 기존 HERDR_SERVER_NAME 환경변수를 herdr 시프트가 직접 읽는 네이티브 HERDR_SESSION_NAME 및 YAML 레지스트리 키 **herdr_session**으로 전수 전환 단일화했습니다.

B-1: find_workspace_uuid tier-3 신원 캐시 해석 오류 해결 — ✅ 완료

  • lib.sh tier-3 신원 캐시 조회 시 미정의 변수(db_path, yaml_path) 및 yaml import 누락으로 무조건 NameError 예외가 발생하던 결함을 해결했습니다.
  • DB를 1차 권위 경로로, $YAML_PATH를 폴백으로 정제하고 전용 회귀 테스트 tests/test_b1_tier3_identity.py (8/8 PASS)를 작성하여 입증했습니다.

B-3: command -v herdr 프리플라이트 무력화 — ✅ 완료

  • lib.sh에 _canonical_file(), _is_shim_path(), _resolve_real_herdr_path(), has_real_herdr() 헬퍼를 작성하여 herdr() bash 함수 오판과 .mam/shim/herdr 래퍼 매칭(파일 수준 심링크 포함)을 완전 차단했습니다.
  • create_session.sh, multi-agent-mux-delegate-job, create/SKILL.md, status/SKILL.md 프리플라이트를 has_real_herdr로 전수 교체했습니다.
  • 회귀 테스트 tests/test_b3_herdr_preflight.py (11/11 PASS)를 작성하여 입증했습니다.

C-1: Kanban 문서 29회 언급 vs 실제 구현 0건 — ✅ 완료

  • SKILL.md 3종(monitor 22 / status 5 / create 2)과 README 2종의 Kanban 서술을 전면 제거했습니다.
  • multi-agent-mux-monitor 의 실행 메커니즘 서술을 실제 구현인 reconcile.sh --subscribe (MQTT push + 브로커 다운 시 폴링 폴백) 기준으로 재작성했습니다.
  • 존재하지 않는 스킬 참조 2건(kanban-worker, kanban-orchestrator)을 실존 스킬로 교체했습니다.
  • hermes kanban create CLI 플래그 잔재 10종(--goal-max-turns, --assignee, --comment-card 등)을 파생형 검증 게이트(G-C)로 차단했습니다.
  • 제품 표면(.agents/skills/, README*.md) Kanban 참조 0건 확인.

O-1: 타당하지 않은 리뷰 피드백 거부/반론 프로토콜 미지원 (Rebuttal Protocol) — ✅ 완료

  • run_loop.sh에 --max-rebut N (기본값 1) 옵션 및 Rebuttal/Re-adjudication/Arbitration 3단계 프로토콜을 구현했습니다.
  • Creator가 지적 항목 거부 시 [REBUT: <reviewer>] 태그를 남겨 해당 리뷰어 대상 재심([ADJUDICATION: SUSTAINED/OVERRULED])을 가동하며, 교착 시 Planner 재정([ARBITRATION: CREATOR/REVIEWER]) 또는 Fail-Closed 결정을 수행합니다.
  • bash 3.2 macOS 규격 빈 배열 확장 안전성(${ARR[@]+"${ARR[@]}"}) 및 per-iteration budget reset / total budget cap 결함을 완벽히 보완하고 회귀 테스트 tests/test_o1_rebuttal.py (10/10 PASS)로 입증했습니다.
  • MULTI_AGENT_RULES.md, .ko.md, multi-agent-mux-loop/SKILL.md 문서 연동을 완료했습니다.

6. 결론 및 향후 보완 로드맵

IMPROVEMENTS.md 문서에 따라 향후 코드베이스 개편 시 남은 백로그 항목(아키텍처 2건, 엣지케이스 7건, 오케스트레이션 2건, 레거시 잔재 4건)을 일원화된 보완 로드맵으로 관리합니다.

Reference in New Issue View Git Blame Copy Permalink