# 구현 계획서 (Refined v4): MAM 세션 생성 · UUID 추출 · 다단계 무결성 검증 아키텍처

> 본 문서는 Reviewer의 코드 리뷰 피드백(대상: Job `03ae0809`가 리뷰한 구현 diff, 이 계획서의 v3, 원본은 `9bde0402`→`de45d5e0`→`fd0b8737`)을 반영해 정교화한 버전이다. v3 대비 변경점은 0장에 요약한다.

## 0. Reviewer 피드백 반영 변경 이력 (v3 → v4)

| # | Reviewer 지적 사항 | 판정 | v4 조치 |
|---|---|---|---|
| 1 | (치명적) `resume_session.sh --dry-run`이 `reconcile.sh`의 `atomic_dump_yaml` 트랜잭션(`BEGIN IMMEDIATE` 배타 락 보유 중) 내부에서 서브프로세스로 호출되는데, `resume_session.sh`의 "herdr 이미 생존" 분기(2단계)는 `--dry-run`으로 전혀 게이트되지 않고 `update_yaml_resumed.sh` → `atomic_dump_yaml`을 통해 **같은 DB에 또 다른 배타 락**을 시도 — 자기 자신과의 락 경합으로 매번 ~60초 스톨 후 실패, 게다가 herdr가 살아있는 정상 케이스(주 사용 경로)에서 항상 발생 | **타당함, 전면 수용** — v2(`de45d5e0`)가 "resume_session.sh --dry-run을 서브프로세스로 호출"을 설계할 때 그 호출 지점이 이미 같은 DB에 락을 쥐고 있는 트랜잭션 내부라는 사실을 반영하지 못한 설계 공백으로 인정 | 2.3장을 전면 재작성: `resume_session.sh --dry-run`을 **어떤 분기에서도 절대 쓰기를 수행하지 않도록** 원칙을 명문화(2.3.4). 구체적으로 "herdr 이미 생존" 분기도 `DRY_RUN` 체크를 통과하도록 재설계(3.4-6) — 이는 "dry-run은 어떤 경로로도 상태를 변경하지 않는다"는 불변조건을 처음부터 지켰어야 했던 근본 설계 원칙의 누락이었음을 자체 인정 |
| 2 | (경미) `rc==0`/`rc==2` 분기 코드 중복(8곳) | 타당함, 권고사항으로 수용 | 3.3에 공통 헬퍼 함수 추출을 정식 리팩터링 항목으로 추가(우선순위는 낮음, 블로킹 아님) |

## 1~2.2장 — v3와 동일, 변경 없음
온보딩 기본화, stage-4의 3-분기 표(`verify_tui_viewport` 0/1/2 처리), `verify_session_uuid`의 `mode` 구분은 Reviewer가 이번 구현에서 정확히 반영되었음을 확인했으므로 변경 없이 유지한다.

## 2.3 Resume 실행-경로 사전검증 — "Dry-run은 어떤 분기로도 쓰지 않는다" 원칙 추가 (Reviewer 발견 1 반영)

### 2.3.1 문제의 근본 원인 재확인
`de45d5e0`(v2)에서 `resume_session.sh --dry-run`을 설계할 때, 스크립트의 5단계 흐름 중 **1~4단계만** dry-run 대상으로 명시했다:
> "1단계... 2단계에서 herdr가 이미 살아있는 경우, dry-run은 '이미 실행 중'으로 보고하고 성공 처리(실제 resume 시에도 이 경로는 spawn을 타지 않으므로 동일 로직)... 5단계(`_herdr new-session` 이하)는 실행하지 않는다."

이 서술은 "2단계는 spawn을 타지 않으니 dry-run에서도 안전하게 그대로 실행해도 된다"는 판단이었다 — **spawn 여부만 기준으로 안전성을 판단**했고, "실제 파일/DB 쓰기가 발생하는지"는 별도로 검토하지 않았다. 그러나 2단계는 spawn하지 않는 대신 **`update_yaml_resumed.sh`를 통해 실제 YAML/DB를 갱신**한다 — 이것이 이번에 발견된 결함의 정확한 근본 원인이다. **"dry-run"이라는 이름의 함의(상태를 바꾸지 않는 시뮬레이션)를 스크립트의 모든 분기에 대해 일관되게 지키지 못한 것**이 진짜 설계 공백이며, 이는 우연히 이번 라운드에서야(reconcile.sh가 이 dry-run을 이미 락을 쥔 트랜잭션 안에서 호출하기 시작하면서) 관측 가능한 증상(데드락)으로 드러난 것뿐, 결함 자체는 v2 설계 시점부터 존재했다.

### 2.3.2 신규 원칙: Dry-run은 어떤 코드 경로로도 절대 쓰지 않는다
`resume_session.sh --dry-run`은 다음을 만족해야 한다:
- 5단계(spawn)뿐 아니라 **2단계("이미 생존" 분기)도 포함해, `DRY_RUN=1`일 때는 스크립트의 어떤 분기도 `agent-sessions.yaml`/`.db`에 쓰기를 수행하지 않는다.**
- 이는 우연이 아니라 **의미적으로도 올바르다**: "herdr가 이미 살아있다"는 것은 실제 운영 모드에서도 spawn을 하지 않고 그저 YAML을 최신 상태로 동기화하는 부가 작업일 뿐, `resume_session.sh --dry-run`이 검증하려는 대상(스폰 경로의 유효성 — 바이너리 resolution, isolation 설정, `CMD_FULL` 조립)과 **무관**하다. 즉 "이미 살아있으면 검증할 스폰 경로 자체가 없다"는 뜻이므로, dry-run은 이 경우 그냥 "이미 실행 중 — 검증 대상 없음"으로 보고하고 종료하는 것이 개념적으로도 정확하다.

### 2.3.3 갱신된 5단계 흐름 (dry-run 게이팅 명시)
1. UUID 해석 — 변경 없음.
2. herdr 생존 확인:
   - **`DRY_RUN=1`이면**: `echo "[dry-run] herdr '$SESSION_NAME' already running — nothing to validate"`, **`update_yaml_resumed.sh` 호출 생략**, `exit 0`.
   - `DRY_RUN=0`(실제 모드)이면: 기존 그대로 `update_yaml_resumed.sh` 호출 후 `exit 0`.
3~4. isolation 설정 해석, 바이너리 resolution/실행권한 검증, `CMD_FULL` 조립 — v2/v3와 동일, dry-run 여부와 무관하게 항상 실행(이 부분은 원래도 쓰기가 없었으므로 문제 없음, 재확인만).
5. spawn — `DRY_RUN=1`이면 생략(기존과 동일).

### 2.3.4 원칙의 재사용성
이 "dry-run은 어떤 분기로도 쓰지 않는다"는 불변조건은 이번 스크립트에 국한되지 않고, **향후 이 MAM 코드베이스에 추가되는 모든 `--dry-run` 플래그에 적용되는 일반 설계 규칙**으로 승격한다. 리뷰에서 지적된 대로 "스크립트 레벨 `--dry-run`"(예: `reconcile.sh` 자신의 `--dry-run`, `env_python` 사용)과 "`resume_session.sh --dry-run`"처럼 이름은 같지만 의미/구현이 다른 두 플래그가 혼동을 야기했던 점도 있으므로, 4장에 이 네이밍 중복에 대한 후속 확인 항목을 추가한다.

## 3. 리팩터링 로드맵 — 갱신 사항

### 3.3 `reconcile.sh` — v3와 동일, 변경 없음
2-패스 재설계(트랜잭션 밖에서 서브프로세스 실행)는 **채택하지 않는다** — 2.3.2/2.3.3의 수정만으로 데드락의 근본 원인(자식 프로세스의 쓰기 시도)이 제거되므로, `reconcile.sh` 자체의 구조(드리프트 C를 `atomic_dump_yaml` 트랜잭션 안에서 실행하고 그 안에서 `resume_session.sh --dry-run`을 서브프로세스로 호출)는 그대로 유지해도 안전하다. 다만 다음 항목을 추가한다:
7. (경미, Reviewer 발견 2 반영) `rc==0`/`rc==2` 분기의 pin/resume-검증/상태갱신 로직이 거의 동일하므로, `reconcile.sh` 내에 공통 헬퍼(예: `_pin_and_verify_resume(s, agent, cwd, uuid, degraded=False)` 형태의 로컬 함수)로 추출해 4개 에이전트 × 2개 분기의 중복을 제거한다. 기능 변경 없음, 순수 리팩터링이므로 우선순위는 5.3(문서/정리)에 배치.

### 3.4 `resume_session.sh` 변경 — v3에 항목 추가
v3의 3.4절 1~5항은 그대로 유지한다. 추가로:
6. **2단계("herdr 이미 생존") 분기를 `DRY_RUN` 체크로 감싼다** (2.3.3 참조). 의사코드:
   ```bash
   if herdr has-session -t "$SESSION_NAME" 2>/dev/null; then
     if [ "${DRY_RUN:-0}" = "1" ]; then
       echo "[dry-run] herdr '$SESSION_NAME' already running — nothing to validate"
       exit 0
     fi
     echo "herdr '$SESSION_NAME' already running."
     bash ".../update_yaml_resumed.sh" --session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT"
     exit 0
   fi
   ```
   이것으로 `DRY_RUN=1`일 때 스크립트의 어떤 코드 경로도 `agent-sessions.yaml`/`.db`에 쓰지 않게 되어, `reconcile.sh`가 이미 보유한 배타 락과 충돌할 방법 자체가 사라진다(자식 프로세스가 애초에 그 락을 요청하지 않으므로).

## 4. 조사 필요/후속 확인 항목 (갱신)
- (v3 유지) agy/hermes/cline TUI 뷰포트 신호 실측 필요.
- (v3 유지, 이번에도 미반영 확인 시 재점검) `stop_session.sh` 리팩터링 — 다음 라운드 최우선.
- (v3 유지) `verify_session_uuid`의 `mode` 파라미터가 함수 시그니처 변경을 수반하는 리팩터링이라는 점 — 이미 이번 구현에서 반영 완료되었으므로 이 항목은 해소됨(v4에서 제거).
- **(신규)** "스크립트 레벨 `--dry-run`"(reconcile.sh, `env_python` 기반, 락 없음)과 "`resume_session.sh --dry-run`"(이번에 "쓰기 없음"이 보장되도록 수정)처럼 이름이 같은 플래그가 서로 다른 스크립트에서 의미상 미묘하게 다른 계약(전자는 원래도 안전, 후자는 이번에 안전하게 고침)을 갖게 되었다 — 향후 혼동 방지를 위해 각 스크립트의 `--help`/주석에 "이 플래그는 어떤 코드 경로로도 쓰기를 하지 않음을 보장한다"는 문구를 명시할 것을 권고(문서 정리, 5.3).

## 5. Implementer 라운드 우선순위 체크리스트 (갱신)

### 5.1 필수 (이번에 새로 추가된 머지 차단 사유)
1. `resume_session.sh`의 "herdr 이미 생존" 분기(2단계)를 `DRY_RUN` 체크로 감싸 어떤 경로로도 쓰지 않도록 수정 (2.3.3/3.4-6, Reviewer 발견 1).

### 5.2 다음 라운드 필수 (v3에서 이어짐, 변경 없음)
2. `stop_session.sh`를 `verify_session_uuid()`/`workspace_key` 재사용 구조로 리팩터링.

### 5.3 문서/정리 (기능에 영향 없음)
3. `reconcile.sh`의 `rc==0`/`rc==2` 코드 중복을 공통 헬퍼로 추출 (Reviewer 발견 2).
4. `--dry-run`류 플래그의 "쓰기 없음 보장" 계약을 각 스크립트 문서에 명시.

이전 v3의 5.1(하드코딩 nvm 경로 제거, verify_tui_viewport 3-분기, mode 파라미터)과 5.3(SKILL.md 갱신, dead code 제거)은 이번 구현 라운드에서 모두 반영 완료 확인되었으므로 체크리스트에서 제거한다.

## 6. 결론
Reviewer가 발견한 치명적 결함(resume dry-run이 reconcile.sh 자신의 트랜잭션과 락 경합을 일으키는 문제)을 전면 수용해, "dry-run은 어떤 코드 경로로도 절대 쓰지 않는다"는 불변조건을 `resume_session.sh`의 모든 분기(특히 이전에 간과되었던 "herdr 이미 생존" 분기)에 명시적으로 적용하도록 설계를 수정했다. 이 원칙은 spawn 경로 검증이라는 dry-run의 본래 목적과도 의미적으로 정확히 부합한다(이미 살아있는 세션은 검증할 스폰 경로가 없으므로 그냥 "검증 대상 없음"으로 보고하는 것이 옳다). 2-패스 트랜잭션 재설계 같은 더 무거운 대안은 이 단순한 수정만으로 문제가 완전히 해소되므로 채택하지 않았다. 경미한 코드 중복 지적(발견 2)은 문서/정리 항목으로 반영했다. 코드는 아직 5.1 항목 반영 전 상태이며, 이 한 가지 수정 후 재검증을 거쳐야 unanimous PASS를 다시 요청할 수 있다.

[VERDICT: PASS]