multi-agent-mux/VERSIONS.md

📜 Multi-Agent Mux 버전 이력 (VERSIONS.md)

이 문서는 multi-agent-mux 프레임워크의 버전별 주요 기능 추가, 아키텍처 개선, 버그 수정 및 품질 검증 이력을 기록합니다.

---

📌 현재 버전 개요 (Current Release)

• 프레임워크 버전: v4.4.4
• 최신 릴리스 일시: 2026-09-13 (KST)
• 기준 브랜치: main
• 핵심 아키텍처:
  • Terminal 상태 단방향 불변성 (engine.py, Issue #6 Phase 1): completed, error, cancelled 터미널 상태 진입 후 후속 이벤트나 업데이트에 의한 덮어쓰기를 엄격히 차단(Terminal Immutability). registry.py close 서브커맨드 및 fail-closed 조기 종료 도입.
  • Herdr 턴 완료 핸드셰이크 (lib.sh: wait_for_agent_idle, Issue #6 Phase 2): 위임 에이전트(claude, agy, hermes, codex 등)의 프롬프트 전송 후 Herdr 뷰포트 및 프로세스 상태를 관측하여 비동기 턴 종료를 결정론적으로 대기하는 핸드셰이크 프로토콜 확립.
  • Loop 모드 attempt_id 추적 및 안전 전이 (Issue #6 Phase 3): 워커/리뷰어 전환 시 동일 회차 내 재전이 충돌을 방지하는 attempt_id 규약 적용 및 4단계 fail-closed finalize_unfinished 보장.
  • 결정론적 종료 코드 계약 (Issue #6 Phase 4 & R1): 0 (Success), 1 (Failure / Inject error), 2 (Subscriber timeout; 단, 에이전트가 Herdr에서 working 중이면 벽시계 --timeout까지 디스크 재관측 후 fail-close), 3 (Broker unavailable), 5 (Precondition failed / session_busy) 표준화. (send_keys_safe 헬퍼의 배달 실패/busy 타임아웃 rc=4는 래퍼 차원에서 rc=1 실패로 수용).
  • 4-Way 버전 락스텝: lib.sh(MAM_VERSION) ↔ lib_py/loop/eager.py(FRAMEWORK_VERSION) ↔ VERSIONS.md ↔ 8개 SKILL.md.

---

🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)

모든 8개 스킬은 YAML frontmatter 메타데이터(author, version, platforms, environments) 표준화를 통해 v4.4.4로 동기화되어 배포됩니다.

스킬명	버전	역할 및 주요 책임	상태
multi-agent-mux-create	4.4.4	에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰	✅ 배포
multi-agent-mux-stop	4.4.4	대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop)	✅ 배포
multi-agent-mux-resume	4.4.4	온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원	✅ 배포
multi-agent-mux-status	4.4.4	실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회	✅ 배포
multi-agent-mux-monitor	4.4.4	YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop)	✅ 배포
multi-agent-mux-delegate-job	4.4.4	MQTT 이벤트 채널 기반 비동기 단위 작업 위임	✅ 배포
multi-agent-mux-loop	4.4.4	Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프	✅ 배포
multi-agent-mux-orc-onboard	4.4.4	오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지	✅ 배포

---

📋 버전별 상세 변경 내역 (Changelog)

🚀 v4.4.4 — Issue #12 레지스트리 비밀번호 제거, Issue #8 업데이트 스탬프 보존, Issue #7 형제 워크스페이스 패킹 (2026-09-13)

패치 마일스톤 (PATCH Release): 모든 서브에이전트가 읽을 수 있는 잡 레코드에 MQTT 브로커 비밀번호가 평문으로 복사되던 문제(Issue #12), deploy/update.sh 가 인스톨러가 새로 쓴 version.txt·asset_hashes.txt 를 업데이트 전 값으로 되돌리던 문제(Issue #8), 같은 cwd 의 첫 워크스페이스만 검사해 다섯 번째 에이전트부터 에이전트마다 워크스페이스를 새로 열던 문제(Issue #7)를 해결했다. 새 registry.py scrub-secrets 는 추가 서브커맨드이며 공개 계약·종료 코드 변경은 없다. 브로커 비밀번호는 이제 레코드가 아니라 환경(MQTT_PASSWORD, .mam.env)에서만 온다.

🌟 주요 개선 사항

1. 잡 레코드의 브로커 비밀번호 제거 (Issue #12, mqtt_common.BrokerConfig.to_registry_block, registry.py): to_registry_block 이 더 이상 password 를 레코드의 broker 블록에 넣지 않는다. broker_config_from_job 은 레코드 블록을 환경 설정 위에 겹치므로 접속 시 비밀번호는 MQTT_PASSWORD(.mam.env)에서 채워지고, publish_event 는 여전히 레코드만으로 접속한다. _atomic_write_record 는 쓰는 모든 레코드에서 broker.password 만 지우므로(다른 필드는 그대로) 이전 규칙으로 쓰인 레코드는 다음 쓰기 때 정리된다. auth_token·dispatch_token 은 에이전트 자신의 publish_event 가 서명과 attempt 고정에 쓰므로 레코드에 남긴다.
2. registry.py scrub-secrets [--dry-run] 마이그레이션 (Issue #12): 레지스트리 lock 아래에서 broker.password 를 가진 레코드만 골라 비밀번호를 지우고 재기록한다. --dry-run 은 대상 잡 목록만 출력하고 아무것도 바꾸지 않는다. registry.md 가 브로커 블록 규칙(비밀번호 비저장, 환경에서 복원, 토큰 유지 이유)을 문서화한다.
3. 업데이트 후 설치 스탬프 보존 (Issue #8, deploy/update.sh): 성공 경로가 업데이트 전 asset_hashes.txt·version.txt 를 되돌리지 않는다. 그 복원 탓에 version.txt 가 이전 커밋을 가리키고 remove.sh 가 갱신된 원본 파일을 "로컬 수정"으로 오판해 백업하던 문제가 사라진다. install_state 는 재설치가 쓰지 않은 키(예: gitignore_created)만 key=value 줄 단위로 병합하며(이미 있는 키는 건너뜀, 마지막 줄에 개행이 없어도 처리), 실패 경로(restore_on_failure)는 종전대로 세 파일을 모두 그대로 복원한다.
4. 같은 cwd 형제 워크스페이스 패킹 (Issue #7, lib.sh 쉼 new-session): 첫 번째로 일치한 pane 의 워크스페이스만 보던 탓에 가득 찬 첫 워크스페이스를 매번 overflow 로 판정해 에이전트마다 새 워크스페이스를 열던 문제(4 + 1 + 1)를 고쳤다. 이제 같은 cwd 의 모든 워크스페이스를 pane 순서대로 순회해 idle pane 이 있거나 2xK 그리드에 여유가 있는 첫 워크스페이스에 배치하고(overflow 인 후보는 다음 후보로 넘어감), 모두 가득 찼을 때만 새 워크스페이스를 만든다(4 + 2).

✅ 품질 검증

• 신규 테스트 8개: tests/test_issue7_workspace_packing.py 3개(여유 있는 형제 워크스페이스로 패킹, 모든 후보가 가득 찼을 때만 새 워크스페이스, 여유 있는 첫 워크스페이스 우선 — mock herdr 에 워크스페이스별 2x2 기하를 흉내 내는 opt-in layout_geometry: "2x2" 추가), tests/test_issue8_update_state.py 1개(실제 install→update 사이클에서 새 version.txt·해시 유지와 install_state 병합), tests/test_issue12_registry_secrets.py 4개(registry 블록에 비밀번호 없음, 등록된 레코드에 비밀번호가 없어도 환경 비밀번호로 접속, 레거시 레코드의 다음 쓰기 때 정리, scrub-secrets CLI 마이그레이션).
• 기존 테스트 조정: registry CLI 계약 스냅샷(tests/test_issue5_phase1_delegation.py)과 도움말 캡처(tests/fixtures/issue_5/phase1/help-registry.txt)에 의도된 scrub-secrets 서브커맨드를 반영하고, G6 가드에 _cmd_scrub_secrets 를 선언된 예외로 추가.
• 실측 (커밋 e629cc1·위임 브리프 기록): 관련 스위트 325개와 전체 스위트(worktree 기준) 통과.

🚀 v4.4.3 — Issue #10·#13 대화 purge 완결, Issue #11 메시지 정정, Issue #15 레지스트리 워크스페이스 고정 (2026-09-13)

패치 마일스톤 (PATCH Release): agy 대화 purge 가 resume 가능한 부속 파일을 남기던 문제(Issue #10), herdr 세션 행이 없는 오케스트레이터 대화를 어떤 스킬로도 지울 수 없던 문제(Issue #13), orc_onboard.sh --remove 의 "removeed" 오타(Issue #11), 호출자 cwd 를 따라가던 잡 레지스트리·감사 로그 때문에 pytest 스위트가 실제 .mam/jobs 에 테스트 레코드를 남기던 문제(Issue #15)를 해결했다. 새 서브커맨드·옵션은 모두 추가 기능이다. 레지스트리·감사 로그의 기본 경로는 WORKSPACE_ROOT 가 있으면 cwd 대신 그 워크스페이스를 따르며, 명시적 --registry-dir 와 MAM_JOBS_DIR/DELEGATE_JOB_LOGS_DIR 는 그대로 우선한다.

🌟 주요 개선 사항

1. agy purge 부속 파일 완결 (Issue #10, lib_py/agents/adapters/agy.py): purge_artifacts 가 대화 DB·brain/<uuid> 에 더해 SQLite 부속 파일(-wal/-shm/-journal — DB 를 열 때마다 생기고 stop 경로의 ID 캡처도 이를 만들며, 체크포인트되지 않은 WAL 에는 대화 내용이 남을 수 있다), 제목 annotation(annotations/<uuid>.pbtxt), presence lock(presence/<uuid>.lock)까지 지운다. presence lock 은 conversation_in_use 가 거짓일 때만 지우고, 사용 중이면 남긴 채 경고한다. agy 의 conversation_in_use 는 DB 만이 아니라 부속 파일·annotation·presence lock 전부를 lsof 점유 검사에 넘기므로, uuid 를 어디에도 적지 않은 채 lock 만 열어 둔 보유자도 잡는다. DB 가 이미 사라지고 WAL·annotation·lock 만 남은 고아 상태도 has_artifacts 가 인식해 purge 대상이 된다. 새 residual_artifacts() 는 ~/.gemini/antigravity-cli 아래에 그 uuid 를 이름에 가진 경로가 남아 있으면 보고한다. db+brain 만 있는 경우 2건을 돌려주는 어댑터 계약은 유지.
2. 오케스트레이터 대화 purge CLI (Issue #13, python -m lib_py.agents purge <agent|auto> <uuid> [workspace]): orchestrator_uuids 는 uuid 만 저장하므로 디스크에서 어댑터를 판별한다. auto 는 agy → claude → hermes → grok → codex → opencode 순으로(opencode 는 모든 uuid 에 대해 존재하는 공유 DB 라 마지막) 각 어댑터의 verify_artifact(revalidate 모드 — 오케스트레이터 대화는 워크스페이스 캐시에 없음)를 먼저, 그다음 uuid 가 들어간 artifact 경로의 존재를 확인한다. 살아 있는 프로세스가 그 uuid 를 참조하면 거부한다(base.conversation_in_use: ① 호출 환경의 세션 id — CLAUDE_CODE_SESSION_ID·ANTIGRAVITY_CONVERSATION_ID·HERMES_SESSION_ID·GROK_SESSION_ID·OPENCODE_SESSION_ID — 가 그 uuid 이면 사용 중, 즉 오케스트레이터가 자기 세션 안에서 자기 대화를 purge 하는 경우를 막는다(claude 는 transcript 를 열어 두지 않아 아래 두 검사로는 보이지 않는다). ② 프로세스 명령줄 검사에서 purge 자신의 헬퍼 사슬(python·셸·스크립트)만 빼되 가장 가까운 에이전트 CLI 조상에서 멈추고, 그 조상의 명령줄에 uuid 가 있으면 보유자로 센다. ③ lsof 로 artifact 점유 확인 — 어댑터가 넘긴 모든 경로(agy 는 DB·부속 파일·annotation·presence lock)). 결과는 JSON 한 줄(agent·purged·residual·in_use)이며 종료 코드는 0 purge 완료 / 4 사용 중이라 거부(아무것도 삭제하지 않음) / 5 해당 uuid 의 artifact 없음.
3. orc_onboard.sh --remove <uuid> --purge-conversation --yes [--agent <name>] (Issue #13): 위 purge 를 레지스트리 갱신 전에 실행하므로 거부되면 등록이 바뀌지 않는다. --yes 가 없으면 경고 후 exit 4, 대화가 사용 중이면 exit 5(등록 유지), 디스크에 대화가 없으면 경고 후 등록만 해제, --dry-run 은 예정 작업만 출력, --purge-conversation 은 --remove 와 함께일 때만 허용(exit 2). 성공 시 purge 된 경로와 잔여(residual) 검사 결과를 출력한다.
4. orc_onboard.sh 성공 메시지 과거형 (Issue #11): add/remove 를 added/removed 로 명시 활용해 "Successfully removeed" 를 없앴다.
5. 잡 레지스트리·감사 로그의 워크스페이스 고정 (Issue #15, mqtt_common.default_registry_dir·get_logs_dir): 기본 경로가 MAM_JOBS_DIR/DELEGATE_JOB_LOGS_DIR → $WORKSPACE_ROOT/.mam/jobs·$WORKSPACE_ROOT/.mam/delegate_job_logs → cwd 기준 .mam/… 순으로 정해진다. registry.py·publish_event.py·service.py 와 create_session.sh·stop_session.sh 가 같은 순서를 쓴다. 저장소 루트에서 돈 pytest 스위트(기본 온보딩 잡을 등록하는 create_session.sh)가 호출자 cwd 를 따라 실제 .mam/jobs 에 테스트 레코드 593건을 남기던 문제를 해소했고, 샌드박스 픽스처(tests/conftest.py)는 두 환경변수를 모두 고정한다.

✅ 품질 검증

• 신규 테스트 26개: tests/test_issue10_13_purge.py 19개(agy 부속 파일·annotation·lock 삭제, 사용 중 lock 보존, 존재한 것만 보고, 자기 계보를 뺀 in-use 판정, 비-에이전트 헬퍼 사슬만 제외하고 에이전트 CLI 조상은 검사, purge CLI 의 auto 판별·사용 중 거부·자기 에이전트 세션 안에서 거부·세션 id 환경변수 5종으로 거부·미해결 uuid, orc_onboard purge 의 --yes 요구·삭제 후 등록 해제·사용 중 거부·오케스트레이터 자기 세션에서 거부·artifact 없음에도 등록 해제·--remove 필수·dry-run 무변경, presence lock 만 연 보유자 거부, DB 가 없는 고아 부속 파일로 agy 해결·purge), tests/test_issue15_registry_isolation.py 7개(MAM_JOBS_DIR 우선, WORKSPACE_ROOT 추종, cwd 폴백, 로그 경로 동일 순서, CLI 기본값의 프로세스별 해석, 명시 env 로 온보딩 잡 샌드박스 유지, WORKSPACE_ROOT 만으로도 샌드박스 유지).
• 기존 테스트 조정: O-13(tests/test_orc_onboard.py)이 정정된 메시지를 단정하고, R1 헬퍼·B-9 로그 경로 테스트와 publish_event 스냅샷(tests/test_issue5_phase1_delegation.py·tests/test_tier1_unit.py)이 워크스페이스 고정 계약에 맞게 조정됨.
• 실측 (커밋 c82ea75·위임 브리프 기록): 전체 스위트 839/839 통과, 스위트 실행 전후 실제 .mam/jobs 레코드 881건 불변.

🚀 v4.4.2 — Issue #9 herdr 서버 환경 격리 및 Issue #14 프롬프트 전달 확인 보강 (2026-09-12)

패치 마일스톤 (PATCH Release): 에이전트 런타임(예: Claude Code 오케스트레이터) 안에서 herdr 서버가 처음 기동될 때 세션 식별 마커가 서버와 이후 모든 에이전트 pane 에 상속되던 문제(Issue #9)와, working 을 보고하지 않는 에이전트(herdr 0.9.0 의 codex)에게 정상 전달된 프롬프트를 send_keys_safe 가 실패로 오판해 잡을 agent_blocked 로 닫고 에이전트의 started/completed 를 거부하던 문제(Issue #14)를 해결했다. 신규 환경변수는 모두 기본값이 있는 추가 설정이며 공개 계약·종료 코드 변경은 없다.

🌟 주요 개선 사항

1. herdr 서버 기동 env 마커 denylist (Issue #9, lib.sh 쉼): 쉼이 herdr --session <name> server 를 부트스트랩할 때 세션 식별 마커만 제거한 환경을 넘긴다 — CLAUDECODE, CLAUDE_CODE_CHILD_SESSION, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_SESSION_ATTENDED, CLAUDE_CODE_ENTRYPOINT, CLAUDE_PID, CLAUDE_CODE_MESSAGING_TOKEN, CLAUDE_CODE_MESSAGING_SOCKET, CLAUDE_CODE_BRIDGE_SESSION_ID, ANTIGRAVITY_CONVERSATION_ID, HERMES_SESSION_ID, GROK_SESSION_ID, OPENCODE_SESSION_ID. CLAUDE_PROJECT_DIR·CLAUDE_CONFIG_DIR 등 사용자 설정은 그대로 상속된다. 상속된 CLAUDE_CODE_CHILD_SESSION 때문에 서브에이전트 claude 의 transcript 저장이 꺼져 resume 이 불가능하던 증상을 해소.
2. 조회 경로 자동 기동 금지 MAM_NO_AUTOSTART=1 (Issue #9): 이 값이 설정되면 쉼은 서버를 띄우지 않고 호출만 전달한다. status.sh·reconcile.sh 가 이를 export 하므로 read-only multi-agent-mux-status 조회가 더 이상 서버 데몬을 기동하지 않는다.
3. 쉼 ls 의 "no server running" 번역 (Issue #9): 서버가 내려가 있으면 쉼의 ls 가 no server running (herdr session <name>) 으로 보고하고, reconcile.sh 는 이를 빈 서버로 판정해 herdr_confirmed 를 유지한다(파싱 실패로 모든 서버의 drift 감지가 멈추는 회귀 방지). 번역은 agent list 가 실패하고 그 오류 봉투(stderr·stdout 어느 쪽이든)의 error.code 가 정확히 server_not_running 일 때만 적용한다. 성공한 목록에 같은 문자열이 들어 있으면(예: 에이전트 이름 server_not_running-codex) 번역하지 않으므로 살아 있는 서버가 빈 서버로 오판되어 drift A 로 전 세션이 종료 처리되지 않는다. 그 밖의 실패는 출력이 목록 파서에 닿기 전에 비-0 으로 끝나(… state unknown, reconcile 의 빈 서버 문구와 겹치지 않음) unknown(herdr_confirmed=False)으로 남는다 — stdout 으로 온 오류 문서도 더 이상 빈 목록으로 읽히지 않는다.
4. accepted 제출의 전달 확인 SKS_DELIVERY_GRACE_S (Issue #14, send_keys_safe): agent prompt --wait 결과가 timeout/agent_prompt_stalled 이면 herdr 가 입력을 이미 수락한 것으로 보고, SKS_DELIVERY_GRACE_S(기본 15초) 동안 agent_status working, 제출 전 화면에 없던 busy 토큰(esc to interrupt), 제출 전 스냅샷 대비 pane 변화 중 하나를 전달 확인 신호로 인정한다. 신호가 없으면 종전대로 rc 4 로 fail-closed 하고, 그 밖의 오류(transport_error 등)는 accepted 로 취급하지 않는다. 단일 주입 계약(재전송 없음)은 유지된다.
5. 래퍼 레지스트리 ack 유예 MAM_INJECT_ACK_GRACE_S (Issue #14, multi-agent-mux-delegate-job): send_keys_safe 가 전달을 확인하지 못해도 잡을 agent_blocked 로 닫기 전에 MAM_INJECT_ACK_GRACE_S(기본 10초) 동안 레지스트리를 관측하고, pending 이 아닌 상태(에이전트의 started 등)가 보이면 전달된 것으로 보고 진행한다(_inject_acknowledged).
6. R1 유예의 pane busy 토큰·디스크 heartbeat 인정 (Issue #14, _agent_still_working, _recent_disk_heartbeat): 구독자 idle 타임아웃 후 R1 유예가 herdr working 외에 pane 최근 8줄의 esc to interrupt 토큰, 그리고 잡 events.log 의 최근 이벤트(publish_event 가 와이어 발행 전에 로컬에 기록하는 progress heartbeat — 브로커가 느리거나 죽어 있어도 발행·재시도를 기다리지 않고 즉시 디스크에 남는다. CLI publish_event.py 와 DelegationService.publish_event 모두 record_local_event 로 먼저 기록하고, 감사 로그의 발행 결과와 상태 동기화만 발행 뒤에 남긴다)도 작업 중 근거로 받아들인다. 유예에 들어가면 IDLE_TIMEOUT 창 하나가 열리고, 근거가 관측될 때마다 그 시점부터 창이 다시 열린다. 따라서 아무 근거도 없는 무응답 에이전트는 마지막 와이어 이벤트 후 약 2×IDLE_TIMEOUT 에 닫히고(디스크 heartbeat 를 인정하기 전에는 IDLE_TIMEOUT; Issue #6 수용 기준 "≤ IDLE_TIMEOUT+5s 내 error"는 "≤ 2×IDLE_TIMEOUT + 여유"로 바뀐다), heartbeat 간격은 약 2×IDLE_TIMEOUT 까지 허용된다(heartbeat 하나가 IDLE_TIMEOUT 만큼 오래될 때까지 근거로 인정되므로). 근거는 idle 창만 늘릴 뿐 벽시계는 늘리지 않는다: 루프는 매 반복 시계로 다시 읽은 START_TIME + TIMEOUT 에서 끝나고, herdr 관측 호출도 그 시각에 끊는다(_within_deadline). broker_unavailable 디스크 재관측 루프도 같은 시계 기준이다. 이로써 idle 타임아웃보다 긴 codex 리뷰, heartbeat 간격이 한 번 idle 창을 넘긴 리뷰, 백그라운드 셸로 테스트를 돌려 herdr 에 idle 로 보이는 creator 가 턴 도중 deadline_timeout 으로 닫히고 이후 completed 가 거부되던 문제를 막는다.

✅ 품질 검증

• T1-7 트리거 변경 (tests/test_issue6_fail_closed.py): 주입 실패 유발값을 prompt_wait_result=timeout → transport_error 로 변경(Issue #14 이후 timeout 은 accepted 제출이므로 더 이상 확정 실패가 아님)하고 MAM_INJECT_ACK_GRACE_S=1 로 대기를 단축.
• 신규 테스트 21개: tests/test_issue9_server_env.py 9개(마커 제거, MAM_NO_AUTOSTART 부트스트랩 생략·호출 전달, status 조회 무기동, 정적 opt-out, ls 번역(최소·herdr 0.9 실제 오류 봉투·stdout 봉투), 성공 목록 속 server_not_running 문자열 비오판, 그 밖의 실패 unknown 유지(stderr·stdout), reconcile drift A 비발생, 다른 실패 시 reconcile herdr_confirmed=False), tests/test_issue14_delivery_ack.py 12개(busy 토큰·pane 변화 확인, 무신호 fail-closed, 선행 busy 토큰 배제, transport_error 비수용, mock herdr timeout 확인, 래퍼 레지스트리 ack, idle 타임아웃 pane busy 유예, idle 타임아웃 디스크 heartbeat 유예(publish_event 실제 경로), heartbeat 가 이어져도 벽시계 TIMEOUT 안에서 종료, 와이어 발행 전 로컬 기록, 발행 실패·재시도에도 로컬 기록 1회).
• 테스트 기대값 정정: tests/test_a4_adapter_contract.py 가 4d444ce 의 agy exit_key=/exit 변경을 반영하도록 수정(그동안 전체 스위트에서 1건 실패하던 문제 해소).
• 실측 (커밋 497633f 기록): 새로 부트스트랩한 서버에 마커가 없고 claude pane 의 transcript 저장이 복구됨, codex 잡 d04ebcb5 의 started/completed 가 agent_blocked 없이 수락됨.

🚀 v4.4.1 — Issue #6 비동기 잡 위임 안정화 및 Fail-Closed / Turn Handshake 완결 (2026-09-08)

패치 마일스톤 (PATCH Release): Issue #6 비동기 잡 위임 파이프라인에서 발생하던 터미널 상태 덮어쓰기 레이스, Herdr 프롬프트 완료 관측 부재, Subscriber 타임아웃 시 pending 방치 버그를 근본 해결. 결정론적 종료 코드 계약(0, 1, 2, 3, 5) 및 4단계 fail-closed finalizer를 완비했다.

🌟 주요 개선 사항

1. Terminal 상태 단방향 불변성: 터미널 상태(completed, error, cancelled)에 도달한 잡에 대해 이후 도착하는 이벤트의 임의 상태 변경을 원천 차단. registry.py close 서브커맨드로 비정상 중단 시 단방향 종료 처리 보장.
2. Herdr 턴 완료 핸드셰이크 (lib.sh: wait_for_agent_idle, watcher.py): wait_for_agent_idle을 통해 에이전트 프롬프트 전송 전후 유휴 상태를 확인하고, 턴이 완전히 완료되어 입력 대기 상태로 복귀할 때까지 신뢰성 있게 추적.
3. Loop 모드 attempt_id 전이 격리: 동일 iteration 내에서 워커→리뷰어 전환 시 attempt_id를 갱신하여 CAS 재전이 충돌(rc=4)을 구조적으로 방지.
4. Subscriber 비정상 종료 시 Fail-Closed 및 R1 Working 회복력 보장: 구독기 프로세스가 타임아웃되더라도 에이전트가 Herdr에서 여전히 작업 중(working)이면 벽시계 --timeout까지 유예하며 디스크 완료 상태를 재관측(R1)하고, 미종료 잡을 안전하게 error로 완결.
5. 결정론적 종료 코드 계약: multi-agent-mux-delegate-job 종료 코드를 정규화(0=성공, 1=실패/주입 오류, 2=구독기 타임아웃, 3=브로커 장애, 5=세션 선결 조건 미충족/session_busy).

🚀 v4.4.0 — Issue #5 Python 코어 마이그레이션 완결 및 main 병합 (2026-09-07)

주요 마일스톤 (MINOR Release): Issue #5 Phase 1~4 전 단계 완료 및 refactor → main 병합. 위임·루프 오케스트레이션의 구현 언어를 Bash에서 Python으로 옮기고, CAS 단일 상태 전이·섀도우 와처·자동 완료 게이트·Eager Import 불변 런타임을 도입했다. 공개 계약(스크립트 경로, CLI 인자·종료 코드, 이벤트 와이어 스키마 schema_version=1, YAML 레이아웃)은 한 건도 제거·변경되지 않았으며, 모든 기본 동작 변경은 환경변수 한 개로 즉시 되돌릴 수 있다.

⚖️ SemVer 판정 근거 (MINOR — v4.4.0, MAJOR v5.0.0 미채택)

SemVer 2.0.0 §8은 MAJOR를 하위 호환을 깨는 공개 API 변경에 한정한다. 본 릴리스는 규모는 크지만 그 조건을 충족하지 않는다.

판정 축	관측 사실	근거
공개 계약 제거/이동	Issue #5 전 구간에서 삭제·rename 파일 0건	git diff --name-status fc0bd96..HEAD
와이어 스키마	SCHEMA_VERSION = 1 불변	mqtt_common.py:135
스크립트 리터럴 경로	scripts/*.py 4종 전부 존속 (호환 shim)	Phase 1 D2
CLI 인자·종료 코드	run_loop.sh·publish_event·job_subscriber 계약 회귀 통과	G-1~G-9
기본 동작 변경의 가역성	MAM_DELEGATION_PY=0 / MAM_ENGINE_CAS=0 / MAM_LOOP_PY=0 / MAM_LOOP_FREEZE=1 로 이전 동작 완전 복원 (레거시 본체 존치, 968줄 셸 루프 포함)	test_issue5_phase3_loop.py, test_issue5_phase4_runtime.py
최고위험 신규 기능	자동 완료는 기본 비활성 옵트인	MAM_AUTO_COMPLETE 기본값 0

운영자 조치 필요 사항 없음: 마이그레이션 절차, 설정 변환, 재배포가 요구되지 않는다. 이것이 MAJOR를 채택하지 않은 결정적 이유다. 다만 MAM_VERSION 불일치는 새로 fail-closed 거부되므로, 프레임워크 트리는 부분 갱신하지 말고 통째로 배포해야 한다(§ 아래 주의).

🌟 신규 기능 및 아키텍처 확장

• Phase 1 — lib_py.delegation 패키지 추출: v4.3.0에서 선행 완료(하단 항목 참조).
• Phase 2a — CAS 단일 상태 전이 엔진 및 섀도우 와처: 잡 레코드 전이를 claim/redispatch 시점에 발급되는 불투명 dispatch_token을 선결 조건으로 하는 compare-and-set으로 결속. 관측 증거 수집(attribution.py)·판정 정책(policy.py)·증거 저장소(store.py)를 분리하고, shadow.py가 실제 전이 없이 "Would-Complete" 판정만 기록한다.
• Phase 2b — 자동 완료 게이트 (autocomplete.py): 섀도우 증거가 충분할 때에만 잡을 자동 종결하는 평가기. MAM_AUTO_COMPLETE(기본 0), MAM_AUTO_COMPLETE_BACKENDS로 백엔드 단위 옵트인. CAS가 롤백된 상태(MAM_ENGINE_CAS=0)에서는 스스로 비활성화한다.
• Phase 2b — 내구성 있는 보류 알림 (notifier.py): 알림 의도를 잡 레코드에 저장하고 CAS 락 바깥에서 발행한 뒤 notification_settled 부기 요청으로 조건부 정산. 재시도는 새 와이어 시퀀스를 받으므로 단조 시퀀스 가드로는 중복을 식별할 수 없고, 안정적인 (seq, event, timestamp) 의도 신원으로 중복을 판별한다.
• Phase 3 — run_loop.sh 얇은 래퍼 전환 및 lib_py.loop 승격: 936줄 Bash 오케스트레이션을 단일 제어 구조의 Python 모듈로 이식. run_loop.sh는 CLI 계약과 기존 정적 검사 앵커를 보존하는 래퍼가 되었고, MAM_LOOP_PY=0으로 레거시 셸 루프를 그대로 실행할 수 있다.
• Phase 3 — Strict 판정 파서 (parser.py): 마크다운 코드 펜스(```, ~~~) 내부를 제거한 뒤 마지막 비공백 라인만을 판정으로 인정한다. 리포트 본문의 예시 코드에 적힌 [VERDICT: PASS]가 실제 판정으로 오인되던 결함(baseline.md Gap)을 해소했다. 판정 부재·PASS/NOT PASS 모호 충돌·미지 태그는 모두 fail-closed NOT PASS.
• Phase 3 — 원자적 체크포인트 및 우아한 정지 (checkpoint.py): .mam/loop-checkpoint.json에 회차·활성 잡·계획·리뷰 상태·기준 커밋을 임시 파일 + replace 원자 커밋으로 기록. SIGINT/SIGTERM 수신 시 서브프로세스를 정리하고 체크포인트를 남긴 뒤 가드를 해제하고 종료(130/143).
• Phase 4 — Eager Import 불변 런타임 (eager.py): 기동 최우선 단계에서 표준·프레임워크 코어 모듈 전량을 sys.modules에 상주시켜, 루프 실행 중 디스크의 .py가 편집되어도 런타임이 영향을 받지 않는다. PYTHONDONTWRITEBYTECODE=1로 .pyc 파편에 의한 작업 트리 오염을 차단한다.
• Phase 4 — B-13 Freeze 스냅샷 제거: Bash가 실행 중 스크립트를 디스크에서 재독해하며 발생하던 크래시(B-13)의 원인이 Python 상주 프로세스 전환으로 근본 해소되었으므로, 임시 비계였던 /tmp/mam-loop-freeze.XXXXXX 트리 복사를 기본 경로에서 철거했다. 턴당 수백 개 파일 복사 오버헤드가 사라진다.

🔒 롤백 및 안전장치

• 단일 환경변수 롤백 4종: MAM_DELEGATION_PY=0(위임 셸 헬퍼 레거시 본체), MAM_ENGINE_CAS=0(무조건 병합 복원), MAM_LOOP_PY=0(레거시 셸 루프), MAM_LOOP_FREEZE=1(Freeze 스냅샷 재활성화). 재배포·revert 불필요.
• ⚠️ 부분 배포 금지 (신규 fail-closed 게이트): lib.sh의 MAM_VERSION과 lib_py/loop/eager.py의 FRAMEWORK_VERSION이 다르면 verify_framework_version()이 RuntimeError로 루프 기동을 거부한다. 두 파일 중 하나만 갱신된 혼재 트리는 실행되지 않으므로, 프레임워크는 항상 트리 단위로 배포한다.
• 4-Way 락스텝 자동 검증: test_version_consistency.py가 lib.sh ↔ eager.py ↔ VERSIONS.md(현재 버전 + 매트릭스 8행) ↔ 8개 SKILL.md frontmatter의 완전 일치를 강제한다. eager.py 커버리지는 본 릴리스에서 신규 추가되었다.

✅ 품질 검증

• 전체 테스트 스위트 750개 통과, 0 실패, 0 skip (Issue #5 착수 시점 510개 대비 +240).
• Issue #5 전용 회귀: test_issue5_phase{0,1,2a,2b,3,4}_*.py.
• 테스트 격리 결함 1건 수정 (tests/conftest.py): lib.sh가 export한 MAM_VERSION이 pytest를 기동한 셸에서 상속되어, 루프 테스트가 검사 대상 트리가 아니라 러너를 띄운 셸이 언제 lib.sh를 source했는지에 따라 통과·실패하고 있었다. 지금까지는 상속값과 상수가 우연히 같아 잠복해 있었고, 본 릴리스의 버전 상승이 이를 드러냈다(4건 실패). 세션 스코프 fixture가 상속된 값을 제거하여 스위트가 트리를 측정하도록 바로잡았다.
  • 프로덕션 경로는 영향 없음: run_loop.sh:17이 실행 최초에 lib.sh를 source하고 lib.sh:32-33이 MAM_VERSION을 무조건 재export하므로, 낡은 상속값은 파이썬 기동 전에 항상 덮어써진다(MAM_VERSION=4.3.0 bash -c 'source lib.sh; echo $MAM_VERSION' → 4.4.0).

🚀 v4.3.0 — lib_py.delegation 패키지 추출 및 장수 MQTT 연결 프로토타입 (2026-09-06)

주요 마일스톤 (MINOR Release): Issue #5 Phase 1. lib.sh의 위임 헬퍼 3종과 multi-agent-mux-delegate-job/scripts/*.py 4종을 lib_py/delegation/ 파이썬 패키지로 추출. 스크립트 경로는 와이어 계약이므로 호환 shim으로 보존하며, 프로덕션 동작·이벤트 스키마·자동완료 정책은 한 줄도 바뀌지 않는다.

🌟 신규 기능 및 아키텍처 확장

• 패키지 바인딩 shim (D2): scripts/{mqtt_common,registry,publish_event,job_subscriber}.py는 lib_py.delegation 패키지를 자기 옆 트리에 프로세스당 1회 바인딩하고 sys.path를 건드리지 않는다. import mqtt_common은 lib_py.delegation.mqtt_common과 동일한 모듈 객체가 된다.
  • sys.path.insert(0, ...) 방식은 pytest에서 최초로 임포트된 샌드박스 사본이 lib_py.agents/layout/state까지 세션 전체에 걸쳐 가로채므로 채택하지 않았다.
  • 모듈 단위 파일 적재 방식은 형제를 임포트하는 모듈이 다른 트리의 의존성을 끌어와 freeze(B-13) 보호를 부분 상실하므로 채택하지 않았다.
• DelegationService / cli.py / daemon.py: 셸 헬퍼 3종의 본체를 python -m lib_py.delegation.cli로 교체. start_watchdog은 ensure_subscriber_daemon의 별칭으로 유지.
• PersistentPublisher 프로토타입 (publisher.py) 및 벤치마크 하니스 (bench.py): 장수 연결은 Phase 2a 엔진용이며 프로덕션 경로(CLI·셸)는 계속 1회성 연결을 사용한다.
• ensure_env_loaded() (D6): .mam.env 로딩을 임포트 시점에서 프로세스 진입점으로 이동. 라이브러리 임포트가 os.environ을 변경하지 않는다.

🔒 롤백 및 안전장치

• MAM_DELEGATION_PY=0: 셸 헬퍼가 보존된 레거시 인라인 본체(_*_legacy)로 즉시 분기. 재배포·revert 불필요. 레거시 본체 제거는 Phase 4.
• 특성화 테스트 선행 (P1-00): 이전까지 위임 셸 헬퍼 3종을 직접 검증하는 테스트가 0건이었으므로, 이동 전에 골든 테스트를 먼저 추가하고 두 경로(MAM_DELEGATION_PY 0/1) 모두에서 통과시켰다.

🚀 v4.2.0 — OpenAI Codex First-Class Agent Backend Integration (2026-09-05)

주요 마일스톤 (MINOR Release): OpenAI Codex CLI(codex)를 6번째 정식 1급 에이전트 백엔드로 통합. 46개 전체 아키텍처 결합 지점(Shell 라이프사이클, Python 어댑터, 레지스트리, 상태 머신, 동기화 루프, 테스트 스위트, 문서) 전면 연동 완료.

🌟 신규 기능 및 아키텍처 확장 (New Features & Architecture)

• A-1: Codex Agent Adapter (CodexAgentAdapter) 신규 구현 (codex.py, registry.py):
  • BaseAgentAdapter 완전 구현: name='codex', own_key='codex_session_id_own', ready_tokens='Codex|Ask Codex to do anything', exit_key='Ctrl+C', delegate_agent_key='codex-cli'.
  • Class A 에이전트 라이프사이클 채택: 세션 생성 시 UUID를 사전 할당하지 않고 런타임에 동적으로 발견.
  • Rev.2 동적 SQLite DB 탐색: 고정 버전 파일 대신 state_*.sqlite 패턴을 최신 mtime 순으로 탐색하여 threads 테이블에서 (rollout_path, cwd)를 O(1)로 색인.
  • Fallback 탐색: SQLite 미존재 시 ~/.codex/sessions/*/*/*/rollout-*-<uuid>.jsonl date-nested 경로 및 재귀 패턴 지원.
  • Safe Purge: codex delete <uuid> --force CLI 호출 및 온디스크 jsonl/DB 레코드 폴백 삭제.
• A-2: Shell 라이프사이클 및 오케스트레이션 46개 지점 완전 연동:
  • lib.sh: resolve_agent_type_from_registry, _sanitize_herdr_agent_name, send_keys_safe에 codex 등록.
  • create_session.sh: --agent codex 허용, ~/.codex/auth.json / OPENAI_API_KEY 프리플라이트 검증, --dangerously-bypass-approvals-and-sandbox 플래그 스폰, codex_session_id_own: null 초기화.
  • resume_session.sh: codex 복원 지원, 0-turn 세션에 대한 FRESH_SPAWN=1 Class A 안전 폴백.
  • update_yaml_resumed.sh: codex 세션 복원 시 YAML 필드 원자적 갱신.
  • stop_session.sh: codex 지원, 종료 시 최종 session id 캡처 및 저장.
  • orc_onboard.sh: flag-tolerant regex 기반으로 codex resume [options] <uuid> 명령행에서 UUID 정확 추출.
  • reconcile.sh: drift C (codex) 전용 감지 블록 추가 (state DB 우선 + glob 폴백), discovery sweep 연동.
  • status.sh: text/JSON 포맷터 양측에 codex 온디스크 복원 가능 여부 검사 로직 연동.
• A-3: 문서 및 표준 헌장 동기화:
  • README.md, README.ko.md, BOOTSTRAP.md, BOOTSTRAP.ko.md, deploy/INSTALL.md, .agents/MULTI_AGENT_RULES.md, .mam.env.example, docs/NEW_AGENT_INTEGRATION_GUIDE.md 전면 업데이트.

---

🛠️ v4.1.3 — Herdr Daemon Isolation & Class A 0-Turn Resume Reliability Fixes (2026-08-31)

주요 마일스톤 (PATCH Release): Issue #3 결함 해소 — Herdr 백그라운드 데몬의 start_new_session=True 기반 프로세스 그룹(setsid) 완전 격리, Class A(agy, hermes, opencode) 에이전트 0-turn 중지 세션의 FRESH_SPAWN fallback 및 discovery epoch 원자적 재설정, Class B(claude, grok) 계약 불변 보존, 455개 전체 테스트 스위트 100% PASS 달성.

🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)

• C-1: Herdr 데몬 프로세스 그룹(PGID/SID) 완전 분리 (lib.sh):
  • .mam/shim/herdr 템플릿의 nohup ... & disown 스폰 방식을 파이썬 subprocess.Popen(..., start_new_session=True) 기반 전용 스포너로 대체하여 자식 프로세스에서 os.setsid() 호출 보장.
  • 부모 셸이나 테스트 러너의 시그널 브로드캐스트(SIGTERM/SIGINT)로 인해 백그라운드 Herdr 데몬이 예기치 않게 종료되는 결함을 원천 차단 (test_h26).
• C-2: Class A 에이전트 0-turn resume 자율 Fallback 및 Discovery Watermark 갱신 (resume_session.sh, update_yaml_resumed.sh):
  • 대화 턴이 발생하기 전에 중지된 Class A(agy, hermes, opencode) 세션 resume 시, UUID 미존재로 인한 비정상 hard-fail(RC=1) 대신 FRESH_SPAWN=1로 자동 전환하여 spawn-spec 기반의 정상 재스폰 수행 (test_t14).
  • fresh-spawn resume 시 update_yaml_resumed.sh에서 herdr_session_epoch를 resume 시점의 타임스탬프로 즉시 갱신하고 session_id_source: pending-discovery로 재설정하여, 세션 생성과 복원 사이에 생성된 무관한 이전 대화 파일이 reconcile.sh의 discovery sweep에 의해 오인 캡처되는 것을 방지 (test_t16).
  • Class B(claude, grok) 에이전트의 verify_session.py:99-101 assigned escape hatch 및 test_t8 계약은 수정 없이 완벽히 보존 (test_t15).

---

🛠️ v4.1.2 — Pane Resolution & Reuse Reliability Fixes (2026-08-30)

주요 마일스톤 (PATCH Release): bug-report/mam_upstream_bug_fix_report.md에 보고된 4건을 실 코드 대비 독립 검증 — 2건은 실재하는 결함으로 확인되어 수정(SemVer 2.0.0 §6 PATCH), 1건(ready_tokens)은 v4.1.1에서 이미 해결됨을 확인, 1건(resume_spec materialized 게이트)은 5개 어댑터 공통의 의도된 안전장치로 판단되어 제안된 수정을 채택하지 않음(근거는 아래 참조).

🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)

• C-1: _resolve_herdr_pane_id Generic agent_kind 오인 매칭 방지 (lib.sh):
  • 세션명 매칭 실패 시 수행되던 agent_kind 광역 폴백을 호출 대상 자체가 kind 리터럴(예: "agy")인 경우로만 한정하고, 상위 루프의 exact match 대상에서 'agent'를 제외하여 동종 페인 다수 존재 시 R-1 fail-closed 계약이 온전히 적용되도록 보장. 이전에는 대상 세션의 yaml 항목에서 조회한 kind로 "동종 페인 아무거나" 검색을 수행해, 워크스페이스 내 무관한 동종 에이전트(예: 별도 오케스트레이터 agy 세션)가 단 1개라도 살아있으면 그 페인을 대상으로 오인 반환하는 결함이 있었음.
• C-2: new-session 유휴 페인(Idle Pane) 우선 재사용 및 환경변수 주입 보전 (lib.sh):
  • 기존 워크스페이스가 감지되면 곧바로 pane split을 호출하던 기존 동작을 변경, 워크스페이스 내 에이전트 미할당(유휴) 페인이 존재하면 이를 target_pane으로 즉시 재사용하고 split을 생략. 재사용 시 호출자가 전달한 $env_flags 및 HERDR_WORKSPACE_ID가 유실되지 않도록 env 접두어로 $final_cmd에 주입하여 환경변수 전달 일관성 보장. 오버플로우 시 신규 워크스페이스 생성 정책(W2b)은 유휴 페인이 없는 경우에만 그대로 적용됨.
• 검토 후 미채택 — opencode.py::resume_spec materialized 게이트:
  • 보고서는 if materialized and session_uuid: 조건 제거를 제안했으나, 이는 claude/grok/agy/hermes/opencode 5개 어댑터 전원에 동일하게 존재하는 의도된 계약이며, materialized는 verify_artifact()(opencode의 경우 실제 SQLite 세션 DB 조회)로 산출됨 — 존재하지 않는 세션 ID로 --session을 넘겨 CLI가 실패/행(hang)하는 것을 막기 위한 안전장치. 제안대로 수정 시 5-어댑터 일관성이 깨지고 안전장치가 무력화되므로 채택하지 않음. resume_session.sh는 WORKSPACE를 필수 인자로 검증하므로 ctx가 비어 materialized가 거짓이 되는 경로도 확인되지 않음.
• 재확인(조치 불필요) — opencode.py::ready_tokens:
  • 보고서가 지적한 ASCII 배너 미인식 문제는 v4.1.1(B-1, job c38ddfcf)에서 이미 해결되어 현재 ready_tokens가 보고서의 "수정 후" 값과 완전히 일치함을 확인. 보고서 작성 시점이 v4.1.1 이전 체크아웃이었던 것으로 추정.

---

🛠️ v4.1.1 — Agent Creation & Runtime Reliability Fixes (2026-08-30)

주요 마일스톤 (PATCH Release): 에이전트 생성 및 런타임 신뢰성 향상을 위한 4대 보편 버그 수정(SemVer 2.0.0 §6 PATCH), Herdr 격리 환경 PYTHONPATH 자동 주입, OpenCode TUI 레디 토큰 보강, 세션 페인 식별자 Fast-Path 및 시작 타임아웃 복원력 강화.

🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)

• B-1: OpenCode TUI 준비 감지 토큰 보강 (lib_py/agents/adapters/opencode.py):
  • ready_tokens를 'OpenCode|Chat|Ask anything|tab agents|ctrl\+p|Build auto|commands'로 확장하여 ASCII 배너 및 Build auto 초기 화면에서 30초 대기 없이 즉각 준비 완료 판정.
• B-2: Herdr Shim 템플릿 내 독립 PYTHONPATH 주입 (lib.sh):
  • .mam/shim/herdr 스크립트 상단에서 자신의 경로를 기준으로 _SKILL_DIR을 산출하고 PYTHONPATH에 주입하여 부모 셸 환경변수 미상속 서브셸에서도 lib_py 모듈 정상 로드 보장.
• B-3: herdr agent start 타임아웃 복원력 및 send-text 폴백 (lib.sh):
  • 시작 타임아웃 발생 시 무조건 실패 처리하지 않고, 실제 에이전트 프로세스 생존을 확인하거나 pane send-text + Enter 폴백으로 명령을 직접 재주입하여 세션 초기화 성공률 제고.
• B-4: _resolve_herdr_pane_id 페인 ID Fast-Path 및 워크스페이스 레이블 매칭 (lib.sh):
  • 이미 해석된 페인 ID(wN:pM) 입력 시 즉각 반환하는 Fast-Path 추가.
  • herdr workspace list를 활용하여 워크스페이스 레이블(예: mam-agents)을 실제 workspace_id로 자동 변환 매칭.

---

🚀 v4.1.0 — OpenCode AI Agent Integration (2026-08-29)

주요 마일스톤 (MINOR Release): OpenCode AI 에이전트(anomalyco/opencode) 백엔드 완전 통합(SemVer 2.0.0 §7 MINOR), 5대 핵심 에이전트(claude, agy, hermes, grok, opencode) 표준화, 29개 CLI 스크립트/스킬 연동 및 447개 전체 테스트 100% PASS 달성.

✨ 주요 변경 사항 (New Features & Enhancements)

• F-1: OpenCode 에이전트 어댑터(OpenCodeAgentAdapter) 구현:
  • lib_py/agents/adapters/opencode.py 신규 구현 및 lib_py/agents/registry.py 등록.
  • SQLite 스토리지(opencode.db) 내 directory 및 time_created(밀리초) 실 스키마 기반의 방어적 세션 검증(verify_artifact) 및 멀티 후보자 발견(discover) 지원.
  • _resolve_db()를 통한 opencode db path CLI 동적 해석 및 샌드박스 환경(HOME/XDG_DATA_HOME) 격리 지원.
• F-2: CLI 라이프사이클 및 스크립트 전면 연동 (29개 터치포인트):
  • create_session.sh, resume_session.sh, stop_session.sh, status.sh, reconcile.sh, run_loop.sh, orc_onboard.sh 내 --agent opencode 완전 지원.
  • 세션 생성 및 재개 시 OPENCODE_PERMISSION='{"*":"allow"}' 자동 내보내기 및 사용자 사전 설정 보존(Empty-Guard).
  • 백그라운드 조정자(reconcile.sh) drift-C 블록에서 어댑터 공유 헬퍼를 통한 세션 ID 사후 자율 감지 및 YAML 등록.
• F-3: 포괄적 테스트 스위트 확장:
  • tests/test_a4_adapter_contract.py: 어댑터 계약, 실 스키마 밀리초 비교, CLI DB 경로 동적 해석 검증.
  • tests/test_tier1_unit.py, tests/test_tier2_component.py, tests/test_c1_tui_readiness.py: TUI 및 라이프사이클 통합 검증 (총 447개 테스트 100% 통과).

---

🚀 v4.0.0 — Complete Cline Agent Deprecation & Hermes Modernization (2026-08-28)

주요 마일스톤 (MAJOR Release): cline 에이전트 백엔드의 완전한 제거 및 폐지(Breaking Change per SemVer 2.0.0 §8), Hermes 에이전트 풀 모더니제이션 및 Ollama 로컬 연동 정식 지원, 4대 핵심 에이전트(claude, agy, hermes, grok) 표준화 및 439개 전체 테스트 100% PASS 달성.

⚠️ 동작 변경 및 마이그레이션 안내 (Breaking Changes)

• B-1: --agent cline 지원 완전 제거 및 파서 거부:
  • adapters/cline.py 삭제 및 registry.py 등록 해제에 따라 모든 스킬 엔트리포인트(create_session.sh, resume_session.sh, stop_session.sh, reconcile.sh, orc_onboard.sh, multi-agent-mux-delegate-job 등)에서 --agent cline 입력 시 exit 2로 즉시 거부됩니다.
  • 지원되는 에이전트 패밀리는 claude, agy, hermes, grok 4종으로 엄격히 제한됩니다.
• B-2: 영향도 확인 (Detection):
  • 저장된 스크립트나 커스텀 세션에서 Cline 관련 설정이 남아있는지 확인:

    grep -rn "agent: cline\|cline_conversation_id_own\|--agent cline" .mam/ *.sh 2>/dev/null
    

• B-3: 업그레이드 전 세션 정리 (Pre-upgrade Cleanup — 권장):
  • v3.1.0 상태에서 deploy/update.sh 실행 전, 기존의 활성/보관 중인 Cline 세션을 원자적으로 정리:

    multi-agent-mux-stop --session <session-name> --agent cline --purge-conversation --yes
    

• B-4: 업그레이드 후 고아 세션 레코드 정리 (Post-upgrade YAML Pruning):
  • deploy/update.sh는 .mam/agent-sessions.yaml을 덮어쓰지 않고 보존하므로, 사전에 정리되지 않은 v3.x cline 세션 행은 아래 원자적 갱신 명령을 통해 안전하게 정리할 수 있습니다:

    source .agents/skills/lib.sh
    atomic_dump_yaml .mam/agent-sessions.yaml <<'MUT'
    d['herdr_sessions'] = [
        s for s in d.get('herdr_sessions', [])
        if s.get('agent') != 'cline' and not str(s.get('name', '')).endswith('-cline')
    ]
    MUT
    

• B-5: Hermes 에이전트 모더니제이션:
  • 헤드리스 플래그(--yolo --accept-hooks), TUI 입력 영역 구분자(─{10,} 및 ❯), 준비 토큰 강화, reconcile.sh 타임스탬프 기반 다중 후보자 동등성(discover()) 지원이 정식 통합되었습니다.

---

🚀 v3.1.0 — 2-Tier TUI Readiness Model, Adapter Modal Contract & Fail-Closed Pane Resolution (2026-08-28)

주요 마일스톤: 다이얼로그 기아(starvation) 구조적 해소를 위한 2계층 TUI 준비 판정 모델(S ∨ (W ∧ C)), 모달/힌트 2계층 토큰 분리, 어댑터별 modal_tokens 계약(T-2d) 정립, 동종 페인 다중 매치 fail-closed 방어, 준비 실패 세션 진단 보존(create_session.sh), lib.sh 런타임 버전 상수(MAM_VERSION="3.1.0") 신설 및 436개 전체 테스트 100% PASS 달성.

⚠️ 동작 변경 및 마이그레이션 안내

• B-1: TUI 미준비 세션 보존 (create_session.sh):
  • TUI 준비 감지 타임아웃 발생 시, PID가 생존해 있다면 세션을 강제 종료(kill-session)하지 않고 status: running, last_visible_status: tui-ready-timeout으로 등록한 뒤 exit 0(성공)으로 반환합니다.
  • 구 v3.0.1의 무조건 롤백 및 종료 동작을 원할 경우 MAM_KILL_ON_READY_TIMEOUT=1을 설정하십시오.
• B-2: 프로세스 사망 시 종료 코드 변경:
  • create_session.sh 실행 중 PID가 사망한 경우 명시적 구분 코드 42(MAM_EXIT_READY_TIMEOUT)로 종료합니다.
• B-3: 동종 페인 다중 매치 시 Fail-Closed 거부 (_resolve_herdr_pane_id):
  • 동일한 에이전트 종류의 페인이 여러 개 발견되고 정확한 세션명 일치가 실패할 경우, 임의의 첫 번째 페인을 선택하지 않고 즉시 exit 1로 실패하여 교차 세션 오염을 원천 차단합니다.
• B-4 & B-5: 환경변수 전파 (WORKSPACE_ROOT, MAM_VERSION):
  • WORKSPACE_ROOT 및 MAM_VERSION이 자식 프로세스로 자동 export됩니다. MAM_VERSION은 런타임 위조 방지를 위해 환경변수 오버라이드가 차단됩니다.

🔧 기존 워크스페이스 사용자 안내

기존 배포된 워크스페이스 사용자는 .mam.env에 아래 3종의 신규 환경변수를 추가하여 동작을 튜닝할 수 있습니다:

변수명	기본값	설명
MAM_KILL_ON_READY_TIMEOUT	0	1로 설정 시 TUI 준비 타임아웃 발생 시 세션을 보존하지 않고 강제 종료(v3.0.1 동작)
MAM_DIALOG_TAIL_LINES	8	블로킹 모달 시그니처를 검사할 페인 하단 비공백 라인 수
MAM_READY_EMPTY_GIVEUP	5	wait_for_tui_ready가 페인을 관측 불가(Headless)로 판정하기까지의 연속 빈 캡처 횟수

1. 2계층 TUI 준비 판정 모델 (S ∨ (W ∧ C))

• 단독 충분 강한 신호 (S): strong_ready_tokens 또는 8자 이상의 유의미한 input_placeholder(Ask anything...) 일치 시 준비 완료 선언.
• 보강 결합 약한 신호 (W ∧ C): weak_ready_tokens(history, Chat 등)는 input_prompt(❯, >) 또는 input_rule_pattern(─{10,})과 동시 일치할 때만 준비 완료로 판정하여 오탐 차단.
• 하강 호환성 (Fallback): input_* 속성이 미정의된 에이전트(Hermes 등)는 강한 토큰 단독 검사로 안전하게 하강.

2. 모달/힌트 토큰 분리 및 어댑터 modal_tokens 계약 (T-2a / T-2d)

• 토큰 집합 분리: _MAM_MODAL_TOKENS(고신뢰 블로킹 모달)와 _MAM_HINT_TOKENS(자연어 TUI 안내 팁)를 분리. _pane_dialog_open이 힌트 텍스트로 인해 영구 차단(Starvation)되는 결함 해소. _MAM_DIALOG_TOKENS는 하위호환용 합집합으로 존치.
• BaseAgentAdapter.modal_tokens: 에이전트별 특화 모달(Claude의 Try the new fullscreen renderer?, Cline의 Select API Provider 등)을 팩트 브리지(MAM_MODAL_TOKENS)로 통합.

3. Fail-Closed 페인 해석 및 워크스페이스 스코프 강화 (R-1 / R-2)

• _resolve_herdr_pane_id에서 다중 매치 시 sys.exit(1) 처리 및 export WORKSPACE_ROOT 보강으로 격리 안정성 확보.

4. 준비 실패 세션 진단 보존 및 MAM_VERSION 스탬프

• create_session.sh 실패/타임아웃 시 .mam/diagnostics/<session>-<timestamp>.txt로 페인 덤프 및 MAM Version 스탬프 자동 기록.

5. 런타임 버전 상수 MAM_VERSION 신설 및 3자 락스텝 검증

• lib.sh 내 MAM_VERSION="3.1.0" 선언 및 test_version_consistency.py를 통한 lib.sh ↔ VERSIONS.md ↔ 8개 SKILL.md 3자 일치 자동 검증.

6. 신규 환경변수 3종 문서화

• .mam.env.example에 MAM_KILL_ON_READY_TIMEOUT, MAM_DIALOG_TAIL_LINES, MAM_READY_EMPTY_GIVEUP 3종 등록.

7. 테스트 스위트 확장: 412 → 436 (+24, 100% PASS)

• test_c1_tui_readiness.py (21 tests), test_adapter_modal_tokens_contract, test_version_consistency.py 신설 등 총 436개 테스트 무결점 통과.

8. 교차 피어 리뷰 이력

• F-1~F-8 및 R-1, R-2 총 10건의 피어 리뷰 이슈 도출 및 해소:
  • F-1 (Yes, try it 팁 오탐 제거), F-2 (업셀 모달 선행 검사), F-3 (변수 스코프 격리), F-4 (리뷰어 실측 검증 후 자진 철회), F-5/F-6/F-7 (어댑터 팩트 연동 및 세션 패턴 보강), F-8 (비-클로드 어댑터 modal_tokens 계약 정립), R-1 (Fail-closed 페인 리졸버), R-2 (WORKSPACE_ROOT export 전파).
  • 계획 단계 챌린지(b9c29c3b)를 통한 C-1 (MAM_VERSION 3자 락스텝) 및 C-2 (마이그레이션 안내) 수용.

🚀 v3.0.1 — Herdr Shim Routing Contract Refactor, Multi-Workspace Isolation & 412-Test Milestone (2026-08-27)

주요 마일스톤: Herdr 심 라우팅 5대 결함(ISSUE-15) 및 F-1F-4 보완 완결, HERDR_WORKSPACE_ID 환경 변수 스코핑 및 파일 기반 격리 영속화 엔진 탑재, pane send-text 기반 단일 안전 삽입 계약 정립, 부분 문자열 매칭(in tn) 완전 제거, 412개 전체 테스트 100% PASS 달성.

1. Herdr 심 라우팅 및 다중 워크스페이스 격리 강화 (.agents/skills/lib.sh)

• HERDR_WORKSPACE_ID 명시적 스코프 & 영속화 (ISSUE-3, F-2b):
  • _herdr_ws_id_file(), _herdr_persist_ws_id(), _herdr_ws_scope() 헬퍼 도입.
  • new-session 시 생성된 워크스페이스 ID를 $WORKSPACE_ROOT/.mam/herdr_workspace_id에 영속화.
  • _herdr_agent_get_scoped는 호출자의 환경변수(HERDR_WORKSPACE_ID)만을 우선 평가하여 단축 경로에서의 교차 워크스페이스 라우팅 오염 차단.
• 엄격 일치(Exact-Match) 단일 페인 리졸버 정립 (ISSUE-2, ISSUE-5, F-3):
  • 기존의 에이전트 CLI 명칭 부분 문자열 매칭(in tn, agent in tn) 완전 제거.
  • 단일 중앙 헬퍼 _resolve_herdr_pane_id로 has-session, kill-session, capture-pane, send-keys, paste-buffer의 페인 해석 통합.
  • 영숫자 워크스페이스 식별자 패턴(^w[A-Za-z0-9]+:p[A-Za-z0-9]+$) 지원 (H-20).

2. 원자적 텍스트 삽입 및 안전 전송 계약 교정 (ISSUE-1, F-4)

• paste-buffer의 pane send-text 전용화:
  • Herdr CLI에 미존재하던 agent send 제거 및 pane send-text로 교체.
  • 삽입과 제출(Enter) 책임을 분리하여 의도치 않은 자동 제출 및 이중 제출(Double Submit) 방지.
  • 페인 미해석 또는 삽입 실패 시 send_keys_safe로 에러 코드(rc 3) 명시적 전파.
• capture-pane 폴백 체인 복원 (F-4):
  • pane read 실패 시 agent read로의 폴백 체인을 안정적으로 복원하여 TUI 캡처 신뢰성 보장.

3. TUI 준비 상태 감지 및 다이얼로그 토큰 정밀화 (N-1, F-1)

• _MAM_DIALOG_TOKENS 일반 팁 토큰 분리:
  • 일반 대화형/TUI 팁에 등장하는 Yes, try it을 블로킹 다이얼로그 토큰 목록에서 제외하여 세션 시작 시의 오탐 방지.
  • 풀스크린 업셀 모달에 대해서는 전용 Escape 거절 브랜치로 격리 처리.

4. 테스트 스위트 및 Mock Herdr 계약 정기 동기화 (tests/)

• Mock Herdr (tests/conftest.py): 실제 Herdr 0.8.2 CLI 계약과 완벽 동기화 (pane send-text, pane read, pane rename 반영, 미지원 agent send 실패 처리).
• 신규 계약 & 회귀 테스트 19건 추가:
  • test_herdr_shim_contract.py: H-15 ~ H-23 (단일 리졸버 불변식, 워크스페이스 격리, 단축경로 스코핑).
  • test_b19_headless_reconcile_fixes.py: D-4 ~ D-7 (set -e 안전성, send_keys_safe 실패 전파, 다이얼로그 토큰 제외 회귀 방지).
• 전체 테스트 결과: 412 passed in 681.20s (100% PASS).

---

🚀 v3.0.0 — 5th Agent (Grok) Ecosystem Expansion, Mux Loop CLI Redesign & Deterministic 2xK Layout Engine 2.0 (2026-08-26)

주요 마일스톤: 5번째 공식 에이전트 grok(Grok Build) 전면 통합, /multi-agent-mux-loop의 --target-agent 폐지 및 --creator/--planner 역할 분리(Breaking Change), 2×2 대칭 그리드를 보장하는 결정론적 레이아웃 엔진 2.0 탑재, 393개 전체 테스트 100% PASS 달성.

⚠️ Breaking Changes & Migration Guide

• multi-agent-mux-loop CLI 플래그 개편:
  • 기존의 단일 대상 지정 플래그 --target-agent <session>가 공식 제거(Drop) 되었습니다.
  • 기존 명령은 이제 ERROR: --target-agent was removed. Use --creator <session> instead.와 함께 종료(exit 1)됩니다.
  • 마이그레이션 방법:
    • 기존: bash run_loop.sh --target-agent <dev-session> --task "..."
    • 변경: bash run_loop.sh --creator <dev-session> --task "..."
    • 플래너 지정 시: bash run_loop.sh --plan --planner <plan-session> --creator <dev-session> --task "..."

1. 5번째 공식 AI 에이전트 Grok Build (grok) 전면 통합

• 어댑터 및 수명 주기 관리 (lib_py/agents/, lib.sh):
  • GrokAgentAdapter 구현 및 레지스트리 공식 등록 (claude, agy, hermes, cline, grok).
  • create_session.sh, resume_session.sh, stop_session.sh, resolve_session_id.sh의 에이전트 화이트리스트 및 디스패치 지원 완비.
  • 온디스크 세션 UUID 해석 및 TUI 렌더링 준비 감지 토큰 반영.

2. 결정론적 2×K 그리드 레이아웃 엔진 2.0 (lib_py/layout.py, lib.sh)

• N=1\to 2 right 분할 우선 정책 (R-1 결함 해소):
  • 1개 페인에서 2번째 에이전트 추가 시 down 대신 right로 분할(single_pane_split_right)하여 좌/우 2개의 전고(Full-height) 열 확보.
  • 이후 $N=3$(좌측 down), $N=4$(우측 down)로 이어져 완벽한 2×2 균등 대칭 격자 기하학(widths=[138,139], heights=[39]) 완성.
• GUI ↔ 헤드리스 단일 결정표 통합 (_decide_from_cols):
  • 기존의 불완전한 n % 2 홀짝 패리티 로직을 폐기하고, 열 점유 상태(cols=(a, b)) 기반의 통합 3단계 결정 매트릭스로 일원화.
• 안전 가드 및 4중 용량 배선:
  • _full_height_pane 가드로 반쪽 열 분할 원천 차단.
  • layout.py 기본값(default=2), lib.sh:435 CLI 인자(--max-cols, --max-rows), .mam.env.example 동기화 완료.

3. 사전 검증 및 인프라 동기화

• create_session.sh의 --workspace 필수 인자 사전 검증(preflight) 강화.
• 사설 NATS 브로커(nats-docker) 2.14-alpine 최신 태그 동기화.

---

🚀 v2.2.1 — Single-Workspace 2xK Multi-Pane Tiling Optimization & Premature Overflow Fix (2026-08-24)

주요 마일스톤: MAM_MIN_PANE_COLS 기본값 60→40 완화, 표준 80~100컬럼 터미널 뷰포트에서 조기 워크스페이스 오버플로(가상 데스크톱 분리) 방지 및 단일 워크스페이스 2x2 통합 타일링 완성, 신규 80/79 경계 및 90/100 col 타일링 테스트 6종 추가, 다중 에이전트 피어 리뷰 100% PASS 달성.

1. 2xK 레이아웃 엔진 최소 폭 완화 (lib_py/layout.py, lib.sh)

• compute_2xk_layout 기본 min_cols 및 CLI --min-cols, lib.sh:432의 ${MAM_MIN_PANE_COLS:-40}, .mam.env.example 문서를 40으로 4중 일치화.
• 90~100컬럼 너비 터미널에서 3번째, 4번째 에이전트 생성 시 불필요하게 가상 데스크톱(Workspace)이 분리되던 현상 완전 해소.

2. 경계값 및 타일링 자동화 테스트 확충 (tests/test_layout.py, tests/test_tier1_unit.py)

• 80 컬럼(분할 성공) vs 79 컬럼(오버플로) 하한 경계값 검증.
• 90 및 100 컬럼 단일 워크스페이스 1→2→3→4 단계 2x2 타일링 및 5번째 에이전트 오버플로 전 과정 수명 주기 검증.

---

🚀 v2.2.0 — Herdr Workspace Label Standardization, Runtime Sync & Legacy Fallback Decoupling (2026-08-24)

주요 마일스톤: --herdr-workspace 옵션 전 스킬 도입 및 YAML 독립 직렬화, Herdr 런타임 워크스페이스 레이블 실시간 동기화, 레거시 소켓 폴백 체인 분리(Breaking Change 방어), 최신 Claude Code TUI 감지 토큰 반영, 27개 신규 테스트 추가 및 만장일치 PASS 달성.

1. --herdr-workspace 옵션 도입 및 Herdr 런타임 레이블 동기화

• CLI 옵션 및 YAML 직렬화 표준화:
  • create_session.sh, resume_session.sh, update_yaml_resumed.sh, stop_session.sh에 --herdr-workspace <name> 파서 및 환경변수(HERDR_WORKSPACE) 지원 추가.
  • agent-sessions.yaml에 herdr_session(소켓명)과 herdr_workspace(워크스페이스 라벨)를 각각 독립 필드로 영구 직렬화.
• Herdr 런타임 워크스페이스 레이블 실시간 연동 (lib.sh, resume_session.sh):
  • herdr workspace create 호출 시 --label "$MAM_WS_LABEL" 전달 및 기존 워크스페이스 사용 시 herdr workspace rename 자동 호출.
  • resume_session.sh 실행 시 저장된 herdr_workspace를 읽어 Herdr 런타임 레이블 복원 보장.

2. 레거시 소켓 폴백 체인 분리 및 Breaking Change 원천 차단

• 소켓 vs 워크스페이스 함수 완전 분리 (lib.sh):
  • resolve_herdr_session(): 데몬/소켓 세션명만 반환 (row herdr_session -> row herdr_server -> env -> slug).
  • resolve_herdr_workspace(): 워크스페이스 라벨만 반환 (row herdr_workspace -> pane.cwd slug -> caller ws arg).
  • 기존 코드베이스 6개 지점(lib.sh:1027, reconcile.sh:135, 399, 495, status.sh:145, 270)에서 소켓 검색 시 herdr_workspace를 오인 참조하던 구문을 완전히 제거.
• 외부 세션 입양(Drift-B) 보강 (reconcile.sh):
  • 외부 세션 입양 시 herdr_workspace와 herdr_server를 자동 채번 및 직렬화.

3. 최신 에이전트 TUI 준비 감지 보강 (claude.py, lib.sh)

• 최신 Claude Code(v2.1.241)의 시작 배너(Claude Code, Opus 5 with high effort 등)를 ready_tokens에 추가하여 세션 생성 타임아웃 방지.

---

🚀 v2.1.0 — 2xK Grid Layout Engine, Explicit Agent Standardization & Herdr Session Hardening (2026-08-24)

주요 마일스톤: 2xK 우측 성장 그리드 레이아웃 엔진(lib_py.layout) 구축(B-20), 전 스크립트 --agent / --herdr-session 표준화 및 전파 가드, 전체 346개 테스트 스위트 100% PASS 달성.

1. 2xK 우측 성장 그리드 레이아웃 엔진 구축 (B-20 / I-2, I-3, C-1, J-1)

• 순수 파이썬 레이아웃 엔진 신설 (lib_py/layout.py):
  • tput 기반 터미널 크기 동적 감지 및 2xK(2행 고정, 우측 열 추가) 그리드 기하학 계산 엔진 구현.
  • 패널 번호 순서(0:좌상, 1:좌하, 2:중상, 3:중하...)에 따른 우측 확장 타일링 분할 명령(split-pane -h/-v, select-pane) 계산.
  • 헤드리스/CI 최소 차원(최소 너비 60, 최소 높이 20) 가드 및 default=60 falsy-zero trap 해결 (_env_int).
• 33개 신규 레이아웃 단위/회귀 테스트 구축 (tests/test_layout.py):
  • 1~8개 패널 수식 검증, 비정상 인자/환경변수 방어, 무한 루프 방지 가드 검증.

2. 에이전트 인자 표준화 및 레지스트리 자동 추론

• stop_session.sh, create_session.sh, resume_session.sh, update_yaml_resumed.sh, resolve_session_id.sh 전반에 걸쳐 --agent <claude|agy|hermes|cline> 명시적 표준화.
• 미지정 시 YAML 레지스트리(agent-sessions.yaml) 기반 에이전트 타입 자동 추론(resolve_agent_type_from_registry) 연동.

3. --herdr-session 격리 세션 옵션 표준화 및 전파 가드

• create_session.sh, resume_session.sh, stop_session.sh, update_yaml_resumed.sh 전반에 --herdr-session <NAME> 표준 옵션화 (레거시 --herdr-server 완전 호환).
• create_session.sh에서 명시적 세션명이 워크스페이스 슬러그에 의해 덮어씌워지지 않도록 가드 보강.
• resume_session.sh의 post-spawn 재개 시 신규 Herdr 세션명이 YAML 레지스트리에 정확히 전파되도록 갱신 로직 및 신규 Tier 2 테스트 5건 추가.

4. 테스트 스위트 확장 및 피어 리뷰 전원 만장일치 PASS

• 전체 테스트 스위트 수 276건 → 346건 (100% PASS) 확장.
• Multi-Agent Loop를 통한 Reviewer(claude, cline) 전원 [VERDICT: PASS] 검증 완료.

---

🚀 v2.0.0 — Unified Agent Adapter Architecture & Herdr Standardization (2026-08-17)

주요 마일스톤: 에이전트 지식 계층 단일 소스화(A-4), 레거시 격리 완전 폐기(Option B), 셸 브리지 하드닝 및 스킬 메타데이터 규격화 완료.

1. 에이전트 지식 계층 마이그레이션 (A-4 Phase 2 / P3-1)

• BaseAgentAdapter 추상 클래스 및 4대 어댑터 구축:
  • .agents/skills/lib_py/agents/base.py: DiscoveryContext 및 추상 인터페이스 정의 (ready_tokens, exit_key, delegate_agent_key, identity_cache_fields, artifact_path, verify_artifact, purge_artifacts, spawn_spec, resume_spec, auth_ok, discover).
  • .agents/skills/lib_py/agents/adapters/: ClaudeAgentAdapter, AgyAgentAdapter, HermesAgentAdapter, ClineAgentAdapter 4개 구체 클래스 구현.
• facts 브리지 셸 인터페이스 하드닝:
  • lib_py.agents CLI 모듈을 통해 8개 MAM_* 변수를 shlex.quote 안전 인용 처리하여 방출.
  • wait_for_tui_ready 빈 토큰 시 전량 매칭 오탐 방지 및 미지 에이전트 fail-closed 가드 내장.
• 셸 스크립트 전반 어댑터 이관:
  • create_session.sh, resume_session.sh, stop_session.sh, reconcile.sh에 산재되어 있던 40여 개 하드코딩 분기를 어댑터 호출로 일원화.

2. 레거시 isolation.root 및 C-3b 소비자 완전 폐기 (Option B)

• Universal Global Config 전환 이후 남아있던 4개 레거시 격리 소비자 코드(lib.sh::mam_session_iso_root, workspace_uuid.py::iso_root_of, verify_session.py, stop_session.sh) 및 atomic_yaml.py의 레거시 유효성 검사 절 100% 삭제.
• 저장소 내 격리 잔재 참조 0건 달성.

3. 셸 브리지 보안 및 예외 처리 강화 (R1, R2, N1 교정)

• R1 (위임 에이전트 키 폴백 보강): 브리지 미작동 시 delegate_agent가 antigravity-cli로 일괄 퇴화하지 않고 claude-code, hermes-agent, cline-agent로 명시적 case 폴백하도록 개선.
• R2 (argv 서브커맨드 전환): python -c 셸 변수 문자열 보간을 spawn-spec, resume-spec, exit-key 서브커맨드로 전면 전환하여 공백/작은따옴표 경로 에러 및 코드 주입 위협 원천 차단.
• N1 (클린 환경 격리 가드): test_a4_adapter_contract.py 내 CLI 테스트가 앰비언트 PYTHONPATH 없이도 독립 통과하도록 환경 격리 보강.

4. 스킬 메타데이터 규격화 및 피어 리뷰 100% PASS

• 8개 SKILL.md frontmatter version: 2.0.0 통일 및 배포 무결성 검증.
• Reviewer cline (Job e7b9812b) 및 Planner/Senior Reviewer claude (Job 31730364) 전원 [VERDICT: PASS] 획득.

5. 레거시 주석 및 사용법 정합성 최신화 (C-6)

• stop_session.sh 상단 주석 및 usage() 내 폐기된 플래그(--mode soft|hard, --capture-id, --graceful) 안내 문구를 완전 제거하고 현행 4대 에이전트(claude, agy, hermes, cline) 및 플래그 체계로 동기화.
• 회귀 방지 컴포넌트 테스트(test_comp_stop_usage_matches_parser) 신설.
• 회귀 및 계약 테스트: 263/263 PASS (100%) 달성.

6. macOS NFS 감지 df -P 폴백 검증 및 종결 (B-5)

• _check_is_nfs(lib.sh)의 macOS/BSD 환경 내 GNU 전용 df --output 구문 오류 시 POSIX df -P 폴백 동작을 실측 및 단위 테스트(test_stop_check_is_nfs_local)로 검증 완료하여 B-5 이슈를 정식 종결.

7. agent_identities tier-3 신원 캐시 완전 제거 및 UUID 해결 경로 PyYAML 탈의존 (B-10 / Option A)

• 쓰기 경로가 존재하지 않아 구조적으로 히트 불가였던 tier-3 폴백과 부속 소비자(workspace_uuid.py, reconcile.sh drift D, stop_session.sh 캐시 소거)를 전면 삭제.
• UUID 해결 경로를 tier-1(per-row own id) → tier-2(어댑터 discover()) 2단계로 단순화.
• verify_session.py::mam_orchestrator_uuids 의 즉시 yaml import 를 YAML 폴백 분기로 이동, UUID 해결 경로가 PyYAML 없이 완주함을 실행 가드로 고정(atomic_yaml.py 의 시스템 PyYAML 요구는 설계상 유지).
• 회귀 가드 3종 신설 — 읽기 경로 부활 차단, import yaml AST 검사(지연 import 포함), 실행 경로 검증.
• 회귀 및 계약 테스트: 266/266 PASS (100%) 달성.

8. 셀프 호스팅 루프 런타임 프리즈 스냅샷 (B-13 / Stage 2)

• 루프 기동 시 .agents/skills/ 를 $TMPDIR 에 1회 동결하고 스냅샷에서 재실행하여, 턴 도중 프레임워크 스킬 편집이 진행 중인 루프를 깨뜨리지 못하도록 차단.
• 코드 루트(스냅샷)와 상태 루트(MAM_REAL_ROOT)를 분리해 레지스트리·루프 락·diff 수집은 실제 저장소를 계속 사용.
• 재실행 시 원본 argv 를 배열로 보존해 인자 유실을 방지(파서가 $@ 를 소비하므로 필수).
• 스냅샷 생성 실패 시 log_* 정의 이전 구간임을 고려해 echo 로 경고하고 미동결 진행.
• MAM_LOOP_NO_FREEZE=1 로 비활성화 가능. 스냅샷 생성 실패는 경고 후 기존 동작으로 폴백.
• 회귀 가드 5종 신설 — argv 보존, 파손 래퍼 면역, 스킬 트리 무오염(B-6 경계), 락 해제 및 스냅샷 정리(B-12 경계), 비활성화 스위치.
• 회귀 및 계약 테스트: 271/271 PASS (100%) 달성.

9. 감사 로그 루트 지연 평가 (B-9 / P4-1)

• mqtt_common.LOGS_DIR 의 import 시점 cwd 고정을 제거하고 호출 시점에 해석하는 get_logs_dir() 를 도입. chdir 이후에도 감사 로그가 현재 워크스페이스에 정확히 기록됨.
• PEP 562 모듈 __getattr__ 로 LOGS_DIR 속성 접근 하위 호환 유지(동적 평가).
• PEP 562 __dir__ 병행 정의로 dir()·탭 완성 가시성 유지.
• DELEGATE_JOB_LOGS_DIR 환경변수가 실행 중 변경까지 반영.
• 회귀 가드 5종 신설 — cwd 추종, 실제 파일 생성, 환경변수 동적 반영, 전역 재도입 차단, dir() 탐색성.
• 회귀 및 계약 테스트: 276/276 PASS (100%) 달성.

---

🛠️ v1.4.0 — Stability, Cleanup & Safe Job Delegation (2026-08-16)

주요 마일스톤: 격리 잔재 정리, 서브셸 루프 락 조기 해제 버그 픽스, 신규 파일 캡처 및 경량화.

• P2-2 (C-3a / C-4 레거시 격리 스텁 및 미사용 심볼 제거):
  • lib.sh 내 빈 스텁 4종(provision_isolation, isolation_lever, isolation_env_prefix, isolation_cmd_args) 및 _REAL_HERDR_PATH 완전 삭제.
  • registry.py::TERMINAL_STATUSES 및 create_session.sh::ISOLATE 제거.
• P2-1 (B-6 / B-12 delegate_job_safe 안정화):
  • .agents/skills/... 내 불필요한 .tmp 복사본 생성 제거 및 인플레이스 직접 실행(bash "$orig_script") 전환.
  • 서브셸 내 trap으로 인한 루프 락 마커(.mam/loop-guard-active) 조기 삭제 결함(D1) 원천 차단.
• P0-2 (O-2 중복 루프 기동 방지 원자적 락):
  • loop_lock.sh 신설: set -C 기반 원자적 락 획득 및 PID + lstart 소유권 검증으로 동시 실행 방지.
• P0-1 (B-7 외곽 diff 수집 및 미추적 파일 캡처):
  • diff_collect.sh 도입: CWD 독립 $REPO_ROOT 기준 diff 수집 및 git ls-files -o 미추적 파일 병합.
• B-4 (시프트 ls 동적 포시스 타임스탬프 복원):
  • lib.sh 554행의 created=999999 하드코딩을 실시간 타임스탬프(int(time.time()))로 복원.
• 테스트 슈트 경량화:
  • 노후화된 중복 레거시 테스트 7개 파일(1,559줄) 삭제 (cf51b2c).

---

🛡️ v1.3.0 — Orchestrator Onboarding & Scoped Guarding (2026-08-15)

주요 마일스톤: 오케스트레이터 신원 격리 및 다중 에이전트 협업 가드레일 확립.

• multi-agent-mux-orc-onboard 스킬 신설:
  • 오케스트레이터(agy)의 대화 UUID를 .mam/agent-sessions.yaml 내 orchestrator_uuids 리스트로 등록.
  • find_workspace_uuid 및 verify_session_uuid에서 오케스트레이터 UUID를 스킵하여 서브에이전트 세션 오염 방지.
• O-3 (조건부 오케스트레이션 위임 가드 — Scoped Guard):
  • 오케스트레이터가 /multi-agent-mux-loop 활성화 상태에서 직접 코드를 수정하지 않고 스크립트로 위임하도록 통제.
  • AGENTS.md §5 및 MULTI_AGENT_RULES.md 내 가드레일 명시.
• 배포 및 패키징 파이프라인 현대화:
  • deploy/lib_ownership.sh 신설 및 hooks.json 3-way 병합(MERGE_REGISTRY) 지원.
  • Gitea CI/CD 파이프라인 (deploy/gitea-ci.yml) 연동.

---

🔌 v1.2.0 — Universal Herdr Server Isolation & Cline Integration (2026-08-14)

주요 마일스톤: Herdr 단일 서버 격리 및 다중 AI 에이전트 확장.

• Universal Herdr Session Isolation:
  • HERDR_SESSION_NAME 기반으로 격리 서버를 통일하여 프로세스 충돌 방지.
• Cline 에이전트 통합:
  • cline CLI 기반 대화 세션 생성, 정지, 복원 및 TUI 레디 토큰 핸들링 지원.
• SQLite WAL 트랜잭션 동시성:
  • 세션 레지스트리 동시 쓰기 시 발생하는 락 충돌을 방지하기 위해 SQLite WAL 모드 전면 적용.

---

🧱 v1.0.0 ~ v1.1.0 — Initial Multi-Agent Mux Framework (2026-08-10 ~ 2026-08-13)

주요 마일스톤: 터미널 다중 에이전트 오케스트레이션 기초 설계 및 비동기 루프 완성.

• 핵심 수명주기 스킬군 구축: create, stop, resume, status, monitor 스킬 기본 구현.
• MQTT 기반 비동기 잡 위임: multi-agent-mux-delegate-job을 통한 에이전트 간 이벤트 통신 및 결과 구독.
• 자율 협업 루프: multi-agent-mux-loop 컨트롤러를 통한 Planner-Creator-Reviewer 역할 분담 체계 정립.

---

🧪 품질 보증 및 검증 기준 (Verification Standards)

모든 릴리스는 다음 4단계 엄격한 검증을 통과해야 배포됩니다:

1. 정적 문법 검사: bash -n (모든 셸 스크립트) 및 AST 미사용 코드 분석.
2. 단위 및 컴포넌트 테스트 (Tier 1~2): 인플레이스 및 컴포넌트 간 상호작용 검증.
3. 통합 및 계약 테스트 (Tier 3~4 / Contract): clean environment (env -u PYTHONPATH) 하에서의 어댑터 계약 및 CLI 브리지 검증.
4. 멀티에이전트 교차 피어 리뷰: Planner(claude) 및 Reviewer(cline) 간 교차 검증 및 [VERDICT: PASS] 100% 합의.