tmpl/multi-agent-mux

Fork 0

Files

T

Godopu 4d1c381033 docs(improvements): prioritize and record execution roadmap Section 6 (100% PASS)

2026-08-09 19:55:25 +09:00

31 KiB

Raw Blame History

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

최종 갱신일: 2026-08-09 (7747d745 Rev.2 — B-7 처방 신설 및 병렬화를 파일 소유권 슬롯으로 교체)
통합 관리 대상: 기존 CODEBASE_REVIEW_REPORT.md + OPTIMIZATION.md
총 추적 미해결 과제: 12건 (아키텍처 2건, 엣지케이스 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 — 2건)

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

현상: mqtt_common.py의 기본 브로커가 공개 서버(broker.hivemq.com)이고, 잡 생성 시 auth_token 이 한 번도 발급되지 않아(실측 26/26 잡이 auth_token=None) verify_hmac 의 if not auth_token: return True 경로가 항상 타집니다. 발행자는 워크스페이스 지문 토픽을 채택하지 않고 전역 python/mqtt/jobs/<job_id>/events 로 발행하며, reconcile.sh:237 이 같은 전역 토픽을 구독합니다. (HMAC 구현 자체는 정상입니다 — 토큰이 없어 검증이 공허해지는 것이 원인입니다.)
파급 효과: 외부에서 유입되는 malicious error 이벤트 수신 시 reconcile.sh가 라이브 에이전트 pane을 kill-session으로 강제 파괴하는 치명적 보안/안정성 위험이 존재합니다.

A-4 (설계 제안): 에이전트 지식 산재 — `BaseAgentAdapter` 어댑터 계층 도입 (Rev.2)

결함 조치가 아니라 구조 개선 제안입니다. 상세 설계·실측 근거는 .mam/jobs/44062a63/claude-reports/report-final.md 및 744ac67a 를 참조하십시오.

현상: "claude 의 transcript 는 어디 있나", "cline 재개 argv 는 무엇인가" 같은 에이전트에 대한 사실이 스크립트 8개 · 34개 팬아웃 지점에 흩어져 있습니다. (8줄 윈도 안에 4개 에이전트 중 3개 이상이 등장하는 지점 기준: create_session.sh 8, reconcile.sh 7, stop_session.sh 6, lib.sh 4, resolve_session_id.sh 3, resume_session.sh/update_yaml_resumed.sh/run_loop.sh 각 2)
사본 현황: agent → *_id_own 키 맵 4벌, ~/.claude/projects 17참조, antigravity-cli/conversations 11참조, .hermes/state.db 6참조, .cline/data/sessions 5참조.
파급 효과: 같은 질문에 서로 다른 답이 공존합니다. 세션명→에이전트 추론이 reconcile.sh::row_agent(pane.cmd → cmd_full → 이름 접미사)와 run_loop.sh:236-243(세그먼트 매칭 + 실패 시 claude 기본값) 두 벌로 존재하며 후자는 오판 가능합니다. b4a1d094 에서 드러난 "격리 분기 inert" 결함도 아티팩트 경로 규칙이 두 벌이었던 데서 비롯됐습니다.

설계 요지 (Rev.2 갱신)

.agents/skills/mam_agents/ 패키지(약 484줄): base.py(ABC + SpawnSpec + DiscoveryContext), registry.py(정적 레지스트리), __main__.py(셸 브리지), adapters/{claude,agy,hermes,cline}.py.
인터페이스: own_key / supports_assigned_id / ready_tokens 속성 + auth_ok(run) · spawn_spec() · resume_spec(binary, uuid, materialized) · artifact_path(uuid, ctx) · verify_artifact(uuid, ctx) · discover(ctx).
- DiscoveryContext & discover() 템플릿 메서드: cwd(물리 절대경로), ws_key, home, claude_dir, iso_root, epoch, claimed 필드를 객체 하나로 캡슐화. _raw_candidates(ctx) 추상 메서드로 어댑터별 물리 탐색만 서술하고 claimed/epoch 필터는 기반 클래스 템플릿이 100% 보장.
- auth_ok 는 서브프로세스 실행자를 주입받아 CLI 미설치 환경에서도 단위 테스트가 가능합니다(hermes 는 현재 미설치).
- resume_spec 의 materialized 파라미터가 b4a1d094 규칙(claude -r <미실현 uuid> 실패 → --session-id)을 흡수합니다.
- ready_tokens 속성을 어댑터로 내보내 wait_for_tui_ready 의 25줄 inline shell case 블록을 단 1줄의 grep -E -q "$MAM_READY_TOKENS" 로 축소.
레지스트리 패턴: 정적 dict 채택. entry_points 는 MAM 이 pip install 되지 않고 rsync/cp 로 배포되므로 부적합, 디렉터리 스캔은 "0개 발견"과 "에이전트 미설치"가 구분되지 않아 부적합.
bash↔python 브리지: python -m mam_agents facts <agent> 가 shlex.quote 된 KEY=value 를 출력. 스크립트당 1회 eval 이 계약입니다(실측 22.8 ms/호출 vs bash case 2.3 ms — 분기마다 호출하면 안 됨).

실현 가능성 및 부트스트랩 (Rev.2 실측)

파이썬 진입점 3종 전부에서 import 확인: env_python, atomic_dump_yaml(flock 쓰기 경로), venv 없는 맨 /usr/bin/python3.
lib.sh source 시점 1회 export PYTHONPATH: lib.sh 로드 시 _mam_export_pythonpath 가 mam_skills_dir 을 PYTHONPATH 에 자동 얹어 run_loop.sh 등 셸 상의 모든 python3 -c 호출이 한 번에 호환됨.
herdr shim 내부 python3 -c 9곳 전부 에이전트 지식 0 → shim 경계가 이미 올바른 위치에 있습니다.
제약(규칙화 필요): 어댑터는 표준 라이브러리만 사용해야 합니다. 서드파티 의존성이 들어오면 venv 없는 경로가 깨집니다.

선행 필수 체크리스트 (누락 시 조용히 업그레이드가 막힘)

deploy/remove.sh:83-91 fallback_assets 에 ".agents/skills/mam_agents" 등록. 미등록 시 tests/test_deploy_freshness.py::test_d2 가 실패하며(프로토타입에서 실제 발생), 언인스톨 후 잔존 자산이 워크스페이스를 영구히 구버전에 고정시킵니다(install.sh 는 비-스킬 자산을 "없을 때만" 복사).
deploy/install.sh 무결성 자산 목록 등록.
deploy/gitea-ci.yml:69-77 의 flake8 / py_compile 경로 추가 — 현재 CI 파이썬 잡은 multi-agent-mux-delegate-job/scripts/ 만 검사하므로 신규 패키지는 린트 사각지대입니다.

단계적 이행 (각 단계는 셸 사본 제거를 같은 커밋에 포함)

단계	내용
M0	패키지 골격 + `lib.sh` source 시점 `PYTHONPATH` export + 배포/CI 등록
M1	`own_key` / `agent_of_row` 이관 — 프로토타입 검증 완료: 팬아웃 34 → 29
M2	`artifact_path` + `verify_artifact` (`verify_session_uuid` 4분기, `DiscoveryContext` 적용, 격리 경로 일원화)
M3	`spawn_spec` / `resume_spec` / `auth_ok` (create·resume argv 및 프리플라이트)
M4	`discover()` (raw candidates + base class template filter) — hermes DB 스키마 실측 선행
M5	`stop_session.sh` purge 경로 및 exit key
M6	`ready_tokens` 어댑터 이관 (`wait_for_tui_ready` 25줄 case 제거)
M7	claude ready tokens 에서 `projects` 제거 및 자체 검증 분리 커밋

정직한 상한: 34 → 약 10. 남는 약 10곳은 셸 상주 TUI·프로세스 제어(send_keys_safe 의 agy/claude/cline 분기, handle_startup_dialogs, spawn 래퍼 분기, pgrep -P 자식 pid 게이트)로 이 추상화의 대상이 아닙니다.
중단 기준: M2 이후에도 팬아웃이 29 → 20 이하로 떨어지지 않으면 중단하고 잔여 단계를 재검토합니다.
검증 상태: Rev.2 프로토타입 기준 전체 회귀 162 passed (회귀 0), 변이 6/6 검출, 배포 스위트 25/25, py_compile 통과.

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

B-5: `df --output` GNU 전용 플래그 사용으로 macOS NFS 감지 실패 — ⚠️ 종결 권고 (재현 불가)

원 서술: macOS/BSD 환경에서 df --output 구문 오류로 NFS 감지가 실패하고 "NFS 아님"으로 오판되어 SQLite WAL 포맷을 강행합니다.
실측(ecef05a3): df --output=target 은 여전히 rc=64 로 실패하나 ea36e81 에서 추가된 df -P 폴백이 정상 동작합니다(macOS 실측: /System/Volumes/Data). 결론("감지 실패")은 더 이상 참이 아니므로 종결을 권고합니다.
잔여분 → B-11 로 분리 권고: mount | grep -E "$mountpoint.*(nfs|cifs|smb|sshfs)" 가 마운트포인트를 이스케이프 없이 ERE 에 보간하여 경로의 . 이 임의 문자로 해석됩니다(이론상 오탐).

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

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

B-7: `run_loop.sh` cwd 의존 및 미추적 파일 누락 — 리뷰어가 빈 diff 로 PASS

원 서술: 저장소 루트 밖에서 run_loop.sh 구동 시 wait_for_job이 3900초 무음 타임아웃을 발생시키며, git diff가 Creator가 새로 추가한 미추적 신규 파일을 리뷰어에게 누락합니다.
실측(ecef05a3): REPO_ROOT 는 BASH_SOURCE 기반이라 cwd 비의존이지만(9-10행) 스크립트가 어디로도 cd 하지 않아 git diff(537·539행)가 호출자 cwd 에서 실행됩니다. 저장소 밖에서는 rc=129 이고 || echo "No git diff available" 가 이를 삼켜, 리뷰어는 그 문자열 하나를 받고 [VERDICT: PASS] 를 요구받습니다.
미추적 파일은 git diff 정의상 제외됩니다(실측 0 hunks). 신규 파일이 곧 산출물인 작업(예: A-4 의 mam_agents/ 패키지)에서는 리뷰가 사실상 존재하지 않게 됩니다.
파급: 이 항목이 열려 있는 동안 나머지 11건의 구현 리뷰를 신뢰할 수 없습니다.
처방: §6.4 참조 ( + 미추적 파일 덧붙이기 + 크기 상한). ** 은 인덱스를 오염시키므로 채택하지 않습니다.**

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 — 1건)

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 오염 원천 방지.
실측(ecef05a3) — 서술보다 위험: run_loop.sh:83-89 는 MAM_LOOP_MARKER 를 존재 확인 없이 덮어쓰고, 종료 트랩(_mam_release_guard)이 소유권 대조 없이 삭제합니다. 따라서 먼저 종료한 인스턴스가 아직 실행 중인 다른 인스턴스의 마커까지 지워, 그 시점부터 완료 처리된 O-3 위임 가드가 "루프 비활성"으로 오판합니다. 해제는 자신이 기록한 pid + lstart 와 일치할 때만 수행해야 합니다.

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

C-3: 격리 관련 잔재 — ⚠️ C-3a / C-3b 로 분리 필요 (§6.5 참조)

C-3a (즉시 실행 가능): provision_isolation / isolation_lever / isolation_env_prefix / isolation_cmd_args 4종 빈 스텁. 프로덕션 호출자 0건. 이를 고정하던 공허한 테스트 5건(test_tier1_unit.py 3, test_tier2_component.py 1 등)도 함께 제거 대상.
C-3b (보류 — A-4 M2 결정 사항): isolation.root 행 필드 소비자(verify_session_uuid 의 iso_root 분기, mam_session_iso_root, find_workspace_uuid 격리 분기, stop_session.sh:277 purge 가드). b4a1d094 / 44062a63 에서 의도적으로 되살린 코드이므로 지우면 그 수정이 회귀합니다.

C-4: 참조 0회 미사용 심볼 — ⚠️ 목록 정정됨 (7종 → 실질 3종)

실제 대상 3종: _REAL_HERDR_PATH(대입·export 만), TERMINAL_STATUSES(registry.py:38 정의만), ISOLATE(create_session.sh:57 대입만).
목록에서 제외: _HERDR_SHIM_DIR_PATTERN 은 사용 중입니다(lib.sh:57 정의 → lib.sh:79 사용). 지우면 shim 경로 판정이 깨집니다. local_herdr 은 참조 0건으로 이미 제거되었습니다.
provision_isolation 은 C-3a 와 중복이므로 그쪽에서 함께 처리합니다.

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. 🧭 우선순위 실행 로드맵 (Prioritized Execution Roadmap)

평가 근거·항목별 실측 결과는 .mam/jobs/ecef05a3/claude-reports/report-final.md 참조. 순위를 매기기 전에 12건을 전부 현재 코드에 대조했으며, 그중 4건(A-2·B-5·C-3·C-4)의 기존 서술이 현재 코드와 달라 본문을 정정했습니다.

6.1 정렬 원칙

① 외부에서 트리거 가능한 위험 → ② 검증 신호를 거짓으로 만드는 결함 → ③ 다른 항목을 싸게 만드는 구조 작업 → ④ 국소 결함 → ⑤ 정리.

조용한 실패에 가중치를 둡니다. 시끄러운 실패는 사람이 보지만, 조용한 실패는 "통과"로 기록되고 그 위에 다음 작업이 쌓입니다.

6.2 실행 순서

순위	항목	근거	비용	선행
P0-1	A-2	공개 브로커 + `auth_token` 발급 0건 + 전역 토픽 발행이 한 줄로 이어져 원격 pane kill 체인이 완결됨 (실측: 26/26 잡이 `topic_prefix=python/mqtt/jobs/...`, `auth_token=None`)	중 (3파일)	—
P1-1	B-7	저장소 밖 기동 시 리뷰어가 문자열 `"No git diff available"` 로 `[VERDICT: PASS]` 를 냄. 신규(미추적) 파일은 리뷰 대상 밖. 나머지 11건의 검증 근거를 훼손	소 (1파일)	—
P1-2	O-2	마커를 조건 없이 덮어쓰고 종료 트랩이 타 인스턴스의 마커까지 삭제 → 완료 처리된 O-3 가드가 조용히 무력화됨	소~중 (1파일)	—
P2-1	A-4 M0~M1	`PYTHONPATH` 부트스트랩·배포/CI 등록·`own_key` 이관. B-8/B-10/C-3b 를 싸게 만듦	중	B-7
P2-2	B-8	agy 주입이 검증 없이 `return 0` → 아무것도 전달되지 않은 잡이 `started` 로 기록됨. A-4 M0(`_pane_capture` 디코딩) 이후엔 회피책 제거로 축소	소	A-4 M0
P3-1	B-6	버전 관리 트리 오염 + rsync 배포 유출. `mktemp -d` 로 옮기는 1~2줄	소	—
P3-2	C-3a + C-4	빈 스텁 4종 + 이를 고정하던 공허한 테스트 5건 + 죽은 심볼 3종 제거 (회귀 시간 단축 효과)	소	—
P3-3	C-6	도움말 3줄 정정	극소	—
P4-1	A-4 M2~M7	어댑터 본이관. 진행 중 B-10 · C-3b 처분 결정	대	P2-1
P4-2	B-10	tier-3 신원 캐시 존치/제거 결정 + PyYAML 의존 완화	중	A-4 M2
P4-3	C-3b	`isolation.root` 소비자 처분 결정	소	A-4 M2
P5	B-9	기본값 한정. `logs_dir` 인자·`DELEGATE_JOB_LOGS_DIR` 두 가지 회피 수단 존재	극소	—
종결 권고	B-5	폴백(`df -P`)으로 이미 해소 — 서술된 실패가 재현되지 않음	—	—

A-2 를 B-7 보다 앞에 두는 이유: B-7 의 피해는 우리 워크플로 내부에 머물고 리뷰 결과를 다시 읽으면 회복 가능하지만, A-2 는 외부에서 트리거되고 살아 있는 세션을 파괴하며 우리 쪽 행동으로 예방할 수 없습니다.

정리(C 계열)를 P3 에 두는 이유: (a) C-3a 는 공허한 테스트 5건을 함께 제거해 이후 모든 전체 회귀를 단축하고, (b) C-4 는 잘못 실행하면 버그를 만듭니다(아래 6.5). 방치할수록 누군가 "쉬운 정리"로 집어 들 확률이 올라갑니다.

6.3 병렬 실행 — 파일 소유권 슬롯 (Rev.2 교체)

Rev.1 은 "주제별 트랙"으로 병렬화를 서술했고 그 분해는 4곳에서 틀렸습니다(챌린지 7d604ee7 계기로 파일 단위 재대조). 병렬 단위는 주제가 아니라 파일입니다.

항목별 처방이 건드리는 파일

파일	건드리는 항목
`run_loop.sh`	B-6, B-7, O-2
`lib.sh`	A-4, B-8, B-10, C-3a, C-4
`reconcile.sh`	A-2, A-4, B-10
`mqtt_common.py`	A-2, B-9
`stop_session.sh`	B-10, C-6
`registry.py`	A-2, C-4
`create_session.sh`	A-4, C-4

슬롯 배치 — 슬롯 안은 직렬, 슬롯 간은 병렬

슬롯	순서
`run_loop.sh`	`B-7` → `O-2` → `B-6`
`lib.sh`	`C-3a`+`C-4` → `B-8`
MQTT 계열 (`mqtt_common.py`·`registry.py`·`publish_event.py`·`job_subscriber.py`·`reconcile.sh`)	`A-2` → `B-9`
`stop_session.sh`	`C-6`
단독 실행 (슬롯 경계를 넘음)	`A-4`, `B-10`

A-4(lib.sh+reconcile.sh+create_session.sh+resume_session.sh)와 B-10(lib.sh+reconcile.sh+stop_session.sh)은 어떤 슬롯 조합과도 겹치므로 단독 실행합니다.
A-4 는 신규 파일을 대량 추가하므로 B-7 이 먼저 닫혀 있어야 리뷰가 성립합니다.
Rev.1 오류 정정 4건: B-6(트랙 C→run_loop.sh 슬롯), C-3a·C-4(트랙 C→lib.sh 슬롯), B-9(독립→MQTT 슬롯), C-6(독립→stop_session.sh 슬롯).
참고: reconcile.sh 는 MAM_LOOP_MARKER·send_keys_safe 를 참조 0건이므로 O-2·B-8 과는 경합하지 않습니다(자체 .mam/monitor.lock 보유).

6.4 B-7 처방 (Rev.2 신설 — 진단만 있고 처방이 없었음)

cd "$REPO_ROOT" 만으로는 미추적 신규 파일이 여전히 100% 누락됩니다. git diff 는 정의상 추적 파일만 봅니다.

CHANGES_DIFF=$(
  cd "$REPO_ROOT" || exit 1
  git diff "$BASE_COMMIT"
  # 미추적 신규 파일을 인덱스 변경 없이 덧붙인다.
  # --exclude-standard 가 .gitignore / .git/info/exclude 를 그대로 존중한다.
  git ls-files -o --exclude-standard -z | while IFS= read -r -d '' f; do
    git diff --no-index --binary /dev/null "$f" 2>/dev/null || true
  done
)

git add -N . 은 채택하지 않습니다. 미추적 파일을 diff 에 넣는 목적은 달성하지만(실측 확인) 인덱스에 A 항목을 남기며, 그 상태에서 Creator 가 git commit -am 을 실행하면 추가한 적 없는 파일이 내용째 커밋됩니다(실측 확인). run_loop.sh 는 Creator 가 같은 저장소에서 작업하는 동안 반복 실행되므로 실제 위험입니다. 위 대안은 동일 결과를 내면서 인덱스를 건드리지 않습니다.

크기 상한도 함께 필요합니다. 현재 CHANGES_DIFF(537·539행)는 아무 제한 없이 547행 리뷰 프롬프트에 보간되고 send_keys_safe paste-buffer 로 주입됩니다. 미추적 파일을 포함시키면 커지기만 하므로 상한을 두고, 초과 시 --stat 요약으로 대체하되 잘렸다는 사실을 리뷰어에게 반드시 노출해야 합니다(조용히 자르면 "빈 diff PASS" 가 "부분 diff PASS" 로 바뀔 뿐입니다). 구체적 임계값은 구현자가 샌드박스 세션에서 paste-buffer 실패 지점을 측정해 확정할 것.

6.5 ⚠️ 실행 전 반드시 확인할 정정 사항

C-3 은 그대로 실행하면 회귀를 만듭니다. 항목이 성격이 다른 둘을 묶고 있습니다.
- C-3a (즉시 실행 가능): provision_isolation / isolation_lever / isolation_env_prefix / isolation_cmd_args 4종 빈 스텁 — 프로덕션 호출자 0건. 이를 고정하던 tests/test_tier1_unit.py 3건 + tests/test_tier2_component.py 1건도 함께 제거 대상.
- C-3b (보류 — A-4 M2 결정 사항): isolation.root 소비자(lib.sh verify_session_uuid 의 iso_root 분기, mam_session_iso_root, find_workspace_uuid 격리 분기, stop_session.sh:277 purge 가드). b4a1d094 / 44062a63 에서 방금 의도적으로 되살린 코드이며, 지우면 그 수정이 되돌아갑니다.
C-4 의 "7종" 중 2종은 사실과 다릅니다.
- _HERDR_SHIM_DIR_PATTERN — 사용 중입니다 (lib.sh:57 정의, lib.sh:79 사용). 목록대로 지우면 shim 경로 판정이 깨집니다.
- local_herdr — 참조 0건, 이미 제거됨.
- 실제 대상은 _REAL_HERDR_PATH, TERMINAL_STATUSES, ISOLATE 3종이며 provision_isolation 은 C-3a 와 중복입니다.
A-2 의 원인 표현 정정 — verify_hmac 구현 자체는 정상입니다(토큰이 있으면 hmac.compare_digest 로 검증). 원인은 토큰이 아무 데서도 발급되지 않아 검증이 공허해지는 것 + 발행자가 워크스페이스 지문 토픽을 채택하지 않은 것입니다. 수정은 ① 발행자 토픽 교체 ② reconcile.sh:237 레거시 전역 구독 제거 ③ verify_hmac fail-closed + 토큰 발급 순입니다.
B-5 잔여분 — 폴백으로 감지는 정상화됐으나 mount | grep -E "$mountpoint.*(nfs|...)" 가 마운트포인트를 이스케이프 없이 ERE 에 보간합니다(경로의 . 이 임의 문자로 해석). 이것만 신규 항목(B-11)으로 분리 권고.

6.6 결론

IMPROVEMENTS.md 는 남은 백로그 항목(아키텍처 2건, 엣지케이스 6건, 오케스트레이션 1건, 레거시 잔재 3건 — 총 12건)을 위 우선순위에 따라 일원화된 보완 로드맵으로 관리합니다.

31 KiB Raw Blame History

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