# 📝 Multi-Agent Mux 작업 세션 기록 (`LOG.md`)

- **최종 기록일시**: 2026-08-16 10:00 (KST)
- **작업 저장소**: `tmpl/multi-agent-mux` (Branch: `main`)
- **작업 상태**: 모든 작업 완료, 세션 안전 종료(stopped), 저장소 상태 Clean!

---

## 📌 1. 금일 작업 내용 요약

### 1) **P3-1 (A-4 Phase 2 / Option B / C-3b / M2~M7): 에이전트 지식 계층 마이그레이션 및 isolation.root 완전 폐기** — **완료**
- **배경**: 에이전트별 아티팩트 경로, 검증 로직, 재개/시작 스펙, 토큰, 종료 키, 인증(`auth_ok`), 자동 발견(`discover`)이 스크립트 전반에 하드코딩 산재되어 있던 문제(A-4)와, Universal Global Config 전환 후에도 4개 지점에 남아있던 `isolation.root` 소비자(C-3b)를 완전 폐기하고 어댑터 단일 소스로 일원화.
- **주요 구현**:
  - [`.agents/skills/lib_py/agents/base.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib_py/agents/base.py): `DiscoveryContext` 확장 (`ws_key`, `cwd`, `home_dir`, `claude_dir`, `epoch`, `row`, `mode`), `BaseAgentAdapter` 추상 인터페이스 정의 (`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/`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib_py/agents/adapters/): `claude.py`, `agy.py`, `hermes.py`, `cline.py` 4개 어댑터 구체 클래스 구현 (Cline `resume_spec` `-i --id` 수정 반영, `auth_ok`, `discover` 구현).
  - [`.agents/skills/lib_py/agents/__main__.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib_py/agents/__main__.py): 8개 `MAM_*` 변수 `shlex.quote` 셸 브리지 완성.
  - [`.agents/skills/lib_py/verify_session.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib_py/verify_session.py): `adapter.verify_artifact(uuid, ctx)` 위임 및 `iso_root` 분기 제거.
  - [`.agents/skills/lib_py/workspace_uuid.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib_py/workspace_uuid.py): `iso_root_of` 제거 및 디스크 스캔을 `adapter.discover(ctx)`로 단일화.
  - [`.agents/skills/lib_py/atomic_yaml.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib_py/atomic_yaml.py): 레거시 `isolation` 유효성 검사 절 제거.
  - [`.agents/skills/lib.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh): `mam_session_iso_root` 제거, `wait_for_tui_ready` 셀프 컨테인드 토큰 폴백 및 claude `projects` 토큰 제거.
  - [`.agents/skills/multi-agent-mux-create/scripts/create_session.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-create/scripts/create_session.sh): `CMD_FULL` (어댑터 `spawn_spec`) 및 `delegate_agent` (`delegate_agent_key`) 이관.
  - [`.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh): `_iso_root` 분기 완전 제거 및 `CMD_FULL` 을 `adapter.resume_spec`으로 이관.
  - [`.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh): `row_agent` / `_pin_and_verify_resume` / `OWN_KEY_BY_AGENT` / auto-register `cmd_full` 을 어댑터 레이어로 이관.
  - [`.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh): `exitkey` (`adapter.exit_key`), `adapter.purge_artifacts`, `adapter.identity_cache_fields` 위임 및 레거시 격리 삭제 블록 제거.
  - [`tests/test_a4_adapter_contract.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/tests/test_a4_adapter_contract.py): facts eval 계약, 어댑터 속성 계약, 복합 아티팩트 삭제(purge_artifacts), spawn/resume_spec 계약, auth_ok 계약, discover 계약 테스트 9종 추가.
  - [`IMPROVEMENTS.md`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/IMPROVEMENTS.md): A-4 및 C-3b 완료 처리 및 19개 과제 완결 상태 동기화.
- **검증**: `pytest` 실행 결과 **259 passed in 493s (100%)**.

### 2) **P2-2 (C-3a / C-4): 레거시 격리 스텁 및 미사용 심볼 제거** — **완료**
- **배경**: 격리 구조가 Universal Global Config(Job `536a6625`)로 전환되며 남은 빈 스텁 4종과, 그 빈 출력만 재확인하던 공허한 테스트 4건, 그리고 참조 0회 심볼 3종 정리.
- **주요 구현**:
  - [`.agents/skills/lib.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh): 빈 스텁 4종(`provision_isolation`, `isolation_lever`, `isolation_env_prefix`, `isolation_cmd_args`) 및 `_REAL_HERDR_PATH` 대입·export 제거, 주석에 C-3b 경계 명시.
  - [`.agents/skills/multi-agent-mux-delegate-job/scripts/registry.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-delegate-job/scripts/registry.py): `TERMINAL_STATUSES` 제거.
  - [`.agents/skills/multi-agent-mux-create/scripts/create_session.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-create/scripts/create_session.sh): `ISOLATE` 제거.
  - [`tests/test_tier1_unit.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/tests/test_tier1_unit.py) / [`tests/test_tier2_component.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/tests/test_tier2_component.py): 공허한 테스트 4건 제거 및 `--isolate`/`--no-isolate` no-op 회귀 가드 1건 신설(변이 4종 검출 입증), 섹션 헤더 동기화.
  - [`IMPROVEMENTS.md`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/IMPROVEMENTS.md): C-4 완결 및 C-3a 완료 반영, C-3b 존속.
- **검증**: `pytest tests/ -q` **256 passed (100%)**.

### 2) **P2-1 (B-6 / B-12): `delegate_job_safe` 임시 사본 제거 및 서브셸 루프 락 조기 해제 차단 조치** — **완료**
- **배경**: `run_loop.sh::delegate_job_safe` 가 `.agents/skills/...` 내부에 `.tmp` 사본을 생성하여 트리 오염 및 배포 시 유출(B-6)되던 문제와, 명령 치환 서브셸 내의 `trap _mam_release_guard EXIT` 로 인해 첫 번째 잡 위임 시 루프 락 마커(`.mam/loop-guard-active`)가 조기 삭제되어 O-3 가드레일이 무력화되던 결함(**B-12 / D1**) 조치.
- **주요 구현**:
  - [`.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh): `delegate_job_safe` 를 임시 사본 및 서브셸 트랩 없이 인플레이스로 직접 실행(`bash "$orig_script" "$@"`)하도록 개선하고 실패 시 진단 로깅 추가. 루프 기동 시 기존 잔여 `.tmp` 스윕 구문 추가.
  - [`IMPROVEMENTS.md`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/IMPROVEMENTS.md): B-6 완료 상태 갱신, B-12 (D1) 결함 명세 및 B-13 (턴 간 스킬 오염) Stage 2 과제 등록.
  - [`tests/test_o3_scoped_guard.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/tests/test_o3_scoped_guard.py): 취약한 문자열 검사 Z-9를 4개 행위 기반 테스트(`test_z9_loop_lock_survives_delegation`, `test_z9_probe_detects_the_defect`, `test_z9_no_tmp_copy_left_in_skill_tree`, `test_z9_exit_code_and_diagnostics_propagation`)로 교체.
- **검증**: `pytest tests/ -q` 실행 결과 **259 passed (100%)** 달성.

### 2) **multi-agent-mux-orc-onboard: 오케스트레이터 온보딩 스킬 및 `orchestrator_uuids` 배제 게이트 구축** — **완료**
- **배경**: 오케스트레이터(`agy`)가 서브 에이전트 생성/정지/복원 시 자기 대화 UUID가 `agent-sessions.yaml` 서브 세션으로 오염 캡처되어 SQLite DB 락(`database is locked`) 및 대화 충돌이 발생하던 결함 조치.
- **주요 구현**:
  - [`.agents/skills/multi-agent-mux-orc-onboard/SKILL.md`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-orc-onboard/SKILL.md) 및 [`.agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh): 오케스트레이터의 신원 UUID를 포착하여 `.mam/agent-sessions.yaml` 및 SQLite DB 내 `orchestrator_uuids` 리스트로 원자적 등록하는 스킬 구축.
  - [`.agents/skills/lib.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh): `find_workspace_uuid` 및 `verify_session_uuid`에 `orchestrator_uuids` 배제 게이트를 내장하여 오케스트레이터 대화 ID 스킵(Skip) 확립.
  - `tests/test_orc_onboard.py`: 전용 회귀 테스트 40개 작성 및 **40/40 PASS (100%)** 달성.
- **멀티에이전트 자율 오케스트레이션**: `/multi-agent-mux-loop --plan --all-reviewer` 가동 결과 Planner(`claude`), Creator(`agy`), Reviewer(`cline`) 3자에 의해 **`[VERDICT: PASS]` (만장일치 통과)**.

### 2) **P0-2 (O-2): 동일 워크스페이스 내 중복 루프 기동 방지 원자적 락 및 마커 소유권 대조 삭제 조치** — **완료**
- **배경**: 루프 중복 기동 시 마커 무단 덮어쓰기로 인한 데이터 오염 및 먼저 종료된 루프 인스턴스의 무차별 마커 삭제로 O-3 위임 가드레일이 조용히 무력화되던 결함 조치.
- **주요 구현**:
  - [`.agents/skills/multi-agent-mux-loop/scripts/loop_lock.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-loop/scripts/loop_lock.sh): `set -C` 기반 원자적 락 획득, `pid` + `lstart` 신원 대조 검증 및 중복 루프 기동 차단 모듈 구현.
  - [`.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh): `_mam_release_guard` 종료 트랩 시 `pid` + `lstart` 소유권 대조 검증 삭제 구현.
  - `tests/test_o2_race_free_lock.py`: 전용 회귀 테스트 22개 작성 및 **22/22 PASS (100%)** 달성. 전체 회귀 테스트 **46/46 PASS (100%)**.

### 2) **P0-1 (B-7): `run_loop.sh` 루프 기동 외곽 diff 누락 및 신규 미추적 파일 캡처 결함 조치** — **완료**
- **배경**: CWD 의존성으로 인해 저장소 외곽에서 `run_loop.sh` 구동 시 `git diff` 실패 및 미추적 신규 파일(Untracked Files) 누락으로 리뷰어가 빈 diff 보고 무조건 `PASS`를 남기던 무음 검증 결함 조치.
- **주요 구현**:
  - [`.agents/skills/multi-agent-mux-loop/scripts/diff_collect.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-loop/scripts/diff_collect.sh): CWD 독립 `$REPO_ROOT` 이동 및 Git 인덱스 비침습 신규 파일 병합(`git ls-files -o --exclude-standard -z` + `git diff --no-index`) 구현.
  - [`.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh): `CHANGES_DIFF` 모듈화 및 500줄/30KB 상한 Truncation 경고 노출 내장.
  - `tests/test_b7_diff_untracked.py`: 전용 회귀 테스트 스위트 20개 작성 및 **20/20 PASS (100%)** 달성.
- **멀티에이전트 자율 오케스트레이션**: `/multi-agent-mux-loop --plan --all-reviewer` 가동 결과 Planner(`claude`), Creator(`agy`), Reviewer(`cline`) 3자에 의해 **`[VERDICT: PASS]` (만장일치 통과)**.

### 2) **B-4: 시프트 `ls` 세션 생성 시각(session_created) 동적 포시스 타임스탬프 복원** — **완료**
- **배경**: `.agents/skills/lib.sh` 554번 라인에서 `herdr ls` 시 생성시각이 `999999`로 하드코딩되어 `reconcile.sh` drift-B 등록 시 epoch 0이 되어 `find_workspace_uuid` 재개 가드가 붕괴되던 결함 조치.
- **주요 구현**:
  - [`.agents/skills/lib.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh): real herdr 및 YAML 상의 `created`/`created_at`/`created_epoch` 속성을 읽고, 미정의 시 `int(time.time())` 동적 포시스 타임스탬프를 리턴하도록 정제.
  - [`reconcile.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh): `created` fallback 포맷팅 보완.
  - `tests/test_b4_session_created.py`: 전용 회귀 테스트 21개 항목 작성 및 **21/21 PASS (100%)** 달성.
- **멀티에이전트 자율 오케스트레이션**: `/multi-agent-mux-loop --plan --all-reviewer` 가동 결과 Planner(`claude`), Creator(`agy`), Reviewer(`cline`) 3자에 의해 **`[VERDICT: PASS]` (만장일치 통과)**.

### 2) **deploy/ 배포 스크립트 최신화 및 레지스트리 3-way 병합 구현** — **완료**
- **배경**: `deploy/install.sh` 및 `install_mam.sh`가 `.agents/skills/` 밖 자산(`hooks.json`, `MULTI_AGENT_RULES.md`, `INSTALL.md`)을 갱신하지 못하거나 로컬 훅 수정을 덮어쓰는 맹점(Job `1567c88e` / Plan Rev.2) 해결.
- **주요 구현**:
  - `deploy/lib_ownership.sh` 신설: 자산 소유권 및 레지스트리 파일 관리 단일 창구화.
  - `deploy/install.sh`: `hooks.json` 키 단위 3-way 병합(`MERGE_REGISTRY`) 및 `.mam/base/` 스냅숏 도입.
  - `deploy/install_mam.sh` & `deploy/remove.sh`: `asset_hashes.txt` 및 `.mam/base/` 자동 생성과 fallback 자산 목록 동기화.
  - `deploy/gitea-ci.yml` & `deploy/README.md`: CI pytest 자동화 게이트 및 문서 구조 갱신.
  - 커밋 완료 (`399242d`, `cc11a02`).

### 2) **테스트 슈트 경량화 및 다이어트** — **완료**
- 중복되고 오래된 레거시 테스트 7개 파일(1,559줄) 완전히 삭제 (`cf51b2c`).
- 핵심 계층별 테스트 슈트(Tier 1~4, Deploy, Guard)만 정비하여 향후 기능 변경 시 실행 속도 및 자원 소모 대폭 개선.

### 3) **O-3: 조건부 오케스트레이션 위임 가드 (Invocation-Aware Scoped Guard)** — **완료**
- **배경**: 오케스트레이터 에이전트가 `/multi-agent-mux-loop` 실행 시 직접 코드를 수정하지 않고 스크립트로 위임하도록 통제하며, 루프 내부에서 무한 재귀 기동되는 현상을 원천 방지함.
- **주요 수정 파일**:
  - `.agents/skills/multi-agent-mux-loop/scripts/run_loop.sh`: PID + 시작시각 기반 `.mam/loop-guard-active` 식별자 작성 및 `trap` 자동 삭제 적용.
  - `AGENTS.md`: Section 5 (Orchestrator Scope Guard O-3) 명시.
  - `.agents/MULTI_AGENT_RULES.md` & `.ko.md`: 오케스트레이터 세션 및 루프 활성화 모드 수칙 동기화.
  - `tests/test_o3_scoped_guard.py`: 24개 검증 케이스 작성 (24/24 PASS).
- **멀티에이전트 자율 피어 리뷰**: Planner(`claude`), Creator(`agy`), Reviewer(`cline`) 3자에 의해 루프 구동 후 **`[VERDICT: PASS]` (100% 합의)** 통과 및 커밋 완료 (`1f8622e`).

### 2) **A-3 & C-2 과제 완수 및 안정화 버그 수정** — **완료**
- **A-3**: `send_keys_safe` 시프트 버퍼 동시성 레이스 조건 해결 (호출 고유 토큰 생성 + 원자적 쓰기/이동 + 60분 자동 GC).
- **C-2**: 미사용 `.cache/multi-agent-mux-monitor` 디렉터리 생성 로직 축소 및 `reconcile.sh` 상태 dead code 정리.
- **환경 변수 전파 보완**: `.agents/skills/lib.sh` 내 `HOME_DIR`, `CLAUDE_PROJECT_DIR`, `LOCAL_BIN` 하위 프로세스 `export` 누락 해결 (`2fc0f58`).
- **테스트 슈트 Mock 지원**: `tests/conftest.py` 내 `mock_herdr`에 `list-panes` 핸들러 추가 (`778b22b`).
- **상태 복구 안전성**: `reconcile.sh` 내 세션 생성 시각 안전 키 접근(`t.get('created', 0)`) 반영 (`36d0178`).

---

##  Git 커밋 내역 (Total 8 Commits on `refactor`)

1. `2fc0f58`: `fix(lib): export HOME_DIR, CLAUDE_PROJECT_DIR, and LOCAL_BIN in lib.sh for proper child environment inheritance`
2. `55fc739`: `fix(lib): use symlink-safe realpath comparison for workspace cwd matching in find_workspace_uuid`
3. `778b22b`: `fix(test): add list-panes support to mock_herdr and fix environment overrides in tier3 integration tests`
4. `9f266e6`: `test(integration): update test_tier3_integration to align with global config-home convention`
5. `7e16d65`: `test(integration): refine test_integration_create_options_combination to test herdr spawn without wrapper`
6. `1658af4`: `test(sanity): update test_sanity assertions to align with removed config-home isolation`
7. `1f8622e`: `feat(o3): implement Invocation-Aware Scoped Guard for orchestrator role scoping (100% PASS)`
8. `5ab7687`: `fix(c2): remove unused .cache directory creation and clean up state dead code (100% PASS)`
9. `3530e8b`: `fix(a3): resolve shift buffer race condition with call-unique tokens, atomic write, and automatic GC (100% PASS)`

---

## 🤖 3. 라이브 에이전트 세션 현황 (`herdr: multi-agent-mux`)

| 에이전트 이름 | 역할 | herdr 세션 상태 | 비고 |
| :--- | :--- | :--- | :--- |
| `canary-projects-multi-agent-mux-creator-claude` | Planner | `stopped` | 대화 UUID `01eae7cf...` 캡처 보존 완료 |
| `canary-projects-multi-agent-mux-creator-agy` | Creator | `stopped` | 대화 UUID `72d2d251...` 캡처 보존 완료 |
| `canary-projects-multi-agent-mux-creator-cline` | Reviewer | `stopped` | 대화 UUID `17856352...` 캡처 보존 완료 |

---

## 🚀 4. 추후 작업 재개 가이드 (Next Steps)

1. **세션 상태 확인**:
   ```bash
   bash .agents/skills/multi-agent-mux-status/scripts/status_session.sh
   ```
2. **백로그 확인 (`IMPROVEMENTS.md`)**:
   - 다음 우선순위 추천 과제:
     - **O-2**: 동일 워크스페이스 내 중복 루프 기동 방지 락 (Race-Free Lock)
     - **B-4**: 시프트 `ls`의 `created=0` 하드코딩 해결
3. **루프 구동으로 작업 재개**:
   ```bash
   /multi-agent-mux-loop --plan --all-reviewer "IMPROVEMENTS.md 백로그의 O-2 (또는 선택 과제) 문제를 해결해줘."
   ```