multi-agent-mux/FUTURE_WORKS.ko.md

FUTURE_WORKS.md

목적: multi-agent-mux 프로젝트의 향후 작업 후보를 추적한다. 완료된 항목은 DONE.ko.md를 참조. 최종 갱신: 2026-06-24

---

향후 개선 작업 로드맵

현재 대기 중인 향후 작업(Future Works) 항목입니다. 본 항목들은 시스템의 보안, 동시성, 이식성 및 워크플로우 분석을 바탕으로 제안되었습니다.

ID	과제명	우선순위	작업량	해결 분야 / 설명	의존성
FW-L4	Job Registry의 SQLite 마이그레이션 및 NFS flock 한계 극복	P3 (Low)	대	동시성/인프라 확장성: 세션 레지스트리와 마찬가지로 개별 JSON 파일 락(fcntl.flock) 방식의 잡 레지스트리를 SQLite 데이터베이스 트랜잭션 구조로 통합 마이그레이션하여, NFS 등 분산/네트워크 FS 환경에서의 안정성을 완전 확보	조건부 (실제 멀티 호스트/NFS 배포 필요 발생 시 착수)
FW-P1	lib.sh 내 GNU/Linux 유저랜드 가정 제거	P2 (Medium)	소	이식성: lib.sh에 포함된 GNU coreutils 전용 명령(df --output=target 및 리눅스 mount 포맷 분석)을 이식 가능한 명령어로 대체하여 macOS/BSD에서 NFS 감지가 자동 무력화되는 사각지대 해결	없음
FW-P2	윈도우 환경을 위한 명시적인 동시성 제어 전략 제공	P1 (High)	중	이식성 / 동시성: fcntl이 POSIX 전용이므로 mqtt_common.py 임포트 실패 시 예외가 발생하는 문제를 스타트업 시점에 감지하여 사용자 친화적 경고와 함께 조기 종료하게 하거나, 윈도우용 msvcrt.locking 등으로 락 메커니즘을 동적 매핑함. 이벤트 감사 로그를 기록하는 _file_lock은 설계 사양대로 best-effort(무영향) 속성을 유지함	없음
FW-P3	가상환경(virtualenv) 로딩 및 의존성 사전 검증 강화	P2 (Medium)	중	이식성: requirements.txt의 paho-mqtt 2.x 의존성 선언 외에, UV/Poetry 등 독립 툴 체인에서 가상환경 인터프리터 불일치를 조기 차단하고, 실행 진입점(entrypoint)에서 필수 라이브러리 탑재 여부를 즉시 검증하는 진단 로직 추가	없음
FW-P4	기본 MQTT 브로커 및 네임스페이스 보안 강화	P1 (High)	중	이식성 / 보안: 공용 브로커인 broker.hivemq.com과 열린 네임스페이스 대신, 사설 TLS 브로커 크레덴셜을 기본 템플릿으로 제공하여 원격 세션 탈취 및 도청 공격 위협 원천 방지	없음
FW-P5	zsh 환경 하에서의 BASH_SOURCE 경로 오작동 해결	P2 (Medium)	소	이식성: zsh 쉘에서 lib.sh를 대화형으로 sourcing할 때 ${BASH_SOURCE[0]}가 공백으로 평가되어 스킬 경로(SKILL_DIR)를 잘못 설정하는 오류 해결	없음
FW-P6	마커 파일 조회를 통한 프로젝트 루트 동적 감지	P1 (High)	중	이식성: lib.sh, status.sh, reconcile.sh 등 여러 스크립트에서 ../.. 등 상대 경로 깊이를 하드코딩하여 발생하는 취약성 해결. .git, .mam, .env 등을 찾는 상위 탐색 마커-파일 워크 방식을 적용하고, 단일한 WORKSPACE_ROOT 환경변수로 통일하여 오케스트레이션 안정성 확보	없음
FW-P7	모니터 종료 경로에 대한 HMAC 서명 검증 및 활성 상태 체크 강화	P1 (High)	중	이식성 / 보안: reconcile.sh가 verify_hmac 서명 검증 없이 completed/error 이벤트만으로 세션을 즉시 강제 종료하는 리스크 해결. 모니터링 이벤트 핸들러(on_message)에서 보안 토큰 검증을 필수 처리하고, kill-session 전 실제 tmux 활성 여부와 예상 아티팩트 보존 상태를 대조하게 설계	없음
FW-W1	글로벌 레지스트리 락을 세밀한 락(Fine-grained locks)으로 대체	P2 (Medium)	중	동시성 / 확장성: 모든 세션 및 progress/sequence 업데이트가 단일 .mam/jobs/ 글로벌 fcntl lock을 거치며 생기는 병목 차단. 잡 단위의 개별 락 파일 도입	없음
FW-W2	블라인드 TUI 키 입력 방지를 위한 실행 준비도 검증	P2 (Medium)	대	워크플로우: 세션 생성, 재개, 중지 시 단순 sleep(예: 6초) 대신 터미널 스크린 스크랩이나 준비도 프로브(Readiness Probe)를 활용하여 다이얼로그나 예외 창을 안전하게 차단	없음
FW-W4	구독자 시퀀스 번호(last_seq)의 디스크 영속화	P1 (High)	중	워크플로우 / 보안: 와치독 재기동 시 시퀀스 카운터가 리셋되는 구조적 취약을 방지하기 위해 subscriber.last_seq를 디스크/DB에 기록하여 잡 라이프타임 전체를 커버하는 Replay 방어선 유지	없음
FW-W5	리뷰어 판정을 위한 구조적 메시지 스키마 정의	P2 (Medium)	중	워크플로우: PM 에이전트가 터미널 스크롤백 문자열을 무가공 grep 파싱하는 대신, 전용 리뷰 피드백 토픽(예: reviews/<job_id>/verdicts) 및 정형화된 JSON 포맷(PASS/NOT_PASS + 차단 요인) 도입	없음
FW-W6	모니터링 복구 루프의 Hermes 에이전트 지원 확장	P2 (Medium)	중	워크플로우 / 일관성: reconcile.sh 내 자동 등록(drift-B) 및 ID 동기화(drift-C) 로직에 hermes 세션을 완전 편입시켜 Claude/Agy 세션과 동일한 모니터링 및 복구 수준 지원	없음
FW-W7	derive_session_name 내 디렉터리 경로 슬러그 이름 충돌 해결	P2 (Medium)	소	워크플로우 / 충돌 방지: 마지막 2개 디렉터리만 슬러그화할 때 발생하는 동일 이름의 중첩 디렉터리 세션 이름 충돌(예: /projectA/src 및 /projectB/src 가 동일한 세션명으로 슬러그화됨)을 해결하기 위해 워크스페이스 범위 해시 값을 포함하는 세션명 명명 규칙 적용	없음
FW-D1	✅ 해결됨 (2026-06-24) — 설치 스크립트가 더 이상 in-place 추출하지 않음	—	—	배포 / 안전성: deploy/install.sh는 이제 다운로드를 mktemp -d 임시 디렉터리에 스테이징하고 .agents/skills/lib.sh 존재를 검증한 뒤, 런타임 자산(.agents/, .env.example)만 per-file no-clobber 가드([ ! -e ])로 타겟에 복사한다. 따라서 기존 타겟 파일이 항상 우선하며 레포 개발 문서가 워크스페이스에 들어가지 않는다. fetch 후 sanity 체크도 디렉터리가 아닌 파일을 검사하도록 변경	완료
FW-D2	설치 스크립트가 다운로드하는 소스를 sourcing 전에 고정 및 검증	P2 (Medium)	소	배포 / 공급망: 설치 스크립트는 네트워크로 이동형 main 브랜치를 clone/추출하고, 워크스페이스는 이후 해당 셸 스크립트(lib.sh 등)를 source한다. 부분 해결 (2026-06-24): 복사 전에 스테이징된 트리에 .agents/skills/lib.sh가 존재하는지 검증함. 남은 작업: 릴리스 태그나 커밋 SHA로 고정하고 공개 체크섬을 검증하여 구조적 존재 여부뿐 아니라 콘텐츠 무결성까지 보장	없음
FW-D3	install.sh와 lib.sh 간 NFS 감지 로직 중복 제거	P2 (Medium)	소	배포 / 이식성: deploy/install.sh가 lib.sh::_check_is_nfs에 이미 존재하는 GNU 전용 df --output=target + mount NFS 검사를 재구현한다. FW-P1 이식성 수정이 이 두 번째 사본까지 포함하도록, 단일 공유 헬퍼로 추출하여 macOS/BSD에서 두 호출 지점 모두 올바르게 동작하게 한다	FW-P1
FW-D4	CI shellcheck 커버리지 공백 해소	P3 (Low)	소	배포 / 품질: deploy/gitea-ci.yml은 5개 스크립트만 shellcheck하며, status.sh, resolve_session_id.sh, update_yaml_resumed.sh, scripts/generate-env.sh는 검사되지 않는다. 추적되는 모든 *.sh를 glob 처리하여 신규 스크립트가 자동 포함되도록 한다	없음

---

세부 논의 결과 및 방향성 (Reviewer 합의 사항)

1. SQLite 통합(FW-L4)의 조건부 연기:

   • 세션 레지스트리와 달리 개별 잡 데이터는 JSON 파일 구조가 관리 및 디버깅 직관성이 우수하며, 현재 배포 환경은 단일 호스트 로컬 FS로 제한되어 있어 fcntl.flock 잠금만으로 안전하게 운용 가능하므로 낮은 우선순위(P3)로 배정하고 필요 시 착수합니다.

2. 윈도우 환경을 위한 명시적인 동시성 제어 전략 제공 (FW-P1, FW-P2):

   • 동시성 제어 시스템에서 오류 시 락 없이 그냥 실행되는 침묵형 오작동(Silent failover)은 가장 위험한 구조입니다. 윈도우 환경에서 fcntl 모듈 누락 시 묵인하지 않고 진입점에서 명시적인 조기 경고를 내어 POSIX 환경이나 전용 래퍼 실행을 유도하고, 혹은 msvcrt.locking 파일 제어 전략을 동적 매핑하여 플랫폼 전반의 안전성을 담보해야 합니다.

3. 마커 파일을 통한 동적 루트 앵커링 (FW-P6):

   • 하위 경로 탐색 시 특정 파일의 상대 경로 깊이(../.. 등)에 의존하는 구조는 디렉터리 리팩토링이나 래퍼 이동 시 치명적 취약점으로 작용합니다. 디렉터리 트리를 따라 .git이나 .mam 등 알려진 루트 표시 마커를 동적으로 검색하는 방식을 채택하여 스크립트 실행 안정성과 이식 속도를 획기적으로 개선합니다.

4. 모니터 종료 권한 제어 강화 (FW-P7):

   • 세션 강제 종료(tmux kill-session) 권한은 안전하게 제어되어야 합니다. 모니터(reconcile.sh)가 와일드카드 토픽을 무검증 수신하여 즉시 세션을 정리하면 위조 주입 공격에 취약해집니다. 종료 이벤트 수신부에 HMAC 서명 검증을 의무화하고, 세션 강제 중지 전 예상되는 작업 결과물(Artifact) 존속 상태를 교차 검토하도록 설계합니다.

5. 개별 잡 와치독의 단일 와일드카드 구독자 통합 (FW-W3):

   • 매 잡마다 개별적으로 실행되어 2분 주기로 끊고 재연결하던 watchdog.sh 프로세스 방식 대신, 상시 기동되는 reconcile.sh --subscribe 단일 와일드카드 구독자 구조로 이벤트 처리, HMAC 보안 검증 및 시퀀스 추적 로직을 완전히 통일했습니다. 이를 통해 불필요한 MQTT 커넥션 급증을 원천 차단하고 세션 정리 과정을 간소화했으며, 메모리 캐시 기반 시퀀스 추적을 통해 Replay 공격 차단 정합성을 동시 실행 중인 모든 잡에 대해 안정적으로 제공합니다.

6. 배포 설치 스크립트 강화 (FW-D1 ~ FW-D4):

   • deploy/install.sh와 Gitea 템플릿은 가장 최근에 추가된(DONE.md 검증 라운드 이후) 리뷰가 가장 적은 영역이며, 검증된 오케스트레이션 코드가 실행되기 이전에 동작하는 유일한 경로입니다. FW-D1(릴리스 차단 항목)은 이제 해결되었습니다(2026-06-24): 처음 제안된 tar --exclude 거부목록(denylist) 방식 — 리뷰 결과 이식성이 없고, 더 심각하게는 비앵커드 --exclude="scripts" 패턴이 스킬 트리 내부의 scripts/ 디렉터리까지 제거하여 조용히 깨진 설치를 만든다는 점이 확인됨 — 대신, 임시 디렉터리 스테이징 + 런타임 자산 허용목록(allowlist) 복사 + per-file no-clobber 가드로 재구성했습니다. 이로써 파괴적 덮어쓰기 위험과 개발 문서 오염을 한 번에 해소했습니다. FW-D2는 부분 해결(복사 전 스테이징 트리 구조 검증)되었고, 남은 공급망 강화 작업은 fetch를 태그/SHA + 체크섬으로 고정하는 것입니다. FW-D3(NFS 감지 분기, FW-P1에 통합)와 FW-D4(CI 린트 커버리지)는 일관성/품질 부채로 남아 있습니다.