# 📐 구현 계획서 **Rev.2** — Job `d6f54b7f` (원안: `79ff98ed`)

- **역할**: Planner (`MULTI_AGENT_RULES.md` §1 — 저장소 코드/문서 무수정, 산출물은 본 보고서)
- **기준 커밋**: `14e306b` (branch `refactor`, working tree clean)
- **베이스라인**: `pytest tests/ --collect-only` → **333 collected**
- **입력**: Job `9f85218e` 리뷰 `[VERDICT: PASS WITH CHALLENGE]` (Challenge C-1, Observation C-2)

---

## 0. Rev.1 → Rev.2 변경 요약

| 항목 | 판정 | 조치 |
|---|---|---|
| **Challenge C-1** — T5 문서 가드의 블록 카운팅 오류 + 부분 문자열 허점 | **전면 수용. 두 갈래 모두 실측 확인** | §5 T5 재설계 (§1.10에 실측 근거) |
| **Observation C-2** — `_env_int` 의 `ValueError` 시 `continue` | **수용. 챌린저가 제시한 것보다 근거가 더 강함** | §4.5 S5 변경 + 전용 테스트 T1b 신설 (§1.11) |
| (자체 정정) Rev.1 §5 의 "신설 8건" | **오산 — 실제 7건** | Rev.2 는 8건(C-2 테스트 1건 추가). 기대 collected 341 은 동일하나 근거가 달라짐 |
| (신규) K-5 | — | 문서화되지 않은 `MAM_MIN_COLS` 가 문서화된 `MAM_MIN_PANE_COLS` 보다 **우선순위가 높다** (§9) |

C-1 은 계획대로 구현하면 **테스트가 100% 실패**하는 결함이었습니다. 챌린저의 지적이 정확했고, 실측으로 재현했습니다(§1.10). 다만 챌린저가 제시한 수정안은 **다른 실패 모드를 새로 만듭니다** — 문서 전체를 스캔하므로 산문 속 파일명 언급을 명령으로 오인합니다. 그래서 **커맨드 단위 검증(챌린저의 핵심 교정)** 에 **펜스 스코프(추가 보강)** 를 합성했습니다. §1.10.3 에 두 실패 모드를 각각 실측했습니다.

C-2 는 챌린저가 "다중 fallback 취지에 부합" 정도로 완곡하게 제기했지만, 실측해 보니 **`.mam.env.example` 이 문서화한 유일한 이름이 조용히 무시되는** 경로였습니다. 근거를 강화해 수용합니다(§1.11).

---

## 1. 실측 (Measurements)

> §1.1 ~ §1.9 는 Rev.1 에서 확정된 실측이며 재검증 없이 유지합니다. §1.10 · §1.11 이 Rev.2 신규입니다.

### 1.1 에이전트 해석기가 저장소에 **4개** 존재한다

| # | 위치 | 우선순위 | 실패 시 |
|---|---|---|---|
| **1** | `lib_py/agents/registry.py:26` `agent_of_row()` | `agent` 필드 → 이름 접미사 → `pane.cmd` | `None` |
| **2** | `stop_session.sh:101-109` | 이름 접미사만 (역할 한정) | `exit 2` |
| **3** | `update_yaml_resumed.sh:44-51` | **#2 와 완전 동일한 복사본** | `exit 2` |
| **4** | `run_loop.sh:278` | `agent` 필드 → `pane.cmd` → 하이픈 세그먼트 → **`claude` 기본값** | 실패 없음 |

```
SESSION_NAME                       stop/upd   run_loop   registry
---------------------------------- ---------- ---------- ----------
x-creator-claude                   claude     claude     claude
agy-creator-01                     EXIT2      agy        None      ← 라이브 세션
my-project-dev-claude              EXIT2      claude     claude    ← INSTALL.md 예제 이름
worker-1-agy                       EXIT2      agy        agy
foo-cline                          EXIT2      cline      cline
bad-session-name                   EXIT2      claude     None      ← run_loop 은 조용히 claude
orc-hermes-main                    EXIT2      hermes     None
```

1. **`agy-creator-01` 은 지금 이 워크스페이스에 running 으로 등록된 실제 세션입니다.** `pane.cmd = 'agy'` 가 기록돼 있는데도 `--agent` 없이는 `exit 2` 로 거부됩니다. 브리프가 지목한 결함의 재현 가능한 구체 사례입니다.
2. `my-project-dev-claude` 는 `deploy/INSTALL.md:95` 가 스스로 문서화한 세션 이름입니다. 접미사가 `-dev-claude` 라 #2 의 역할 한정 케이스에 걸리지 않습니다. INSTALL.md 가 `--agent claude` 를 명시해 사고가 안 났을 뿐입니다.
3. `run_loop.sh` 는 해석 실패를 `claude` 로 흡수합니다. 호출 12곳이라 이번 범위 밖(§9 K-1).

라이브 3개 행에 `agent_of_row` 직접 적용:

```
canary-projects-multi-agent-mux-creator-claude     agent_of_row='claude'  match_cmd=False → 'claude'
canary-projects-multi-agent-mux-creator-cline      agent_of_row='cline'   match_cmd=False → 'cline'
agy-creator-01                                     agent_of_row='agy'     match_cmd=False → None
```

`match_cmd=True` 는 docstring 상 **비-입양(non-adoption) 조회**용이고 `stop`/`update_yaml_resumed` 가 정확히 그 경우입니다. (`reconcile.sh` 입양 루프 금지라는 `3aee63cf` §1.2 반증은 유효하며, 이 계획은 `reconcile.sh` 를 건드리지 않습니다.)

### 1.2 `agent` 필드는 존재하지 않는다

```
row keys 합집합:
['agy_conversation_id_own', 'attach_command', 'child_pid', 'claude_session_id_own',
 'cline_conversation_id_own', 'delegate_job_id', 'herdr_server', 'herdr_session',
 'herdr_session_created_at', 'herdr_session_epoch', 'kill_command',
 'last_visible_status', 'last_visible_status_at_termination', 'mcp_attachments',
 'name', 'pane', 'role', 'start_command', 'status', 'tui']
```

3개 행 전부 `agent=None`, `pane.cmd` 는 3개 전부 채워짐. → `agent` 필드를 **쓰는** 코드는 추가하지 않고, 우선순위 ①은 테스트로만 고정합니다(T4b).

### 1.3 `load_state_json` 은 YAML 이 아니라 SQLite 를 읽는다

`lib.sh:938-978` — `.db` 우선, 없을 때만 `.yaml`. 라이브에 `.mam/agent-sessions.db`(40 KiB) 존재. 문서·커밋 메시지에서 "레지스트리" 로 표현합니다.

### 1.4 비용

| 항목 | 실측 |
|---|---|
| `load_state_json` 1회 | ~34 ms |
| `python3` 기동 + `import lib_py.agents.registry` | ~27 ms |
| `stop_session.sh` 가 이미 수행하는 `load_state_json` | **2회** (`:97`, `:113`) |

`PYTHONPATH` 는 `lib.sh:25` 가 export 하므로 맨 `python3` 로 임포트 가능. venv 없는 시스템 파이썬(3.9.6)에서 `env -i` 검증 완료. `registry` 는 서드파티 의존 없음(`yaml` 불필요 — 상태는 JSON 으로 env 전달).

### 1.5 J-1 재현

페이로드: 1패널 `width=50, height=30`

| 경로 | 결과 |
|---|---|
| `--min-cols 0` | `right` / `single_pane_height_constrained` |
| `MAM_MIN_PANE_COLS=0` | **`overflow`** |
| `MAM_MIN_COLS=0` | **`overflow`** |
| `--min-rows 0` | `down` |
| `MAM_MIN_PANE_ROWS=0` | **`overflow`** |
| **대조군** `--min-cols 25` vs `MAM_MIN_PANE_COLS=25` | **양쪽 동일** (`right`) |

대조군이 결함을 `or` 관용구의 falsy-zero 하나로 국소화합니다.

### 1.6 J-2 임계값

```
n=3 n//2=1 -> down      ← 현행 d3 단언. 상한 검사 도달 불가
n=4 n//2=2 -> overflow
n=5 n//2=2 -> down      ← 판별 가능한 최소 홀수
n=6 n//2=3 -> overflow
n=7 n//2=3 -> down
```

### 1.7 문서 실태

| 파일 | 현상 |
|---|---|
| `multi-agent-mux-stop/SKILL.md` | `--agent` **0회**. 워크플로 예제 3개(`:68, :72, :77`) 전부 생략 |
| `deploy/INSTALL.md:94, :98` | `--agent claude` **이미 명시** — 유일한 모범 사례 |
| `multi-agent-mux-create/SKILL.md:146` | `AGENT=claude  # or agy` |
| `multi-agent-mux-create/SKILL.md:171` | `must be claude or agy` — 실물 `create_session.sh:86` 은 4종을 받음 |
| `multi-agent-mux-resume/SKILL.md:61` | `# or agy or hermes` (cline 누락) |
| `create_session.sh:4`, `resolve_session_id.sh:4` | 헤더 주석 `<claude\|agy>` |
| `update_yaml_resumed.sh:7, :14` | `[--agent claude\|agy]` |

`create_session.sh` 는 이미 `--agent` 필수 + 4종 검증(`:83`, `:85-86`). create 쪽은 **문서 동기화뿐**입니다.

### 1.8 기존 테스트 계약

| 테스트 | 세션명 | 현행 |
|---|---|---|
| `tests/test_tier1_unit.py:142` | `bad-session-name` | rc=2, `cannot infer agent` |
| `tests/test_tier3_integration.py:398` | `bad-name` | rc=2, `cannot infer agent` |

두 이름 모두 샌드박스 레지스트리(`herdr_sessions: []`)에 없습니다. §3 설계 결정을 지배합니다.

### 1.9 (부수) `cd … 2>/dev/null || pwd` 결함

```
line35 result: [/lib.sh]        → 존재하지 않음, 항상 :36 폴백
correct form : [/Users/.../.agents/skills/lib.sh]
```

잔존: `stop_session.sh:35`, `create_session.sh:23`, `resume_session.sh:6`. (`update_yaml_resumed.sh:10` 은 이미 정상.) `31b2d70` 의 R-2 와 동일 결함. 1차 소싱 경로가 100% 죽어 `${WORKSPACE_ROOT:-$PWD}` 폴백에만 의존합니다.

---

### 1.10 **[Rev.2 신규] Challenge C-1 검증**

#### 1.10.1 갈래 ① — `checked == 2` 로 단언이 실패한다 → **확인**

Rev.1 T5 의 블록 단위 정규식을 현재 문서에 그대로 적용:

```
SKILL.md:   total fenced bash/sh blocks=3, containing stop_session.sh=1
   -> one block holds 3 stop_session.sh invocations; '--agent' present in block: False
INSTALL.md: total fenced bash/sh blocks=7, containing stop_session.sh=1
   -> one block holds 2 stop_session.sh invocations; '--agent' present in block: True
CHECKED = 2   (planner asserted >= 4)
```

`assert checked >= 4` 는 **결정론적으로 실패**합니다. 챌린저의 지적이 정확합니다. 제가 §1.7 에서 "예제 3개(`:68, :72, :77`)" 를 세면서도 그것이 **하나의 펜스 안에 들어 있다**는 사실을 확인하지 않은 것이 원인입니다 — 개수는 셌지만 **경계를 세지 않았습니다**.

#### 1.10.2 갈래 ② — 블록 단위 단언의 위양성(False Positive) → **확인**

INSTALL.md 사본에서 **두 호출 중 하나에서만** `--agent` 를 제거하는 뮤테이션:

```
mutation applied (agent count 2 -> 1)
설계 A (블록 단위, Rev.1 원안):     blocks=1  all pass? True    ← 뮤테이션 미검출
설계 C (펜스+커맨드, Rev.2 정제안): checked=2 missing=1        ← 뮤테이션 검출
```

블록에 `--agent` 가 **한 번이라도** 나오면 통과합니다. 회귀를 못 잡는 가드는 가드가 아니라 주석입니다. 챌린저의 지적이 정확합니다.

#### 1.10.3 챌린저 수정안의 잔여 실패 모드 → **문서 전체 스캔이 산문을 명령으로 오인한다**

챌린저 수정안은 `doc.read_text()` **전체**에 커맨드 정규식을 돌립니다. 산문 속 파일명 언급이 있는 문서로 실측:

```
=== 챌린저 수정안 (문서 전체 스캔) ===
  [1] --agent=NO  | '`stop_session.sh` does not delete report trees.'          ← 위양성
  [2] --agent=NO  | '`stop_session.sh --purge-conversation` note below.'       ← 위양성
  [3] --agent=YES | 'bash .../stop_session.sh --session "$S" --agent "$A"'
  [4] --agent=NO  | 'bash .../stop_session.sh --session "$S"'

=== 펜스 스코프 + 커맨드 단위 (Rev.2) ===
  [1] --agent=YES | 'bash .../stop_session.sh --session "$S" --agent "$A"'
  [2] --agent=NO  | 'bash .../stop_session.sh --session "$S"'
  checked=2
```

산문 두 줄이 각각 `checked += 1` 되고 `--agent` 가 없으므로 **테스트가 실패**합니다. 이것이 가설이 아니라 임박한 문제인 이유:

- 이 계획 **§4.4 자체가 stop/SKILL.md 에 산문 문단을 추가**합니다.
- `stop/SKILL.md` 의 `## Pitfalls` · `## When NOT to use` 절은 성격상 스크립트를 산문으로 언급하게 되는 자리입니다.
- 문장을 하나 썼다고 실패하는 가드는 다음 사람이 **지웁니다**.

현재 두 문서에는 펜스 밖 언급이 0건이라(SKILL.md 3회·INSTALL.md 2회 모두 펜스 안) 챌린저 수정안도 **지금은** 통과합니다. 하지만 가드의 존재 이유는 미래의 편집을 견디는 것이므로, 지금 통과하는 것만으로는 부족합니다.

#### 1.10.4 정제안 검증 — 계획 §4.4 적용 후

`§4.4` 대로 편집한 사본(3개 예제에 `--agent "$AGENT"` 추가 + `stop_session.sh` 문자열을 포함하지 않는 산문 문단 추가)에 정제안 적용:

```
SKILL.md     checked=3  missing_agent=0
INSTALL.md   checked=2  missing_agent=0
```

총 5건, 전건 통과. 펜스 스코프 덕분에 **"산문에 파일명을 쓰지 말라"는 제약이 계획에서 사라집니다** — 이것이 챌린저 수정안 대비 실질 이득입니다.

### 1.11 **[Rev.2 신규] Observation C-2 검증 — 근거는 챌린저가 제시한 것보다 강하다**

#### 1.11.1 어느 이름이 정본인가

```
.mam.env.example:133   # MAM_MIN_PANE_COLS=60
.mam.env.example:137   # MAM_MIN_PANE_ROWS=20
.mam.env.example:143   # MAM_MAX_PANE_COLS=3
lib.sh:432             --min-cols "${MAM_MIN_PANE_COLS:-60}" --min-rows "${MAM_MIN_PANE_ROWS:-20}"
test_herdr_shim_contract.py:100-101   export MAM_MIN_PANE_COLS=60 / MAM_MIN_PANE_ROWS=20
```

`MAM_MIN_COLS` / `MAM_MIN_ROWS` / `MAM_MAX_COLS` 단축형은 **`layout.py:191-193` 안에서만** 등장합니다. 생산 코드·문서·템플릿·테스트 어디에도 없습니다. `report-8f0cb35f.md:72` 는 정리 작업 당시 *"no legacy `MAM_MIN_COLS=`/`MAM_MIN_ROWS=` env-prefix style"* 을 확인 사항으로 적고 있습니다 — 단축형은 **레거시 별칭**입니다.

그런데 `_env_int("MAM_MIN_COLS", "MAM_MIN_PANE_COLS")` 는 **레거시 단축형을 먼저** 봅니다.

#### 1.11.2 결과: 문서화된 유일한 이름이 조용히 무시된다

```
env                                                현행 or 60   return default   continue
{}                                                        60               60         60
{'MAM_MIN_PANE_COLS': '0'}                                60                0          0
{'MAM_MIN_PANE_COLS': '25'}                               25               25         25
{'MAM_MIN_COLS': 'foo'}                                   60               60         60
{'MAM_MIN_COLS': '',    'MAM_MIN_PANE_COLS': '25'}        25               25         25
{'MAM_MIN_COLS': 'foo', 'MAM_MIN_PANE_COLS': '25'}        60               60         25  ← 차이
{'MAM_MIN_COLS': 'foo', 'MAM_MIN_PANE_COLS': 'bar'}       60               60         60
{'MAM_MIN_COLS': 'foo', 'MAM_MIN_PANE_COLS': '0'}         60               60          0  ← 차이
```

읽어야 할 두 가지:

1. **`""` 와 `"foo"` 가 다르게 취급됩니다.** 빈 문자열은 다음 후보로 넘어가고(`if raw:` 가 걸러냄), 무효 문자열은 즉시 탈출합니다. 둘 다 "쓸 수 없는 값"인데 처리가 정반대입니다. `continue` 는 이 비대칭을 없앱니다.
2. 차이가 나는 두 행에서 무시되는 값은 **`.mam.env.example` 이 문서화한 바로 그 변수**입니다. 운영자가 템플릿대로 `MAM_MIN_PANE_COLS=25` 를 설정했는데, 셸 어딘가에 남은 `MAM_MIN_COLS=foo` 하나 때문에 60 이 적용됩니다.

3. **차이는 정확히 2행뿐입니다.** 나머지 7행은 세 구현이 완전히 일치합니다. 즉 `continue` 는 J-1 수정과 직교하고, 행동 변경 표면이 "첫 후보 무효 + 후속 후보 유효" 라는 한 조건으로 좁혀집니다. 테스트 1건으로 완전히 고정할 수 있습니다(T1b).

**결론: C-2 수용.** 챌린저는 "다중 fallback 취지에 부합" 이라는 설계 논거로 제기했는데, 실측하면 **문서화된 설정이 무시되는 실동작 결함**이라 근거가 더 강합니다. Rev.1 이 `return default` 를 고른 이유는 "오타 입력에 대한 행동 동등성 보존" 이었고 그 목표 자체는 유효하지만, 위 표의 5·7행이 보여주듯 **`continue` 도 그 목표를 똑같이 만족**합니다(모든 후보가 무효면 `default`). Rev.1 은 더 좁은 불변식을 지키느라 더 나은 것을 놓쳤습니다.

---

## 2. 범위

**포함**

| # | 항목 |
|---|---|
| S1 | `lib.sh` 에 `resolve_agent_type_from_registry()` 공용 헬퍼 신설 |
| S2 | `stop_session.sh` 폴백을 S1 로 교체 + 헤더/`usage()` 갱신 |
| S3 | `update_yaml_resumed.sh` 의 동일 복사본을 S1 로 교체 + 헤더/`usage()` 갱신 |
| S4 | `stop`/`resume`/`create` SKILL.md 및 3개 스크립트 헤더 주석 문서 동기화 |
| S5 | J-1: `_env_int(*names, default=None)` 리팩터(+ **C-2 `continue`**) 및 `main()` 배선 |
| S6 | 회귀 테스트 **8건** 신설 + 기존 J-2 가드 1건 보강 |
| S7 | `IMPROVEMENTS.md` 백로그 등록 및 완료 카운트 갱신 |
| S8 | (분리 커밋) §1.9 `cd … && pwd` 3곳 |

**제외**

| 항목 | 제외 사유 |
|---|---|
| `run_loop.sh:278` 통합 | 호출 12곳 + `claude` 기본값 제거는 행동 변경 → K-1 |
| `reconcile.sh` 해석 경로 | `3aee63cf` §1.2 실측 반증 유효 |
| `agent_of_row` 세그먼트 매칭 | `reconcile.sh` 입양 판정에 영향 → K-4 |
| `max_columns` falsy-zero | 브리프가 min-cols/min-rows 만 지목 → K-2 |
| **`_env_int` 후보 순서 뒤집기** | 문서화된 `MAM_MIN_PANE_COLS` 를 앞으로 옮기는 것은 **우선순위 변경**이라 C-2 (무효값 건너뛰기)와 별개 사안 → **K-5** |
| 레지스트리에 `agent` 필드 쓰기 | 쓰는 코드가 0건이고 요구되지 않음 |

---

## 3. 설계 결정 — 폴백을 **어디에** 넣는가 (Rev.1 유지)

`stop_session.sh` 현재 순서:

```
:88   --session 검사                       → exit 2
:89   YAML 파일 존재 검사                   → exit 1
:97   resolve_herdr_workspace              (load_state_json #1)
:101  AGENT 접미사 추론                     → exit 2  ← 교체 대상
:113  MAPPED_DATA: row 조회                (load_state_json #2)
:124  row 없음                             → exit 1
:152  AGENT 최초 사용
```

**안 A (기각)** — `:113` 블록에 병합. 프로세스 1개 절약, 코드도 가장 깔끔. **기각 사유**: 해석이 row 조회 뒤로 밀려 "미등록 + 이름 해석 실패" 세션의 종료 코드가 **2 → 1** 로 바뀝니다. §1.8 의 두 테스트가 깨지고 헤더 `:28-30` 의 계약도 바뀝니다. 얻는 것은 34 ms 뿐입니다.

**안 B (채택)** — `:101` 자리를 그대로 두고 해석기만 교체.

| 성질 | 결과 |
|---|---|
| 종료 코드 계약 | **불변** (`exit 2`, 동일 메시지) |
| §1.8 기존 테스트 2건 | **수정 불필요** |
| `agy-creator-01` | `EXIT2` → `agy` ✅ |
| `my-project-dev-claude`, `foo-cline`, `worker-1-agy` | `EXIT2` → 정상 해석 ✅ |
| 미래의 `agent` 명시 필드 | 자동 지원 ✅ |
| 비용 | `--agent` 생략 시에만 `load_state_json` 1회 (~34 ms) |

`set -euo pipefail` 주의: 실패 가능한 명령 치환을 대입에 쓰므로 반드시 `|| AGENT=""` 로 감쌉니다(`test_lib_sh_layout_split_in_set_e_subshell` 선례). `stderr` 는 억제하지 않습니다 — 정상 해석 실패는 `sys.exit(1)` 이라 무출력이고, `PYTHONPATH` 파손 같은 진짜 오류의 traceback 은 보여야 합니다. 기존 테스트는 부분 문자열 단언이라 traceback 이 섞여도 무영향입니다.

---

## 4. 구현

### 4.1 S1 — `lib.sh` 공용 헬퍼

`resolve_herdr_session()`(`:989`) 바로 앞에 추가.

```bash
# resolve_agent_type_from_registry <session_name>
#
# 레지스트리(YAML/DB)에 기록된 사실로 에이전트 종류를 해석한다. 우선순위는
# lib_py.agents.registry.agent_of_row 의 계약을 그대로 따른다:
#   ① row['agent'] 명시 필드
#   ② 세션명 접미사 (*-{creator,planner,reviewer}-<agent> 및 *-<agent>)
#   ③ pane.cmd (정확히 일치하거나 .../<agent> 바이너리 경로)
# 성공하면 에이전트명을 stdout 에 출력하고 0 을, 셋 다 실패하면 아무것도
# 출력하지 않고 1 을 반환한다. 오류 메시지는 호출자가 소유한다 — 각 스크립트가
# 문서화한 종료 코드를 그대로 유지하기 위해서다.
#
# NOTE: agent_of_row 의 match_cmd=True 는 "비-입양 조회" 계약이다. reconcile.sh
#       입양 루프는 이 헬퍼를 쓰면 안 된다 (3aee63cf §1.2 실측 반증).
resolve_agent_type_from_registry() {
  local name="$1"
  MAM_STATE_JSON="$(load_state_json)" SESSION_NAME="$name" python3 -c "
import os, json, sys
from lib_py.agents.registry import agent_of_row
name = os.environ['SESSION_NAME']
d = json.loads(os.environ.get('MAM_STATE_JSON', '{}'))
row = next((s for s in d.get('herdr_sessions', []) if s.get('name') == name), {})
resolved = agent_of_row(row, session_name=name)
if not resolved:
    sys.exit(1)
print(resolved)
"
}
```

**이름을 `resolve_agent_type` 로 하지 않는 이유**: `run_loop.sh:278` 이 동명 함수를 정의하며 `lib.sh` 를 source 합니다. 동명이면 run_loop 의 나중 정의가 조용히 덮어써서 12개 호출 지점이 어느 구현을 쓰는지 읽어서는 알 수 없게 됩니다.

### 4.2 S2 — `stop_session.sh`

`:100-109` 교체:

```bash
# --agent 미지정 시 레지스트리 기록으로 해석 (B-21).
# ① row['agent'] → ② 세션명 접미사 → ③ pane.cmd 순. 셋 다 실패하면
# 종전과 동일하게 exit 2 (헤더 :27-30 의 종료 코드 계약 유지).
if [ -z "$AGENT" ]; then
  AGENT="$(resolve_agent_type_from_registry "$SESSION_NAME")" || AGENT=""
  [ -n "$AGENT" ] || {
    echo "ERROR: cannot infer agent from '$SESSION_NAME'; pass --agent" >&2
    exit 2
  }
fi
```

헤더 `:15-16`:

```
#   --agent <type>          — claude | agy | hermes | cline
#                             (권장: 항상 명시. 미지정 시 레지스트리 기록으로
#                              해석 — agent 필드 → 세션명 접미사 → pane.cmd;
#                              셋 다 실패하면 exit 2)
```

`usage()` `:46-47`:

```
  --agent <type>       — claude | agy | hermes | cline (recommended: always pass it)
                         (falls back to the registry record: agent field ->
                          session-name suffix -> pane.cmd)
```

`usage()` 에 4개 에이전트명이 모두 남아야 합니다 — `test_comp_stop_usage_matches_parser`(`test_tier2_component.py:711-712`)가 단언합니다.

### 4.3 S3 — `update_yaml_resumed.sh`

`:43-52` 를 S2 와 동일한 블록으로 교체(메시지·종료 코드 동일). 헤더 `:7` / `usage()` `:14` 의 `[--agent claude|agy]` → `[--agent claude|agy|hermes|cline]`. `:10` 은 이미 올바른 소싱 형태이므로 손대지 않습니다.

### 4.4 S4 — 문서 동기화

**`multi-agent-mux-stop/SKILL.md`**

Pre-flight(`:38-40`):

```bash
SESSION_NAME=<workspace>-creator-<agent>  # convention
AGENT=claude                              # claude | agy | hermes | cline — always pass it
AGENT_SESSIONS_YAML=.mam/agent-sessions.yaml
```

워크플로 예제 3개(`:68, :72, :77`)에 `--agent "$AGENT"` 추가:

```bash
# 1. Stop gracefully (default — captures ID, shuts down safely, status=stopped)
bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
  --session "$SESSION_NAME" --agent "$AGENT"
```

"Idempotency" 문단(`:81`) 아래에 추가:

```markdown
**`--agent` is the standard.** Pass it on every invocation. If omitted, the script
resolves the agent from the registry record — the row's `agent` field, then the
session-name suffix, then `pane.cmd` — and exits 2 if none of the three resolve.
The fallback exists for recovery, not as the normal calling convention: a session
whose name carries no agent suffix (e.g. `agy-creator-01`) is only resolvable
while its registry row survives.
```

> **Rev.1 에 있던 제약 삭제.** Rev.1 은 이 산문에 `stop_session.sh` 문자열을 쓰지 말라는 제약을 걸어야 했습니다. Rev.2 의 T5 가 펜스 스코프이므로 **그 제약이 필요 없습니다**(§1.10.3~4). 산문을 자유롭게 쓰십시오.

**`multi-agent-mux-resume/SKILL.md:61`** — `AGENT=claude  # or agy or hermes` → `AGENT=claude  # claude | agy | hermes | cline — pass it explicitly`

**`multi-agent-mux-create/SKILL.md`**
- `:146` 동일 수정
- `:171` — 실물 `create_session.sh:86` 과 동일한 `claude, agy, hermes or cline` 문구로. 같은 `case`(`:158-172`)에 `hermes`/`cline` arm 이 없으므로, **스니펫을 축약하고 실물 스크립트를 가리키게 하는 쪽을 권장**합니다. SKILL.md 스니펫이 실물과 갈라지는 것 자체가 이번에 고치는 결함군입니다.

**스크립트 헤더 주석** — `create_session.sh:4`, `resolve_session_id.sh:4` 의 `--agent <claude|agy>` → `<claude|agy|hermes|cline>`

### 4.5 S5 — J-1 (+ C-2)

`layout.py:175-186`:

```python
def _env_int(*names: str, default: Optional[int] = None) -> Optional[int]:
    """First *valid* int among the env vars in *names*, else `default`.

    `default` is an explicit parameter rather than an `or` at the call site so a
    legitimate 0 survives (MAM_MIN_PANE_COLS=0 means 0, not the 60 default).

    An unparsable value is skipped rather than raised or treated as terminal: a
    typo in an operator's shell must not take the whole layout call down (lib.sh
    would silently fall back to 'right'), and must not shadow a later candidate
    that IS set correctly -- MAM_MIN_COLS is a legacy alias while
    MAM_MIN_PANE_COLS is the name .mam.env.example documents, so aborting on the
    first bad value would discard the documented setting. Empty values already
    fell through; this makes invalid values behave the same way.
    """
    for n in names:
        raw = os.environ.get(n, "").strip()
        if raw:
            try:
                return int(raw)
            except ValueError:
                continue
    return default
```

`main()` `:191-193`:

```python
    parser.add_argument("--min-cols", type=int, default=_env_int("MAM_MIN_COLS", "MAM_MIN_PANE_COLS", default=60))
    parser.add_argument("--min-rows", type=int, default=_env_int("MAM_MIN_ROWS", "MAM_MIN_PANE_ROWS", default=20))
    parser.add_argument("--max-cols", type=int, default=_env_int("MAM_MAX_COLS", "MAM_MAX_PANE_COLS"))
```

`--max-cols` 는 `default=None` 이 의도된 의미(미지정 = 상한 없음)이므로 그대로 둡니다.

**`return default` 가 아니라 `continue` 여야 하는 이유(불변식 확인)**: 모든 후보가 없거나 무효이면 루프가 끝나 `return default` 에 도달합니다. 즉 Rev.1 이 지키려던 "오타 입력은 문서화된 기본값으로 흡수된다"는 성질은 **그대로 유지**되며(§1.11.2 표 4·7행), 달라지는 것은 "첫 후보 무효 + 후속 후보 유효" 한 조건뿐입니다. `min_cols=None` 으로 `compute_2xk_layout` 에 들어가 `TypeError` 가 나는 경로는 두 안 모두에서 발생하지 않습니다.

`*names` 뒤의 키워드 전용 `default` 는 Python 3.9 에서 유효합니다(시스템 인터프리터 3.9.6 실측). `_env_int` 호출자는 `main()` 3곳뿐입니다.

---

## 5. 테스트 계획

신설 **8건**, 기존 가드 보강 **1건**. 예상 collected: **333 → 341**.

> **Rev.1 자체 정정**: Rev.1 은 "신설 8건 → 341" 이라고 적었으나 실제 열거는 7건이었습니다(T1 3 + T3 1 + T4 2 + T5 1). Rev.2 는 C-2 전용 테스트 T1b 를 더해 실제로 8건이 되며, 341 이라는 수치가 비로소 맞아떨어집니다.

### T1 — J-1 env/flag 등가성 (`tests/test_layout.py`, 3건)

```python
_LAYOUT_ENV_VARS = ("MAM_MIN_COLS", "MAM_MIN_PANE_COLS", "MAM_MIN_ROWS",
                    "MAM_MIN_PANE_ROWS", "MAM_MAX_COLS", "MAM_MAX_PANE_COLS")

def _run_layout(payload, args=(), env_extra=None):
    env = {**os.environ, "PYTHONPATH": os.path.abspath(".agents/skills")}
    for k in _LAYOUT_ENV_VARS:
        env.pop(k, None)          # 호출자 셸의 오염 차단
    env.update(env_extra or {})
    res = subprocess.run([sys.executable, "-m", "lib_py.layout", "--json", *args],
                         input=json.dumps(payload), capture_output=True, text=True, env=env)
    assert res.returncode == 0, res.stderr
    return json.loads(res.stdout)

# height//2 = 15 < min_rows(20) 로 제약 분기 진입, width//2 = 25 가 min_cols 와 비교됨.
_ZERO_TRAP = {"result": {"panes": [
    {"pane_id": "p1", "rect": {"x": 0, "y": 0, "width": 50, "height": 30}}]}}


def test_j1_env_zero_min_cols_matches_flag_zero():
    """J-1: MAM_MIN_PANE_COLS=0 must mean 0, not fall through to the 60 default."""
    flag = _run_layout(_ZERO_TRAP, ("--min-cols", "0"))
    assert flag["direction"] == "right" and flag["reason"] == "single_pane_height_constrained"
    for var in ("MAM_MIN_COLS", "MAM_MIN_PANE_COLS"):
        assert _run_layout(_ZERO_TRAP, (), {var: "0"}) == flag, var


def test_j1_env_zero_min_rows_matches_flag_zero():
    flag = _run_layout(_ZERO_TRAP, ("--min-rows", "0"))
    assert flag["direction"] == "down" and flag["reason"] == "single_pane_split_down"
    for var in ("MAM_MIN_ROWS", "MAM_MIN_PANE_ROWS"):
        assert _run_layout(_ZERO_TRAP, (), {var: "0"}) == flag, var


def test_j1_nonzero_and_malformed_env_behaviour_unchanged():
    """Behaviour neutrality: non-zero env still applies, and a lone typo still
    lands on the documented default instead of crashing on a None comparison."""
    assert _run_layout(_ZERO_TRAP, (), {"MAM_MIN_PANE_COLS": "25"}) == \
           _run_layout(_ZERO_TRAP, ("--min-cols", "25"))
    assert _run_layout(_ZERO_TRAP, (), {"MAM_MIN_PANE_COLS": "abc"}) == _run_layout(_ZERO_TRAP)
```

### T1b — **[Rev.2 신규]** C-2: 무효값이 뒤 후보를 가리지 않는다 (1건)

```python
def test_j1b_invalid_alias_does_not_shadow_the_documented_var():
    """C-2: MAM_MIN_COLS is a legacy alias checked first; MAM_MIN_PANE_COLS is the
    name .mam.env.example documents. An unparsable value in the alias must be
    skipped, not abort the search and discard the documented setting.

    Empty values already fell through (`if raw:`); this makes invalid values
    behave the same way. When every candidate is unusable, `default` still wins.
    """
    good = _run_layout(_ZERO_TRAP, (), {"MAM_MIN_PANE_COLS": "25"})
    assert good["direction"] == "right"
    # 별칭이 깨져 있어도 문서화된 변수가 적용된다
    assert _run_layout(_ZERO_TRAP, (), {"MAM_MIN_COLS": "foo",
                                        "MAM_MIN_PANE_COLS": "25"}) == good
    # 0 도 마찬가지 (J-1 과의 상호작용)
    assert _run_layout(_ZERO_TRAP, (), {"MAM_MIN_COLS": "foo",
                                        "MAM_MIN_PANE_COLS": "0"}) == \
           _run_layout(_ZERO_TRAP, ("--min-cols", "0"))
    # 모든 후보가 무효면 문서화된 기본값으로 흡수 (Rev.1 불변식 보존)
    assert _run_layout(_ZERO_TRAP, (), {"MAM_MIN_COLS": "foo",
                                        "MAM_MIN_PANE_COLS": "bar"}) == _run_layout(_ZERO_TRAP)
```

마지막 단언이 중요합니다 — `continue` 로 바꾸면서 Rev.1 이 지키려던 성질이 깨지지 않았음을 같은 테스트 안에서 못 박습니다.

### T2 — J-2 임계값 보강 (기존 `test_headless_max_columns_growth_guard` 확장, 신설 0건)

```python
    # n=5 is the first odd n that can discriminate: n//2 == 2 == max_columns, so an
    # over-correction that also checked the cap on the odd branch would return
    # overflow here. n=3 has n//2 == 1 and cannot reach the check at all.
    d5 = compute_2xk_layout(headless(5), max_columns=2)
    assert d5.direction == "down" and not d5.is_overflow
    assert d5.reason == "headless_odd_down"
```

계획 `5e4ef463` 의 뮤테이션 M6 사양 오류(제가 `n=3` 을 골랐고 그 값으로는 판별 불가)를 닫습니다.

### T3 — `agent_of_row` 단위 보강 (`tests/test_a4_adapter_contract.py`, 1건)

```python
def test_agent_of_row_pane_cmd_binary_path_and_failure():
    # pane.cmd 가 절대 경로 형태여도 해석된다
    assert agent_of_row({'pane': {'cmd': '/usr/local/bin/agy'}}) == 'agy'
    # 세 경로 모두 실패하면 None — 호출자가 오류를 소유한다
    assert agent_of_row({}, session_name='bad-session-name') is None
    # 입양 조회용 match_cmd=False 에서는 pane.cmd 를 보지 않는다
    assert agent_of_row({'name': 'agy-creator-01', 'pane': {'cmd': 'agy'}},
                        match_cmd=False) is None
```

### T4 — `stop_session.sh` 폴백 (`tests/test_tier2_component.py`, 2건)

기존 `test_comp_stop_sqlite_state_update` 의 `run_mutation` 패턴 사용(herdr 부재 → "herdr already dead, just updating YAML" 경로로 rc=0 완주, 실제 세션 미영향).

```python
def test_comp_stop_agent_fallback_reads_pane_cmd(mam_sandbox):
    """B-21: --agent 생략 시 세션명에 에이전트 접미사가 없어도 레지스트리 행의
    pane.cmd 로 해석된다 (라이브 `agy-creator-01` 형태)."""
    mutation = """
d['herdr_sessions'] = [{
    'name': 'agy-creator-01',
    'status': 'running',
    'pane': {'cwd': 'WS_PLACEHOLDER', 'cmd': 'agy'}
}]
""".replace("WS_PLACEHOLDER", str(mam_sandbox))
    run_mutation(mam_sandbox, mutation)
    script = mam_sandbox / ".agents" / "skills" / "multi-agent-mux-stop" / "scripts" / "stop_session.sh"
    res = subprocess.run(["bash", str(script), "--session", "agy-creator-01"],
                         capture_output=True, text=True)
    assert res.returncode == 0, res.stderr
    assert re.search(r"^\s*agent:\s+agy\s*$", res.stdout, re.M), res.stdout


def test_comp_stop_agent_fallback_prefers_explicit_agent_field(mam_sandbox):
    """우선순위 계약: 명시 `agent` 필드가 세션명 접미사와 pane.cmd 를 모두 이긴다."""
    mutation = """
d['herdr_sessions'] = [{
    'name': 'x-creator-claude',
    'status': 'running',
    'agent': 'hermes',
    'pane': {'cwd': 'WS_PLACEHOLDER', 'cmd': 'claude'}
}]
""".replace("WS_PLACEHOLDER", str(mam_sandbox))
    run_mutation(mam_sandbox, mutation)
    script = mam_sandbox / ".agents" / "skills" / "multi-agent-mux-stop" / "scripts" / "stop_session.sh"
    res = subprocess.run(["bash", str(script), "--session", "x-creator-claude"],
                         capture_output=True, text=True)
    assert res.returncode == 0, res.stderr
    assert re.search(r"^\s*agent:\s+hermes\s*$", res.stdout, re.M), res.stdout
```

두 번째가 T4 를 "pane.cmd 를 읽는다" 가 아니라 **"`agent_of_row` 계약을 호출한다"** 로 고정합니다. 첫 번째만 있으면 `pane.cmd` 만 직접 읽는 얕은 구현도 통과합니다.

**미해결 계약(exit 2)** 은 이미 `test_tier1_unit.py:142` 와 `test_tier3_integration.py:398` 이 지킵니다. 두 파일을 **수정하지 않은 채 통과하는 것**이 안 B 의 증거이므로 중복 테스트를 추가하지 않습니다.

### T5 — **[Rev.2 재설계]** 문서 가드 (`tests/test_tier2_component.py`, 1건)

Rev.1 원안은 §1.10.1 의 실측대로 `checked == 2` 로 확정 실패하고, §1.10.2 대로 단일 호출 회귀를 놓칩니다. 챌린저의 **커맨드 단위** 교정을 채택하되, §1.10.3 의 산문 위양성을 막기 위해 **펜스 스코프**를 합성합니다.

```python
# 코드 펜스 안의 stop_session.sh 호출을 '명령 단위'로 잘라낸다.
#  - 펜스 스코프: 산문 속 `stop_session.sh` 언급을 명령으로 오인하지 않는다
#    (Pitfalls / When-NOT-to-use 절은 성격상 스크립트를 산문으로 언급한다).
#  - 명령 단위: 한 펜스에 여러 호출이 들어 있어도 각각을 따로 검증한다
#    (블록 단위로 보면 그중 하나만 --agent 를 가져도 통과해 버린다).
_FENCE_RE = re.compile(r"```(?:bash|sh)\n(.*?)```", re.S)
_STOP_CALL_RE = re.compile(r"(?:bash\s+)?\S*stop_session\.sh[^\n\\]*(?:\\\n[^\n\\]*)*")


def test_comp_docs_stop_examples_pass_agent():
    """B-21 문서 계약: 문서의 모든 stop_session.sh 예제는 --agent 를 넘긴다.
    문서 변경은 뮤테이션 감도가 없으므로 이 가드가 표준의 유일한 집행 장치다."""
    repo = Path(__file__).resolve().parent.parent
    expected = {  # 문서별 최소 예제 수 — 예제를 지워 가드를 무력화하는 것을 막는다
        repo / ".agents/skills/multi-agent-mux-stop/SKILL.md": 3,
        repo / "deploy/INSTALL.md": 2,
    }
    for doc, floor in expected.items():
        seen = 0
        for block in _FENCE_RE.findall(doc.read_text()):
            for m in _STOP_CALL_RE.finditer(block):
                snippet = m.group(0)
                seen += 1
                assert "--agent" in snippet, \
                    f"{doc.name}: stop_session.sh example without --agent:\n{snippet}"
        assert seen >= floor, f"{doc.name}: expected >= {floor} examples, saw {seen}"
```

Rev.1/챌린저안 대비 세 가지가 다릅니다.

| | Rev.1 원안 | 챌린저 수정안 | **Rev.2** |
|---|---|---|---|
| 검증 단위 | 코드 블록 | 명령 | 명령 |
| 스캔 범위 | 펜스 | **문서 전체** | 펜스 |
| 개수 하한 | 전역 `>= 4` (**실패**) | 전역 `>= 5` | **문서별** (3 / 2) |

전역 카운트를 문서별로 쪼갠 이유: 전역이면 SKILL.md 예제 1개가 사라져도 INSTALL.md 가 6개면 통과합니다. 문서별 하한은 실패를 발생 지점에 국소화합니다.

**실측 확인** (§1.10.4): §4.4 적용 후 사본에서 `SKILL.md checked=3 missing=0`, `INSTALL.md checked=2 missing=0`.

### T6 — 회귀 무영향 확인

`bash -n`: `lib.sh`, `stop_session.sh`, `update_yaml_resumed.sh`, `create_session.sh`, `resume_session.sh`, `resolve_session_id.sh`.
`py_compile`: `lib_py/layout.py`. 시스템 파이썬 **3.9.6** 임포트 확인.

### 테스트 파일 사전 조건 2건

1. `test_tier2_component.py:296` 의 `FEATURE 3: Stop Session (4 Test Cases)` 주석 개수 갱신(→ 7). 같은 종류의 드리프트를 새로 만들지 않도록.
2. `test_tier2_component.py` 는 `Path` 는 임포트하지만 **`re` 는 임포트하지 않습니다**(`:1-10`). T4/T5 가 `re` 를 쓰므로 `import re` 추가 필요. `test_layout.py` 는 T1/T1b 가 쓰는 `os/json/subprocess/sys` 를 모두 이미 임포트하고 있어 추가 불필요합니다.

---

## 6. 뮤테이션 매트릭스

격리 사본(`rsync`)에 적용해 지정 테스트가 **FAIL** 하는지 확인.

| # | 뮤테이션 | FAIL 해야 하는 테스트 |
|---|---|---|
| M1 | `stop_session.sh` 폴백을 옛 `case` 블록으로 복원 | `test_comp_stop_agent_fallback_reads_pane_cmd` |
| M2 | 헬퍼에서 `agent_of_row(row, …)` → `agent_of_row({}, session_name=name)` | 위 + `…prefers_explicit_agent_field` |
| M3 | 헬퍼에 `match_cmd=False` 추가 | `…reads_pane_cmd` **만** (두 테스트가 서로 다른 성질을 잡음을 증명) |
| M4 | `_env_int(…, default=60)` → `_env_int(…) or 60` | `test_j1_env_zero_min_cols_matches_flag_zero` |
| M5 | `_env_int` 의 `except ValueError: continue` → `return None` | `test_j1_nonzero_and_malformed_env_behaviour_unchanged` (rc≠0) |
| **M5b** | **[Rev.2]** `except ValueError: continue` → `return default` | `test_j1b_invalid_alias_does_not_shadow_the_documented_var` |
| M6 | 헤드리스 홀수 분기에도 `max_columns` 검사 추가 (과잉 교정) | `test_headless_max_columns_growth_guard` (신설 `d5` 단언) |
| M7 | `SKILL.md` 예제 **한 곳**에서 `--agent` 삭제 | `test_comp_docs_stop_examples_pass_agent` |
| **M7b** | **[Rev.2]** `INSTALL.md` 의 **두 호출 중 하나**에서만 `--agent` 삭제 | 동일 (§1.10.2 에서 이미 선실측: Rev.1 설계는 미검출, Rev.2 설계는 `missing=1` 검출) |
| **M7c** | **[Rev.2]** `SKILL.md` 워크플로 예제 1개를 통째로 삭제 | 동일 (`seen >= 3` 하한) |
| M8 | `update_yaml_resumed.sh` 폴백을 옛 `case` 블록으로 복원 | — **가드 없음** |

**M8 을 정직하게 남깁니다.** `update_yaml_resumed.sh` 의 폴백은 유일한 생산 호출자인 `resume_session.sh:66, :129` 가 항상 `--agent "$AGENT"` 를 명시하므로 **그 경로에서 도달 불가**합니다. 직접 호출 시에만 살아납니다. 도달 불가 경로를 위해 별도 픽스처를 세우는 대신 S3 는 "중복 제거"로 정당화하고 가드 없음을 명시합니다. 리뷰어가 이 판단에 이의가 있으면 T4 와 동형의 테스트 추가가 옳은 처방입니다.

**M5 와 M5b 가 서로 다른 테스트를 깨는 것**이 C-2 반영의 검증 조건입니다. M5(=`None` 복귀)는 크래시 경로를, M5b(=Rev.1 안으로 복귀)는 별칭 섀도잉을 각각 잡습니다. 둘 다 잡히지 않으면 T1b 가 의미 없는 테스트라는 뜻입니다.

---

## 7. 커밋 분할

| # | 커밋 | 내용 |
|---|---|---|
| 1 | `feat(lib,stop,resume): resolve --agent from the registry via agent_of_row (B-21)` | S1 + S2 + S3 + T3 + T4 |
| 2 | `docs(skills): standardize explicit --agent across stop/resume/create guides (B-21)` | S4 + T5 |
| 3 | `fix(layout): make _env_int take an explicit default and skip invalid values (J-1)` | S5 + T1 + T1b |
| 4 | `test(layout): cover the headless growth-guard threshold at n=5 (J-2)` | T2 |
| 5 | `docs(improvements): register J-1/J-2/B-21 and refresh the completed count` | S7 |
| 6 | `fix(scripts): repair the dead lib.sh sourcing path in stop/create/resume` | S8 (§1.9) |

커밋 1~4 는 각각 독립 revert 가능합니다. 커밋 6 은 §1.9 가 브리프 범위 밖의 별개 사안이므로 분리합니다 — 리뷰어가 범위 이탈로 판단하면 이 커밋만 드롭하면 됩니다.

커밋 3 의 제목이 Rev.1 에서 바뀌었습니다(`… and skip invalid values` 추가). C-2 가 J-1 과 다른 성질의 변경이므로 제목이 그 사실을 담아야 합니다.

---

## 8. `IMPROVEMENTS.md` 갱신 (S7)

J-1 / J-2 는 현재 `IMPROVEMENTS.md` 에 **등록돼 있지 않습니다**(`55d1a1d9` 리뷰 보고서에만 존재).

**ID 충돌 경고**: `IMPROVEMENTS.md:301` 의 `C-1`("Kanban 문서 29회 언급 vs 실제 구현 0건")과 `:37` 이 참조하는 `C-1`(레이아웃 헤드리스 `max_columns`)은 **서로 다른 두 과제가 같은 ID** 를 씁니다. 신규는 `J-1`/`J-2`/`B-21` 을 씁니다. 기존 충돌은 K-3.

갱신 항목:

1. `:3` 최종 갱신일
2. `:6` 총 추적 미해결 과제 카운트
3. `:7` 완료 과제 **29 → 30** 및 목록에 `B-21` 추가
4. `:37` B-20 후속 정리 줄에 J-1/J-2 해소 한 줄
5. §2 에 `B-21` 절 신설 — 현상(라이브 `agy-creator-01` 이 `--agent` 없이 `exit 2`), 원인(해석기 4중화), 조치, 회귀 가드
6. §6.2 로드맵 표에 완료 행
7. §6.3 파일 소유권 슬롯 표 갱신

---

## 9. 후속 백로그 (이번 범위 밖, 등록만)

| ID | 내용 | 근거 |
|---|---|---|
| **K-1** | `run_loop.sh:278` `resolve_agent_type` 통합 | §1.1 — 해석 실패를 `claude` 로 흡수. cline 세션에 claude 종료키를 보내는 오분류가 구조적으로 가능. 호출 12곳이라 별도 계획 필요 |
| **K-2** | `compute_2xk_layout` 의 `if max_columns and …` falsy-zero | `--max-cols 0`("열 0개")이 "상한 없음"으로 흡수됨. J-1 과 동일 부류 |
| **K-3** | `IMPROVEMENTS.md` 의 `C-1` ID 충돌 정리 | §8 |
| **K-4** | `agent_of_row` 에 하이픈 세그먼트 매칭 추가 여부 | `orc-hermes-main` 류 미해결. `reconcile.sh` 입양 판정 영향 → 실측 선행 |
| **K-5** | **[Rev.2 신규]** `_env_int` 후보 **순서** 재검토 | §1.11.1 — 문서화되지 않은 레거시 `MAM_MIN_COLS` 가 `.mam.env.example` 이 문서화한 `MAM_MIN_PANE_COLS` 보다 **우선**합니다. C-2(무효값 건너뛰기)는 이 순서 문제를 완화할 뿐 해소하지 않습니다. 둘 다 유효한 값이면 여전히 레거시가 이깁니다. 순서 변경은 행동 변경이므로 별도 항목 |

---

## 10. 검증 절차 (Creator 실행)

```bash
# 1) 구문
for f in .agents/skills/lib.sh \
         .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
         .agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh \
         .agents/skills/multi-agent-mux-resume/scripts/resume_session.sh \
         .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh \
         .agents/skills/multi-agent-mux-create/scripts/create_session.sh; do
  bash -n "$f" || echo "FAIL $f"
done
python3 -m py_compile .agents/skills/lib_py/layout.py

# 2) J-1 직접 확인 (0 이 살아남는가)
P='{"result":{"panes":[{"pane_id":"p1","rect":{"x":0,"y":0,"width":50,"height":30}}]}}'
printf '%s' "$P" | PYTHONPATH=.agents/skills MAM_MIN_PANE_COLS=0 python3 -m lib_py.layout --json
printf '%s' "$P" | PYTHONPATH=.agents/skills python3 -m lib_py.layout --json --min-cols 0
#   → 두 출력이 완전히 동일하고 direction=right

# 3) C-2 직접 확인 (무효 별칭이 문서화된 변수를 가리지 않는가)
printf '%s' "$P" | PYTHONPATH=.agents/skills \
  env MAM_MIN_COLS=foo MAM_MIN_PANE_COLS=25 python3 -m lib_py.layout --json
#   → direction=right (수정 전에는 overflow)

# 4) 전체 스위트 (베이스라인 333 → 기대 341)
.venv/bin/python -m pytest tests/ -q

# 5) 배포 신선도 (기존 31건 유지)
.venv/bin/python -m pytest tests/test_deploy_freshness.py -q

# 6) 뮤테이션 M1~M7c (격리 사본에서)
```

**금지 사항**: `tests/test_tier1_unit.py:142` 와 `tests/test_tier3_integration.py:398` 은 **수정하지 않습니다**. 두 건이 무수정으로 PASS 하는 것이 안 B 의 종료 코드 계약 보존을 입증하는 증거입니다. 고쳐야 통과한다면 구현이 안 A 로 흘러간 것이므로 되돌려야 합니다.

**라이브 세션 보호**: T4 는 `mam_sandbox` 안에서만 동작하며 실제 `.mam/agent-sessions.yaml` 을 건드리지 않습니다. 개발 중 `stop_session.sh` 를 실 워크스페이스에서 수동 실행하지 마십시오 — `canary-projects-multi-agent-mux-creator-claude` 가 이 세션입니다.

---

## 11. 규모 추정

| 파일 | 변경 |
|---|---|
| `.agents/skills/lib.sh` | +22 (헬퍼 1개) |
| `stop_session.sh` | +8 / −10, 헤더·usage +6 |
| `update_yaml_resumed.sh` | +8 / −9, 헤더·usage +2 |
| `lib_py/layout.py` | +10 / −6 (docstring 확장 포함) |
| `multi-agent-mux-stop/SKILL.md` | +12 |
| `multi-agent-mux-resume/SKILL.md` | +1 / −1 |
| `multi-agent-mux-create/SKILL.md` | +2 / −2 |
| `create_session.sh` / `resolve_session_id.sh` | 헤더 각 +1 / −1 |
| `tests/test_layout.py` | +62 (T1 45 + T1b 17) |
| `tests/test_a4_adapter_contract.py` | +9 |
| `tests/test_tier2_component.py` | +58 |
| `IMPROVEMENTS.md` | +20 |
| (커밋 6) 3개 스크립트 소싱 줄 | +3 / −3 |

총 **약 +215 / −35 줄**, 파일 12개. 규모 **소~중**.

---

## 12. 챌린저에게

C-1 은 계획대로 짜면 확정 실패하는 결함이었고, 두 갈래 모두 정확했습니다. 특히 갈래 ②(부분 문자열 위양성)는 **테스트가 통과하기 때문에 아무도 눈치채지 못하는** 종류라 더 값어치가 있습니다. §1.10.2 에서 뮤테이션으로 재현했습니다.

수정안을 그대로 채택하지 않은 부분은 한 곳입니다 — 문서 전체 스캔이 산문 속 파일명 언급을 명령으로 오인합니다(§1.10.3, 위양성 2건 실측). 이 계획 §4.4 자체가 SKILL.md 에 산문을 추가하므로 임박한 문제였습니다. 커맨드 단위라는 **핵심 교정은 그대로 채택**하고 펜스 스코프를 얹었습니다.

C-2 는 제기하신 근거(다중 fallback 취지)보다 강한 근거가 실측에서 나왔습니다. `MAM_MIN_COLS` 는 `layout.py` 밖 어디에도 없는 레거시 별칭이고, 가려지는 `MAM_MIN_PANE_COLS` 는 `.mam.env.example` 이 문서화한 **유일한** 이름입니다. 게다가 현행 코드는 `""` 는 건너뛰고 `"foo"` 는 탈출하는 비대칭을 갖고 있습니다. 수용하고 전용 테스트 T1b 를 신설했습니다.