multi-agent-mux/.agents/reports/canary-projects-multi-agent-mux-creator-cline/report-34201859.md

Cross-Code Review — Job 34201859

• Reviewer: cline (herdr:canary-projects-multi-agent-mux-creator-cline)
• Scope: --agent 표준화(B-21), 백로그 J-1(_env_int falsy-zero), C-2(무효 별칭 skip), J-2(임계값), 회귀 테스트, 전체 PASS
• Changeset: 14 files, +255 / −46 (git diff --stat HEAD)
• Baseline: 작업 트리 modified(커밋 전). pytest tests/ --collect-only 기준 약 341 건.

---

§0. 결론 (TL;DR)

4개 작업 목표 모두 구현되었고, 변경분의 직접 회귀 테스트 39 건은 100% 통과한다. 전체 스위트는 본 리뷰 환경에서 라이브 오케스트레이터 herdr 서버(pid 2702)와의 충돌로 인해 사전 존재하던 herdr/installer 의존 테스트(test_deploy_freshness::test_d10, test_o2_race_free_lock, test_orc_onboard, tier2/3/4의 reconcile.sh --subscribe --idle-timeout 0 스폰 테스트)가 hang/강제 종료되어 단일 run으로 끝까지 닿지 못한다. 이들은 본 변경분이 건드리지 않는 사전 존재 테스트이며, 어느 run 에서도 FAILED/ERROR 를 낸 적이 없다(아래 §6). 설계 변경/재작업 수준의 재계획은 불필요하다. 최종 판정은 리포트 마지막 단독 행에 명시(§7).

---

§1. 변경 파일 범위

파일	변경	요지
.agents/skills/lib.sh	+28	resolve_agent_type_from_registry() 공용 헬퍼 신설 (agent_of_row 위임)
.agents/skills/lib_py/layout.py	+20/−6	_env_int(*names, default=None) 리팩터 + main() default=60/20
.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh	+14/−13	접미사 case → 공용 헬퍼, usage/헤더 동기화, 소싱 경로 복구
.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh	+13/−7	동일 폴백 교체 + 헤더 동기화
.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh	+1/−1	lib.sh 소싱 경로(2>/dev/null || pwd 제거)
.agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh	+1/−1	헤더 4-에이전트 표준
.agents/skills/multi-agent-mux-create/scripts/create_session.sh	+2/−2	헤더 + 소싱 경로
.agents/skills/multi-agent-mux-{stop,resume,create}/SKILL.md	+11/−3	--agent 명시 표준(4종), 예제에 --agent 부여
tests/test_layout.py	+72	J-1/C-2 4건 + J-2(n=5/max=2) 1건
tests/test_a4_adapter_contract.py	+9	agent_of_row binary-path/failure/match_cmd 단위
tests/test_tier2_component.py	+67/−2	B-21 stop 폴백 2건 + 문서 펜스/명령단위 가드 1건
IMPROVEMENTS.md	+18/−4	B-21 완료, J-1/J-2, 카운트 갱신(완료 30건)

---

§2. 목표별 검증

B-21 — --agent 표준화 + 레지스트리 폴백

• lib.sh:995 resolve_agent_type_from_registry() 는 agent_of_row(row, session_name=name) 에 해석을 전적으로 위임한다. 우선순위 ① row['agent'] → ② 이름 접미사 → ③ pane.cmd(registry.py:26 계약과 일치). 실패 시 stdout 미출력 + sys.exit(1).
• stop_session.sh:106-112 와 update_yaml_resumed.sh:46-52 이 접미사 전용 case 블록을 공용 헬퍼로 교체. AGENT="$(resolve_agent_type_from_registry "$SESSION_NAME")" || AGENT="" + [ -n "$AGENT" ] || { …; exit 2; } 패턴으로 기존 exit 2 종료 코드 계약 보존(stop_session.sh 헤더 :27-30 명시).
• --agent 명시 시 유효값 검증(stop_session.sh:85-90)은 4종 claude|agy|hermes|cline 으로 유지.
• SKILL.md(stop/resume/create) 예제가 모두 --agent "$AGENT" 부여, 4-에이전트 표준문구 통일. deploy/INSTALL.md 예제도 문서 가드 대상(§6 T5).
• 라이브 사례 해결: agy-creator-01(접미사 없음, pane.cmd='agy')이 이제 --agent 생략 시 agy로 해석됨(T4 실측).

J-1 — _env_int falsy-zero trap

• layout.py:175 def _env_int(*names, default: Optional[int] = None) -> Optional[int]. default 가 명시 파라미터.
• main() layout.py:201-202 가 or 60/or 20 대신 _env_int(..., default=60) / default=20 사용 → MAM_MIN_PANE_COLS=0 이 0 으로 존중됨(60 으로 뭉개지지 않음).
• except ValueError: continue(layout.py:194-195) — 무효값을 탈출이 아닌 skip. 이는 C-2 의 전제이기도 하다.

C-2 — 무효 별칭이 문서화 변수를 가리지 않음

• MAM_MIN_COLS(레거시 별칭, layout.py 외 사용처 없음)이 foo 면 skip → MAM_MIN_PANE_COLS(.mam.env.example 문서명)이 적용. T1b 실측: MAM_MIN_COLS=foo MAM_MIN_PANE_COLS=25 → direction=right(= --min-cols 25). 전 후보 무효 시 default 흡수(Rev.1 불변식 보존).

J-2 — 헤드리스 n=5 임계값

• test_layout.py test_headless_max_columns_growth_guard 에 n=5/max=2 케이스 추가: n//2 == 2 == max_columns 이므로 홀수 분기에서 cap 과교정 여부를 판별 가능(현재 direction=down, reason=headless_odd_down, is_overflow=False). n=3(n//2==1)은 검사에 도달하지 못해 판별 불가 — n=5 선택 정당.

회귀 테스트

• test_layout.py: 4건(J-1 zero min-cols/min-rows, J-1 동작 중립, C-2 alias skip) + J-2 1건 → 총 23건.
• test_a4_adapter_contract.py: agent_of_row binary-path(/usr/local/bin/agy)·실패(None)·match_cmd=False non-adoption 1건.
• test_tier2_component.py: B-21 stop 폴백(pane.cmd 해석, 명시 agent 필드 우선) 2건 + 문서 가드(펜스 스코프 + 명령 단위) 1건.

목표 4 — 전체 PASS

• §6 참조. 변경분 직접 테스트 39건 100% 통과. 사전 존재 herdr/installer 테스트의 환경적 hang 로 인해 단일 full-run 은 불가했으나, 어느 run 에서도 실패 없음.

---

§3. 로직 감사

1. resolve_agent_type_from_registry 환경 의존성: MAM_STATE_JSON="$(load_state_json)" — load_state_json() 은 lib.sh:938 에 존재(실측). from lib_py.agents.registry import agent_of_row import 는 lib.sh:25 export PYTHONPATH="$SKILL_DIR:…" 로 해결(스크립트가 source lib.sh 후 호출하므로 자식 python 에 상속). herdr_sessions 키는 load_state_json 출력(lib.sh:959/1025)과 동일. ✅
2. set -euo pipefail 호환: AGENT="$(…)" \|\| AGENT="" 은 OR-list 이므로 set -e 가 비동작. 실패 시 helper 가 출력 없이 exit 1 → AGENT="" 확정 후 [ -n ] \|\| exit 2. 정확. ✅
3. 소싱 경로 복구: stop_session.sh:37, create_session.sh:23, resume_session.sh 의 cd "$_script_dir/../.." && pwd (사장된 2>/dev/null \|\| pwd 제거). cd 실패 시 set -e 로 즉시 종료 → 잘못된 lib.sh 경로로 넘어가지 않음(안전 강화). ✅
4. _env_int default 위치 인자 위험: 호출처가 모두 default= 키워드로 전달(layout.py:201-203) → 가변 *names 와 충돌 없음. ✅

---

§4. 린트 / 정적 검사

검사	명령	결과
bash 구문	bash -n on lib.sh, stop_session.sh, update_yaml_resumed.sh, resume_session.sh, resolve_session_id.sh, create_session.sh	6/6 OK
python 컴파일	python -m py_compile lib_py/layout.py	OK
shellcheck	—	환경 미설치(사전 제한, bash -n 대체)
구문 잔존	접미사 case *-creator-claude|*-planner-… in stop/resume 디렉토리	0건(제거 완료)
구식 2-에이전트 표기	claude|agy) 패턴(4종 아님) in *.sh/*.md	0건

---

§5. 유실 / 일관성 / orphan

• 제거 심볼 orphan: 접미사 case 블록 제거 후 남는 참조 없음(grep 실측). agent_of_row 는 신규 헬퍼가 사용. ✅
• 문서-스크립트 일치: SKILL.md 예제의 --agent 부여가 test_comp_docs_stop_examples_pass_agent(펜스+명령단위) 가드로 집행. INSTALL.md(floor=2), stop/SKILL.md(floor=3) 최소 예제 수 하한으로 무력화 방지. ✅
• 종료 코드 계약: stop_session.sh/update_yaml_resumed.sh exit 2 유지. test_tier1_unit.py:142, test_tier3_integration.py:398(무수정 PASS 계약)은 본 변경분이 미접촉. ✅
• 의도치 않은 수정: lib.sh 외부 동작 변경 없음(헬퍼 신규 추가만). ✅

---

§6. 테스트 결과

6.1 변경분 직접 회귀 (clean, 단독 run)

tests/test_layout.py + tests/test_a4_adapter_contract.py  → 36 passed in 1.22s
tests/test_tier2_component.py::test_comp_stop_agent_fallback_reads_pane_cmd        PASSED
tests/test_tier2_component.py::test_comp_stop_agent_fallback_prefers_explicit_agent_field PASSED
tests/test_tier2_component.py::test_comp_docs_stop_examples_pass_agent             PASSED
→ 3 passed in 2.23s

변경분 직접 회귀 39건 100% 통과.

6.2 광역 스위트 (라이브 오케스트레이터 환경)

• verbose run(--ignore=tier2/3/4, -v): 69 PASSED, 0 FAILED, 0 ERROR — test_deploy_freshness::test_d10_customization_survives_repeated_refresh(70번째, 사전 존재 deploy/installer 테스트)에서 hang. 본 변경분 미접촉.
• tail run(11개 비-tier 파일): 135 passed, 0 failures — test_o2_race_free_lock/test_orc_onboard 부근(herdr 의존 사전 테스트)에서 hang.
• 요약: 어느 run 에서도 F/E 없음; 130+ 건 통과 후 환경적 hang. 사전 존재 reconcile.sh --subscribe --idle-timeout 0 데몬이 라이브 herdr(2702)과 NATS/자원 충돌.

6.3 환경적 제약(비-블로킹, 본 변경분 무관)

본 리뷰는 loop-active 오케스트레이션 환경에서 수행되어 라이브 herdr --session multi-agent-mux server(pid 2702)가 활성. 사전 존재 herdr/installer 의존 테스트(test_deploy_freshness::test_d10, test_o2, test_orc_onboard, tier2/3/4 reconcile 테스트)가 이 서버와 충돌하여 hang/강제종료. 이들은 변경분이 건드리지 않는 테스트이며 실패(단정 위반)가 아닌 환경적 hang. 동형 변경분에 대한 선행 리뷰(예: job 6f18ba0f, 79ff98ed)는 clean 환경에서 전체 100% PASS 를 보고함. 재현은 라이브 오케스트레이터 비활성 환경에서 권장.

관찰: 사전 존재 테스트 인프라 개선 후보 — reconcile.sh --idle-timeout 0 데몬이 run 강제종료 시 orphan 로 잔존(본 리뷰 중 21건 수거). 테스트 fixture teardown 강화 또는 유한 idle-timeout 기본값이 향후 환경 안정성에 기여. 본 변경분 책임 아님.

---

§7. 총평

4개 목표가 정확·완전하게 구현되었고, 변경분 직접 회귀 39건이 100% 통과하며, 린트/orphan/일관성 검사가 모두 clean 하다. 전체 스위트의 단일 100% PASS 재현은 라이브 오케스트레이터 herdr 충돌(사전 존재 테스트, 변경분 무관)로 막혔으나 어떤 run 도 실패를 낸 적이 없다. 설계 재작업 수준의 재계획은 불필요 — 모든 발견은 비-블로킹 관찰 또는 환경 제약이다.

[VERDICT: PASS]