From d7e19feaf54fa5bcea2f3762b0f39e0a39336aac Mon Sep 17 00:00:00 2001
From: Godopu <godopu16@gmail.com>
Date: Sat, 11 Jul 2026 00:41:12 +0900
Subject: [PATCH] refactor(installer): resolve architectural inconsistencies,
 pyyaml hard check, and migrate reports to tracked paths

---
 .agents/INSTALL.md                            |  2 +-
 .agents/MULTI_AGENT_RULES.ko.md               |  2 +-
 .agents/MULTI_AGENT_RULES.md                  |  2 +-
 .../brief-isolation-review.md                 | 28 ++++++++++
 .../report-isolation-review.md                | 56 +++++++++++++++++++
 .../brief-isolation-review.md                 | 28 ++++++++++
 .../brief.md                                  | 20 +++++++
 .../report-mam-installer-rereview.md          |  0
 .../report-mam-installer-review.md            |  0
 .../report-session-isolation-review.md        |  0
 scripts/install_mam.sh                        | 55 +++++++++++-------
 11 files changed, 169 insertions(+), 24 deletions(-)
 create mode 100644 .agents/reports/canary-projects-multi-agent-mux-creator-claude/brief-isolation-review.md
 create mode 100644 .agents/reports/canary-projects-multi-agent-mux-creator-claude/report-isolation-review.md
 create mode 100644 .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief-isolation-review.md
 create mode 100644 .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief.md
 rename {.mam => .agents}/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-rereview.md (100%)
 rename {.mam => .agents}/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-review.md (100%)
 rename {.mam => .agents}/reports/canary-projects-multi-agent-mux-reviewer-cline/report-session-isolation-review.md (100%)

diff --git a/.agents/INSTALL.md b/.agents/INSTALL.md
index 265b2b9..77f0d7b 100644
--- a/.agents/INSTALL.md
+++ b/.agents/INSTALL.md
@@ -92,4 +92,4 @@ $ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
 
 ## 🛡️ 협업 및 보안 가이드라인
 *   MAM을 사용할 때 모든 에이전트(개발자, 리뷰어)들은 루트의 `AGENTS.md` 지침을 우선 숙지하도록 설계해야 오탐과 무분별한 리팩토링 범람을 방지할 수 있습니다.
-*   각 에이전트 역할별로 리뷰 프로세스를 돌릴 시, 승인 결과 보고서(.md)는 `.mam/reports/<session_name>/` 하위에 생성 및 형상 커밋하는 규약(`.agents/MULTI_AGENT_RULES.md`)을 준수해 주세요.
+*   각 에이전트 역할별로 리뷰 프로세스를 돌릴 시, 최종 승인 결과 보고서(.md)는 형상 관리가 추적할 수 있도록 버전 관리 대상 경로(구체적으로 `.agents/reports/<session_name>/` 또는 `docs/reports/` 등) 하위로 이관 복사하여 커밋하는 규약(`.agents/MULTI_AGENT_RULES.md`)을 준수해 주세요.
diff --git a/.agents/MULTI_AGENT_RULES.ko.md b/.agents/MULTI_AGENT_RULES.ko.md
index 5c18332..55349e7 100644
--- a/.agents/MULTI_AGENT_RULES.ko.md
+++ b/.agents/MULTI_AGENT_RULES.ko.md
@@ -127,7 +127,7 @@ TMUX 환경에서 실행되는 에이전트가 화면 스크롤 한계로 인해
   - **디스크 정리 및 보존 정책 계약 (Cleanup & Retention)**:
     - `.mam/reports/` 폴더 아래의 파일들은 감사 이력(audit-trail) 산출물로 보존됩니다.
     - 해당 격리 디렉터리들은 `stop_session.sh` 등을 통해 세션이 정상적으로 종료되거나 파기(`--purge-conversation`)될 때 자동으로 함께 정리되어야 합니다.
-    - 버전 관리가 필요한 영구 보존용 주요 산출물(최종 설계 계획, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(예: `docs/` 또는 `artifacts/` 등)로 명시적으로 복사하여 기록을 이관 보존해야 합니다.
+    - 버전 관리가 필요한 영구 보존용 주요 산출물(최종 설계 계획, 최종 리뷰 보고서, 보안 감사 리포트 등)은 gitignore 대상인 `.mam/` 하위가 아닌, 버전 관리 대상 경로(구체적으로 `.agents/reports/<tmux_session_name>/` 또는 `docs/reports/` 등)로 명시적으로 복사하여 기록을 이관 보존해야 합니다.
 
 ### ⏱️ 타임아웃 구성 및 정렬 규칙
 - **잡 실행 제한 (`timeout_sec` & `idle_timeout_sec`)**: 각 잡은 전체 실행 만료 시간(`timeout_sec`, 기본 3600s)과 메세지 미수신 유휴 시간(`idle_timeout_sec`, 기본 120s)을 독립적으로 가집니다.
diff --git a/.agents/MULTI_AGENT_RULES.md b/.agents/MULTI_AGENT_RULES.md
index 1408b4b..23b7af6 100644
--- a/.agents/MULTI_AGENT_RULES.md
+++ b/.agents/MULTI_AGENT_RULES.md
@@ -127,7 +127,7 @@ To ensure that agents running in TMUX environments do not lose debug logs or pre
   - **Cleanup & Retention Contract**:
     - Files under `.mam/reports/` are audit-trail artifacts.
     - These folders should be cleaned up automatically during `stop_session.sh` when a session is gracefully stopped or purged (`--purge-conversation`).
-    - Durable outcomes (such as final design plans or security audit reports) that require version control must be explicitly copied to tracked directory paths (e.g., `docs/` or `artifacts/`) instead of remaining in the gitignored `.mam/` runtime tree.
+    - Durable outcomes (such as final design plans, review verdicts, or security audit reports) that require version control must be explicitly copied to tracked directory paths (specifically under `.agents/reports/<tmux_session_name>/` or `docs/reports/`) to preserve collaborative audit trails in version history, instead of remaining in the gitignored `.mam/` runtime tree.
 
 ### ⏱️ Timeout Configuration & Alignment Rules
 - **Job Execution Limits (`timeout_sec` & `idle_timeout_sec`)**: Each job independently manages its overall execution timeout (`timeout_sec`, default 3600s) and idle timeout without receiving messages (`idle_timeout_sec`, default 120s).
diff --git a/.agents/reports/canary-projects-multi-agent-mux-creator-claude/brief-isolation-review.md b/.agents/reports/canary-projects-multi-agent-mux-creator-claude/brief-isolation-review.md
new file mode 100644
index 0000000..9bd3d05
--- /dev/null
+++ b/.agents/reports/canary-projects-multi-agent-mux-creator-claude/brief-isolation-review.md
@@ -0,0 +1,28 @@
+# 📋 세션 ID 중복 충돌 해결 종합 설계안 리뷰 요청 지시서
+
+- **요청자**: Planner Agent (Antigravity)
+- **수신자**: Reviewer Agent (Claude)
+- **대상 세션**: `canary-projects-multi-agent-mux-creator-claude`
+- **검토 대상 파일**: [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md)
+
+---
+
+## 1. 개요 및 검토 요청 사항
+
+기존에 진행되었던 세션 ID 중복 충돌 해결 설계 토론 보고서에 Planner Agent가 새로 작성한 구체적 구현 계획(Rev.2)을 성공적으로 통합 및 단일화하였습니다.
+
+수신자(Claude) 에이전트님은 통합된 [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md) 문서를 검토하시어 아래 기준을 만족하는지 검사해 주시기 바랍니다.
+
+### 주요 검토 기준
+1. **의견 반영의 정합성**: Claude 에이전트 본인이 2차 토론 및 `implementation_plan.session_isolation.md`에서 개진했던 핵심 논지(3계층 하이브리드 격리 체계, Phase 0 검증 게이트, claimed-set resolver 필터 등)가 유실 없이 충실히 설계 및 구현 계획안에 녹아 들어가 있는지 검사하십시오.
+2. **논리적 정합성**: Phase 0 ~ Phase 4 로드맵이 논리적인 순서로 설계되어 있으며, Phase 0(실측 검증)의 게이트로서의 기능이 올바르게 설계되었는지 확인하십시오.
+3. **누락 확인**: 문제 해결을 위해 이전에 논의되었던 내용(예: RC-2 청소 계약, R1/R2 이중 안전장치 등)이 누락 없이 적절하게 기입되었는지 점검하십시오.
+
+---
+
+## 2. 작업 결과 보고 양식
+
+검토를 마친 후, 본인의 의견과 최종 승인 여부를 아래에 명시된 경로에 기록해 주십시오.
+
+*   **리포트 작성 경로**: `.mam/reports/canary-projects-multi-agent-mux-creator-claude/report-isolation-review.md`
+*   **승인 불변식**: 검토 결과 설계가 완벽하고 구현 계획으로 전환하는 데 이견이 없다면 리포트 및 최종 응답(Completed Event Detail)의 마지막에 반드시 **`"PASS"`** 문자열을 포함하여 응답해 주십시오. 만약 수정이나 보완이 필요하다면 구체적인 피드백을 전달해 주십시오.
diff --git a/.agents/reports/canary-projects-multi-agent-mux-creator-claude/report-isolation-review.md b/.agents/reports/canary-projects-multi-agent-mux-creator-claude/report-isolation-review.md
new file mode 100644
index 0000000..a2491b3
--- /dev/null
+++ b/.agents/reports/canary-projects-multi-agent-mux-creator-claude/report-isolation-review.md
@@ -0,0 +1,56 @@
+# 🔍 리뷰 리포트 — 세션 ID 격리 종합 설계/구현 계획서 검토
+
+- **리뷰어**: Claude (Reviewer A — 상위 논리/설계 정합성)
+- **검토 대상**: `session_isolation_discussion.md` (Planner 통합본, Rev.2 반영)
+- **대조 기준**: 본인 작성 `implementation_plan.session_isolation.md` (Rev.2) + 2차 토론 합의
+- **job_id**: 655fb695
+- **날짜**: 2026-07-10
+- **최종 판정**: **PASS** (경미한 비차단 권고 3건 동반)
+
+---
+
+## 1. 검토 기준별 결과
+
+### 기준 1 — 의견 반영의 정합성 ✅
+본인이 개진한 핵심 논지가 **유실 없이** 통합됨을 확인:
+| 원안 논지 | 통합본 위치 | 상태 |
+|---|---|---|
+| 3계층 하이브리드 (L1 인자주입 / L2 디렉터리 격리 / R1 불변식) | §2.1, mermaid 다이어그램 | ✅ 충실 |
+| L1: `uuidgen` 사전발급 → `--session-id` 주입 → `*_own` 즉시 기록 | L1 (line 36-37) | ✅ |
+| L2: env 격리 + `env_overrides` 영속화 + resume 재적용 | L2 (line 38-40), T6 | ✅ |
+| R1 claimed-set 필터 + R2 생성-시 유일성 assert | R1/R2 (line 41-43), T1/T2 | ✅ |
+| Phase 0 검증 게이트, 게이트 통과 전 구현 금지 | line 51, §Phase 0 | ✅ |
+| agent별 ID 발급 비대칭(claude UUID vs cline `epoch_rand`) | RK3 (line 104) | ✅ |
+
+### 기준 2 — 논리적 정합성 ✅
+- **Phase 0→(L1/L2 분기)→Phase 1→Phase 2/3→Phase 4** 로드맵이 인과적으로 타당.
+- **Phase 0가 게이트로서 올바르게 기능**: line 51에서 "Phase 0 통과 전 코드 구현 착수 금지"를 대전제로 명시하고, G1/G2 실측 매트릭스가 L1/L2 라우팅을 결정(line 55-56, 73) — 게이트 의미론 정확. cline 미지원 리스크가 코드 착수 전에 해소되는 구조라 사이드이펙트 예방 설계가 성립.
+- Phase 1(R1/R2)이 전략 무관 선행 가능하다는 원안 취지도 반영(line 58, "선행 가능").
+
+### 기준 3 — 누락 확인 ✅
+- **RC-2 청소 계약**: §2.1 RC-2(line 44-45) + T7(line 88) + RK4(line 105)로 3중 기입 — 누락 없음.
+- **R1/R2 이중 안전장치**: line 41-43에 defense-in-depth로 명확히 기입.
+- Phase별 DoD, Phase 4 회귀검증(V1~V3) 모두 존재.
+
+---
+
+## 2. 🟡 비차단 권고 (구현 계획 세련화용, PASS 조건 아님)
+
+- **A-1. Non-Goal 명시 부재**: 원안의 명시적 Non-Goal("CLI(claude/cline/agy/hermes) 자체 미수정 — 인자/환경변수 인터페이스만 사용")이 통합본엔 문장으로 빠져 있음(접근법상 내재되어 있으나 암묵적). 오해 방지 위해 1줄 명문화 권고.
+- **A-2. RK5 `--isolate-strict` 신규 요소**: 원안엔 없던 "격리 활성화를 세션 다중성/명시 플래그로 제어"(line 106)가 추가됨 — 합리적 개선이나 **새 설계 결정**이므로 Phase 0/1 계획 시 스코프로 확정 필요(플래그 기본값·발동 조건).
+- **A-3. Phase 1 순서 표기 미세 모호**: 다이어그램(line 53-63)은 Phase 1을 Phase 0 아래에 선형 배치하나 본문은 "선행 가능"이라 표기 — Phase 1이 Phase 0 산출물에 의존하지 않음을 한 줄로 명확화하면 좋음(기능적 문제 아님).
+
+---
+
+## 3. 판정 요약
+
+| 관점 | 결과 |
+|---|---|
+| 의견 반영 정합성 | ✅ 핵심 논지 유실 없음 |
+| 논리적 정합성 / Phase 0 게이트 | ✅ 인과 타당, 게이트 의미론 정확 |
+| 누락 확인 (RC-2, R1/R2) | ✅ 누락 없음 |
+| 비차단 권고 | 🟡 A-1/A-2/A-3 (계획 세련화용) |
+
+통합본은 2차 토론 합의와 Rev.2 구현 계획을 **충실·완전하게** 반영했고, 결정적으로 **Phase 0 실측 게이트가 구현 전에 위치**하여 잔여 불확실성(특히 cline)이 코드 착수 전에 해소되는 안전 구조를 갖췄습니다. 구현 계획으로 전환하는 데 이견 없습니다. A-1~A-3는 Phase 0 착수 시 함께 반영 권고.
+
+**PASS**
diff --git a/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief-isolation-review.md b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief-isolation-review.md
new file mode 100644
index 0000000..cf1ed71
--- /dev/null
+++ b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief-isolation-review.md
@@ -0,0 +1,28 @@
+# 📋 세션 ID 중복 충돌 해결 종합 설계안 리뷰 요청 지시서
+
+- **요청자**: Planner Agent (Antigravity)
+- **수신자**: Reviewer Agent (Cline)
+- **대상 세션**: `canary-projects-multi-agent-mux-reviewer-cline`
+- **검토 대상 파일**: [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md)
+
+---
+
+## 1. 개요 및 검토 요청 사항
+
+기존에 진행되었던 세션 ID 중복 충돌 해결 설계 토론 보고서에 Planner Agent가 새로 작성한 구체적 구현 계획(Rev.2)을 성공적으로 통합 및 단일화하였습니다. 특히 모든 에이전트들을 격리 디렉터리 방식으로 일원화 관리하자는 사용자 피드백을 반영하였습니다.
+
+수신자(Cline) 에이전트님은 통합 및 단순화된 [session_isolation_discussion.md](file:///home/godopu16/PuKi/laa/canary_projects/multi-agent-mux/session_isolation_discussion.md) 문서를 검토하시어 아래 기준을 만족하는지 검사해 주시기 바랍니다.
+
+### 주요 검토 기준
+1. **의견 반영의 정합성**: 모든 에이전트가 격리 디렉터리 오버라이드 방식(L2)으로 일원화된 설계 구조가 논리적/구조적으로 타당한지 검사하십시오.
+2. **누락 확인**: 문제 해결을 위해 이전에 논의되었던 내용(예: RC-2 청소 계약, R1/R2 이중 안전장치 등)이 누락 없이 적절하게 기입되었는지 점검하십시오.
+3. **DoD 검증성**: 각 단계별 정의된 DoD(Definition of Done) 및 최종 검증(V1~V3) 단계가 실제 Cline 에이전트의 관점에서도 무결하고 재현 가능한지 평가하십시오.
+
+---
+
+## 2. 작업 결과 보고 양식
+
+검토를 마친 후, 본인의 의견과 최종 승인 여부를 아래에 명시된 경로에 기록해 주십시오.
+
+*   **리포트 작성 경로**: `.mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-isolation-review.md`
+*   **승인 불변식**: 검토 결과 설계가 완벽하고 구현 계획으로 전환하는 데 이견이 없다면 리포트 및 최종 응답(Completed Event Detail)의 마지막에 반드시 **`"PASS"`** 문자열을 포함하여 응답해 주십시오. 만약 수정이나 보완이 필요하다면 구체적인 피드백을 전달해 주십시오.
diff --git a/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief.md b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief.md
new file mode 100644
index 0000000..a480430
--- /dev/null
+++ b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/brief.md
@@ -0,0 +1,20 @@
+# Onboarding & Project Context Analysis Brief
+
+안녕하세요 Reviewer Cline Agent.
+당신은 본 프로젝트의 **리뷰어(Reviewer)** 역할을 위임받았습니다.
+실무 또는 검수 작업을 위임받기 전에, 설계 규약에 따라 다음 맥락 파악 작업을 완료해 주세요.
+
+## 📋 온보딩 요구사항 (Onboarding Checklist)
+
+1. **설계 규약 및 제약사항 숙지**
+   - [README.md](../../README.md) 및 [.agents/MULTI_AGENT_RULES.ko.md](../../.agents/MULTI_AGENT_RULES.ko.md)를 꼼꼼히 읽고 본 프레임워크의 규칙을 인지해 주세요.
+   - 특히 **TUI 뷰포트 절단 방지(Pane Snapshotting 3대 규칙)** 및 **마크다운 기반 협업 규약**을 지켜야 합니다.
+
+2. **레포지토리 활성 수정 내역 분석**
+   - `git status` 및 `git diff`를 실행하여 현재 진행 중인 배포 스크립트 URL 파라미터화 작업 관련 변경 사항을 분석하세요.
+
+3. **역할 및 타 에이전트 정보 검증**
+   - [.mam/agent-sessions.yaml](../agent-sessions.yaml)을 읽어 자신의 지정된 역할(`role: reviewer`)과 현재 러닝 상태인 타 에이전트 목록을 확인하세요.
+
+## 🏁 완료 보고 (Handshake Complete)
+위 파악이 끝나면 본 세션의 터미널 상에서 분석 결과 요약과 함께 **"Onboarding complete; aligned with role reviewer"** 라는 단말 완료 이벤트를 발행하거나 메시지를 출력해 주세요.
diff --git a/.mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-rereview.md b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-rereview.md
similarity index 100%
rename from .mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-rereview.md
rename to .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-rereview.md
diff --git a/.mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-review.md b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-review.md
similarity index 100%
rename from .mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-review.md
rename to .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-mam-installer-review.md
diff --git a/.mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-session-isolation-review.md b/.agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-session-isolation-review.md
similarity index 100%
rename from .mam/reports/canary-projects-multi-agent-mux-reviewer-cline/report-session-isolation-review.md
rename to .agents/reports/canary-projects-multi-agent-mux-reviewer-cline/report-session-isolation-review.md
diff --git a/scripts/install_mam.sh b/scripts/install_mam.sh
index 857cef7..d6710f4 100755
--- a/scripts/install_mam.sh
+++ b/scripts/install_mam.sh
@@ -65,7 +65,13 @@ while [ -h "$SOURCE" ]; do
 done
 DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
 SRC_DIR="$(cd "$DIR/.." && pwd)"
-TARGET_DIR="$(mkdir -p "$TARGET_DIR" && cd "$TARGET_DIR" && pwd)"
+
+# Ensure target directory exists
+if [ ! -d "$TARGET_DIR" ]; then
+  log_info "Creating target directory: $TARGET_DIR"
+  mkdir -p "$TARGET_DIR"
+fi
+TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
 
 log_info "Installing MAM skills to target project: $TARGET_DIR"
 log_info "Source directory resolved: $SRC_DIR"
@@ -77,7 +83,7 @@ fi
 
 # 1. Dependency Checks
 log_info "Verifying host dependencies..."
-DEPS=(tmux python3 sqlite3 rsync)
+DEPS=(tmux python3 sqlite3 rsync uuidgen flock)
 MISSING_DEPS=()
 for dep in "${DEPS[@]}"; do
   if ! command -v "$dep" &>/dev/null; then
@@ -91,10 +97,11 @@ if [ ${#MISSING_DEPS[@]} -ne 0 ]; then
   exit 1
 fi
 
-# Check Python PyYAML library
+# Check Python PyYAML library (hard dependency for YAML registry parsing)
 if ! python3 -c "import yaml" &>/dev/null; then
-  log_warn "Python 'pyyaml' package is not installed. Python YAML parsing features may fail."
-  log_warn "Please run: pip install pyyaml"
+  log_error "Python 'pyyaml' package is not installed (hard dependency for session registry)."
+  log_error "Please run: pip install pyyaml"
+  exit 1
 fi
 log_ok "Dependency checks completed."
 
@@ -103,23 +110,32 @@ log_info "Deploying orchestration rules & skills (.agents/)..."
 mkdir -p "$TARGET_DIR/.agents"
 
 # Sync rules and skills, avoiding copying temporary or system files
-# Exclude git histories or internal runtime cache if any
-rsync -a --exclude='.git/' --exclude='reports/' --exclude='*.log' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
+# Exclude git histories, reports, logs or internal runtime cache if any
+rsync -a --exclude='.git/' --exclude='/reports/' --exclude='*.log' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
 log_ok "Deployed Rules and Skills under target's .agents/"
 
-# 3. Copy AGENTS.md to root
+# 3. Copy AGENTS.md to root or inject guidelines pointer
 log_info "Configuring developer guidelines (AGENTS.md)..."
-if [ -f "$TARGET_DIR/AGENTS.md" ]; then
+AGENTS_FILE="$TARGET_DIR/AGENTS.md"
+MARKER_START="<!-- BEGIN MAM ORCHESTRATION -->"
+MARKER_END="<!-- END MAM ORCHESTRATION -->"
+
+if [ -f "$AGENTS_FILE" ]; then
   if [ "$FORCE" -eq 1 ]; then
-    log_warn "AGENTS.md already exists in target project. Backing up and overwriting..."
-    cp "$TARGET_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md.bak.$(date +%s)"
-    cp "$SRC_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md"
+    log_warn "AGENTS.md already exists in target project. Backing up and overwriting (--force)..."
+    cp "$AGENTS_FILE" "$AGENTS_FILE.bak.$(date +%s)"
+    cp "$SRC_DIR/AGENTS.md" "$AGENTS_FILE"
     log_ok "Guidelines overwritten successfully."
   else
-    log_warn "AGENTS.md already exists in target. Skipping copy. Use -f/--force to overwrite."
+    if grep -Fq "$MARKER_START" "$AGENTS_FILE"; then
+      log_ok "MAM orchestration guidelines pointer already exists in AGENTS.md."
+    else
+      echo -e "\n$MARKER_START\n# 🤖 Multi-Agent Orchestration Guidelines\nPlease refer to [.agents/MULTI_AGENT_RULES.md](file://./.agents/MULTI_AGENT_RULES.md) for detailed collaborative rules and state flow constraints.\n$MARKER_END" >> "$AGENTS_FILE"
+      log_ok "Injected MAM guidelines pointer to existing AGENTS.md."
+    fi
   fi
 else
-  cp "$SRC_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md"
+  cp "$SRC_DIR/AGENTS.md" "$AGENTS_FILE"
   log_ok "Guidelines AGENTS.md copied to project root."
 fi
 
@@ -129,8 +145,8 @@ GITIGNORE="$TARGET_DIR/.gitignore"
 MAM_PATTERN="/.mam/"
 
 if [ -f "$GITIGNORE" ]; then
-  if grep -Fqx "$MAM_PATTERN" "$GITIGNORE"; then
-    log_ok "/.mam/ already registered in target's .gitignore."
+  if grep -Eq '^/?\.mam/?$' "$GITIGNORE"; then
+    log_ok ".mam/ already registered in target's .gitignore."
   else
     echo -e "\n# Multi-Agent Mux (MAM) runtime databases and isolation cache\n$MAM_PATTERN" >> "$GITIGNORE"
     log_ok "Appended /.mam/ registration to .gitignore."
@@ -140,10 +156,6 @@ else
   log_ok "Created .gitignore with /.mam/ exclusion."
 fi
 
-# 5. Initialize runtime reports folder
-mkdir -p "$TARGET_DIR/.mam/reports"
-log_ok "Initialized runtime structures."
-
 # Done
 log_ok "MAM Installation completed successfully!"
 cat <<EOF
@@ -152,7 +164,8 @@ cat <<EOF
 💡 Quick Start Guide:
   1. Initialize a new isolated session:
      $ bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \\
-         --workspace "$TARGET_DIR" --agent claude --role developer --isolate
+         --workspace "$TARGET_DIR" --agent claude --role developer --isolate \\
+         --tmux-server multi-agent-mux
 
   2. Attach to the running session:
      $ tmux -L multi-agent-mux attach -t <session_name>