tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a5a0939866a6d5daaa7158320f1fb92b9775d22
multi-agent-mux/VERSIONS.md
T
Godopu c3631e2aa1 fix(herdr): resolve shim routing defects, add workspace scoping, and bump to v3.0.1 
- Resolve Herdr shim 5 routing & paste defects (ISSUE-1 ~ ISSUE-5):
  * paste-buffer: use pane send-text without auto-enter, propagate rc=3 to send_keys_safe
  * exact-match pane resolution: remove substring matching ('in tn') across all branches
  * workspace scoping: introduce HERDR_WORKSPACE_ID and .mam/herdr_workspace_id persistence
  * unified resolver: single _resolve_herdr_pane_id helper across shim commands
- Resolve dialog token false-positive on 'Yes, try it' tip and isolate fullscreen modal rejection
- Sync mock Herdr CLI contracts in tests/conftest.py
- Add contract tests H-15~H-23 and regression tests D-4~D-7 (412 tests, 100% PASS)
- Add multi-agent loop plans, review reports, and bug report
- Update framework and skill packages to v3.0.1
2026-08-27 21:42:37 +09:00

305 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 📜 Multi-Agent Mux 버전 이력 (`VERSIONS.md`)
이 문서는 `multi-agent-mux` 프레임워크의 버전별 주요 기능 추가, 아키텍처 개선, 버그 수정 및 품질 검증 이력을 기록합니다.
---
## 📌 현재 버전 개요 (Current Release)
- **프레임워크 버전**: `v3.0.1`
- **최신 릴리스 일시**: 2026-08-27 (KST)
- **기준 브랜치**: `main`
- **핵심 아키텍처**:
- **Herdr Shim Routing & Multi-Workspace Isolation Engine**: `HERDR_WORKSPACE_ID` 환경 변수 스코핑 및 `$WORKSPACE_ROOT/.mam/herdr_workspace_id` 영속화 메커니즘을 통해 다중 워크스페이스 동시 실행 시 페인 교차 오염 원천 차단
- **Atomic Safe Paste Insertion (`pane send-text`)**: 미지원 서브커맨드(`agent send`) 제거 및 `pane send-text` 단일 삽입 계약 도입, `send_keys_safe` 실패 전파(`rc 3`) 및 중복 제출(Double Submit) 방지
- **Strict Exact-Match Single Pane Resolver**: 부분 문자열 매칭(`in tn`) 완전 제거, 단일 중앙 `_resolve_herdr_pane_id` 헬퍼 기반 5대 서브커맨드(`has-session`, `kill-session`, `capture-pane`, `send-keys`, `paste-buffer`) 무결성 정립
- **TUI Readiness & Dialog Token Precision**: `_MAM_DIALOG_TOKENS` 일반 팁(`Yes, try it`) 오탐 제거 및 풀스크린 모달 Escape 거절 브랜치 분리
- **Comprehensive Test Suite Milestone**: 412개 전체 테스트 100% PASS (412 passed / 0 failed).
---
## 🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)
모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v3.0.1`으로 동기화되어 배포됩니다.
| 스킬명 | 버전 | 역할 및 주요 책임 | 상태 |
| :--- | :---: | :--- | :---: |
| **`multi-agent-mux-create`** | `3.0.1` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
| **`multi-agent-mux-stop`** | `3.0.1` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
| **`multi-agent-mux-resume`** | `3.0.1` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
| **`multi-agent-mux-status`** | `3.0.1` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
| **`multi-agent-mux-monitor`** | `3.0.1` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
| **`multi-agent-mux-delegate-job`** | `3.0.1` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
| **`multi-agent-mux-loop`** | `3.0.1` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
| **`multi-agent-mux-orc-onboard`** | `3.0.1` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
---
## 📋 버전별 상세 변경 내역 (Changelog)
### 🚀 `v3.0.1` — Herdr Shim Routing Contract Refactor, Multi-Workspace Isolation & 412-Test Milestone (2026-08-27)
> **주요 마일스톤**: Herdr 심 라우팅 5대 결함(ISSUE-1~5) 및 F-1~F-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`](.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/`](.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% 합의.
Reference in New Issue View Git Blame Copy Permalink