docs(deploy): synchronize deploy/ assets with nats-docker submodule and hermes prefix defaults

docs: synchronize MESSAGING.md, IMPROVEMENTS.md, implementation_plan.md and add D-31/D-32 freshness guards
docs: archive Reviewer cline PASS report and update submodule doc links
2026-08-23 16:40:22 +09:00 · 2026-08-23 16:22:10 +09:00 · 2026-08-23 15:36:32 +09:00 · 2026-08-23 15:11:04 +09:00 · 2026-08-23 15:06:47 +09:00 · 2026-08-23 14:54:23 +09:00
24 changed files with 3698 additions and 586 deletions
@@ -0,0 +1,375 @@
+# 🔎 문서 정합성 검증 및 동기화 계획서 Rev.2 (Job `eb04e918`)
+
+- **작성일**: 2026-08-23
+- **역할**: Planner (`.agents/MULTI_AGENT_RULES.md` §1 — Planner 는 저장소 코드/문서를 **수정하지 않으며**, 산출물은 본 보고서입니다)
+- **기준 커밋**: `916185c`, 작업 트리 clean, `main` 은 `origin/main` 보다 **ahead 2**
+- **선행 리비전**: `1fa7183a` (Rev.1) ← 본 문서가 대체합니다
+- **판정 대상 리뷰**: `b93680ab` (agy, `[VERDICT: PASS WITH CHALLENGE]`) — CI 서브모듈 인증 / D-31 스코프 / B-17 fail-closed
+- **검증 대상**: `MESSAGING.md`, `IMPROVEMENTS.md`, `implementation_plan.md`
+
+---
+
+## A. 리뷰 판정 (Adjudication of Challenge `b93680ab`)
+
+### A-0. 판정 요약
+
+| 챌린지 | 판정 | 핵심 근거 |
+|---|---|---|
+| **C1** 서브모듈 인증·URL 제약 | 🟢 **전제 확증 — 다만 처방 형태는 틀림** | `laa/nats-docker` 는 실제로 **비공개**(익명 `ls-remote` → `Failed to authenticate user`). 그러나 제안된 `url = ../nats-docker` 는 **`tmpl/nats-docker`** 로 해석되어 **잘못된 조직**을 가리킴(실측). 올바른 형태는 `../../laa/nats-docker` |
+| **C2** D-31 과도한 제약 | ✅ **전면 수용 — Rev.1 의 논거가 틀렸음** | `lint-shell`/`lint-python` 은 `.agents/`·`deploy/` 만 훑으며 서브모듈 경로를 읽지 않음(실측). Rev.1 이 내세운 "비대칭" 논거는 성립하지 않음 |
+| **C3** 명시적 `MAM_ENV_FILE` fail-closed | ✅ **원칙 수용 — 다만 차단 지점을 옮겨야 함** | `_load_dotenv()` 는 **import 시점**에 호출되고(`mqtt_common.py:112`) 테스트 3개 파일이 `mqtt_common` 을 import 함. 여기서 예외를 던지면 스위트 자체가 붕괴 |
+
+리뷰어의 세 지적은 모두 실재하는 맹점을 짚었고, 그중 둘은 **Rev.1 의 처방을 직접 교정**합니다. 다만 C1 의 구체적 처방과 C3 의 차단 지점은 그대로 구현하면 각각 서브모듈을 깨뜨리거나 테스트 스위트를 깨뜨립니다. 아래에서 측정으로 교정합니다.
+
+---
+
+### A-1. C1 — 전제는 옳다. 처방의 형태가 틀렸고, 처방만으로는 부족하다
+
+#### (1) 전제 확증: 서브모듈은 실제로 비공개다
+
+익명(자격증명 없이) `ls-remote` 실측:
+
+| 대상 | 결과 |
+|---|---|
+| `https://git.godopu.com/laa/nats-docker` | 🔴 `remote: Failed to authenticate user` → **비공개** |
+| `https://git.godopu.com/tmpl/multi-agent-mux` (상위 저장소) | 🟢 `629a67f… HEAD` 응답 → **공개** |
+
+리뷰어가 가정한 "비공개 서브모듈이면 토큰이 전파되지 않아 실패" 시나리오는 **가정이 아니라 현실**입니다. Rev.1 의 T-1(`submodules: recursive` 한 줄 추가)만으로는 CI 가 여전히 실패합니다. 이 지적은 Rev.1 의 실질적 결함을 잡아냈습니다.
+
+더 나아가 실측이 드러낸 구조는 리뷰어가 알던 것보다 까다롭습니다: **상위 저장소는 공개, 서브모듈은 비공개, 게다가 서로 다른 조직**(`tmpl/` vs `laa/`). 즉 CI 러너가 상위 저장소를 익명으로 받을 수 있어도 서브모듈에는 별도 권한이 필요합니다.
+
+#### (2) 처방 형태 교정: `../nats-docker` 는 잘못된 저장소를 가리킨다
+
+git 의 상대 서브모듈 URL 은 **상위 저장소의 origin URL 기준**으로 해석됩니다. 실측(임시 저장소에 origin 을 동일하게 설정하고 `git submodule init` 으로 해석 결과 확인):
+
+```
+origin = https://git.godopu.com/tmpl/multi-agent-mux
+
+url = ../nats-docker        ->  https://git.godopu.com/tmpl/nats-docker      ❌ 조직 불일치
+url = ../nats-docker.git    ->  https://git.godopu.com/tmpl/nats-docker.git  ❌ 조직 불일치
+url = ../../laa/nats-docker ->  https://git.godopu.com/laa/nats-docker       ✅ 정확
+```
+
+실제 저장소는 `laa/` 아래에 있으므로, 리뷰어가 제시한 두 형태(`../nats-docker`, `../nats-docker.git`)를 그대로 적용하면 **존재하지 않는 경로**를 가리켜 서브모듈이 아예 클론되지 않습니다. 상위 저장소와 서브모듈이 같은 조직에 있다는 암묵적 가정이 이 인스턴스에서는 성립하지 않습니다.
+
+#### (3) 처방 충분성 교정: 상대 URL 은 인증을 해결하지 않는다
+
+상대 URL 이 물려받는 것은 **프로토콜과 호스트**이지 **권한**이 아닙니다. SSH 로 상위를 클론하면 서브모듈도 SSH 로 가므로 키가 재사용되는 이점은 실재하지만, HTTPS + 토큰 조합에서는 토큰의 스코프가 `laa/nats-docker` 를 포함해야 합니다. 상위가 공개이고 서브모듈이 비공개인 현 구조에서는 **상대 URL 로 바꿔도 자격증명은 여전히 별도로 공급**해야 합니다.
+
+따라서 T-1 은 한 줄 추가가 아니라 세 부분으로 확장됩니다(§4 T-1a/T-1b/T-1c).
+
+#### (4) 실측으로 드러난 제3의 선택지 — 서브모듈 공개 전환
+
+`nats-docker` 가 추적하는 파일은 **10개뿐이며 비밀을 담은 파일이 0개**입니다.
+
+```
+.agents/skills/env-generator/SKILL.md      docker/.env.example
+.agents/skills/env-generator/scripts/…     docker/README.md
+.gitignore                                 docker/docker-compose.yaml
+NATS_REPORT.md                             docker/nats.conf
+PRIVATE_SERVER.md
+README.md
+```
+
+- `.gitignore` 가 `.env` / `*.env` 를 제외하고 `!*.env.example` 만 허용 — 실제 시크릿은 추적 대상이 아님.
+- `docker/.env.example` 은 설계상 **빈 값**(D-25(d) 가 봉인).
+- `docker/nats.conf` 는 모든 `password:` 가 `$VAR` 참조(D-25(e) 가 봉인).
+
+즉 이 저장소를 공개해도 유출되는 비밀은 없습니다. 남는 것은 "배포 토폴로지를 공개할 것인가"라는 **정책 판단**이므로 일방적으로 처방하지 않고 §4 에서 3개 선택지로 제시합니다. 다만 공개 전환은 CI 인증 문제를 **완전히 소멸**시키는 유일한 선택지입니다.
+
+#### (5) 부수 실측 — 폭발은 아직 안 터졌을 뿐이다
+
+`git status -sb` → `## main...origin/main [ahead 2]`. 즉 `12ba30b`(문서 서브모듈 이전)와 `916185c` 는 **아직 푸시되지 않았고**, 원격 HEAD 는 `629a67f` 입니다. CI 는 아직 이 변경을 본 적이 없습니다. **다음 푸시 순간 S-1 이 발현**하므로 T-1 은 푸시 이전에 완료되어야 합니다.
+
+---
+
+### A-2. C2 — 전면 수용. Rev.1 의 논거가 틀렸다
+
+Rev.1 은 "test 잡만 고치면 lint/compile 잡이 서브모듈 없는 트리를 훑는 **비대칭**이 남는다"는 이유로 세 checkout 전부에 `submodules` 를 요구했습니다. 실측 결과 이 논거는 성립하지 않습니다.
+
+| 잡 | 실제로 읽는 경로 | 서브모듈 필요 |
+|---|---|:---:|
+| `lint-shell` | `.agents/skills/**`, `.agents/hooks/…`, `deploy/*.sh` (shellcheck 대상 15개 파일 명시) | ❌ |
+| `lint-python` | `.agents/skills/multi-agent-mux-delegate-job/scripts/`, `.agents/skills/lib_py/` (flake8·py_compile) | ❌ |
+| `test` | `pytest tests/ -q` → D-11~D-19, D-22~D-30 이 `nats-docker/**` 를 읽음 | ✅ |
+
+lint 잡들은 서브모듈 경로를 **한 번도 참조하지 않습니다**. 없는 트리를 훑는 "비대칭"은 관측 가능한 결과를 낳지 않으므로 교정 대상이 아니었습니다. 리뷰어의 두 지적(불필요한 네트워크 I/O, 향후 경량 워크플로에서의 false positive)이 옳습니다.
+
+**다만 리뷰어 처방에 한 가지를 더합니다 — 공허 통과 방지.** "pytest 를 실행하는 잡"으로 스코프를 좁히면, 잡 이름을 바꾸거나 `pytest` 를 래퍼 스크립트(`make test`, `bash deploy/run-tests.sh`) 뒤로 숨기는 순간 가드가 **검사 대상 0건으로 조용히 통과**합니다. 따라서 D-31 은 테스트 수행 잡을 **하나도 못 찾으면 실패**해야 합니다. 이것이 없으면 스코프 축소가 곧 가드 무력화 경로가 됩니다.
+
+**구현 실측 참고**: PyYAML 로 `deploy/gitea-ci.yml` 을 파싱하면 최상위 키가 `['name', True, 'jobs']` 로 나옵니다 — YAML 1.1 이 `on:` 을 불리언 `True` 로 해석하는 알려진 함정입니다. D-31 은 `jobs` 만 읽으므로 영향은 없으나, Creator 가 `d["on"]` 에 접근하면 `KeyError` 를 만납니다. 현재 세 잡 모두 checkout 스텝 1개 · `with` 는 `None` 이며, `pytest` 가 포함된 잡은 `test` **하나**입니다.
+
+---
+
+### A-3. C3 — 원칙 수용. 그러나 "기동 차단"을 import 시점에 두면 스위트가 죽는다
+
+#### (1) 리뷰어가 옳은 부분
+
+Rev.1 의 처방은 "`MAM_ENV_FILE`(존재할 때만) → `MAM_REAL_ROOT` → … → `walk_up(cwd)`" 순서였습니다. 이는 사용자가 **명시적으로 지정한** 경로가 없을 때 상위 디렉터리의 다른 `.mam.env` 를 임의로 집어 든다는 뜻이고, 리뷰어 지적대로 **명시적 설정 우선 원칙 위반**입니다. 다른 프로젝트의 브로커/계정으로 조용히 붙을 위험이 실재합니다. 이 부분은 Rev.1 의 설계 오류이며 수정합니다.
+
+#### (2) 그러나 차단 지점은 옮겨야 한다
+
+`mqtt_common.py:112` 는 모듈 최상위에서 `_load_dotenv()` 를 호출합니다 — 즉 **import 부작용**입니다. 그리고 `mqtt_common` 을 import 하는 테스트 파일이 3개 있습니다.
+
+```
+tests/test_tier1_unit.py
+tests/test_tier2_component.py
+tests/test_deploy_freshness.py     ← D-19/D-27 이 DEFAULT_TOPIC_ROOT 만 읽으려고 import
+```
+
+여기서 예외를 던지면, 낡은 `MAM_ENV_FILE` 이 환경에 남아 있는 **모든** 상황에서 `import mqtt_common` 이 실패하고 스위트가 수집 단계에서 붕괴합니다. 브로커에 접속할 의도가 전혀 없는 소비자(상수 하나 읽는 테스트)까지 함께 죽습니다.
+
+#### (3) 종합 처방 — 기록은 import 에서, 거부는 접속 지점에서
+
+| 단계 | 동작 |
+|---|---|
+| **import (`_load_dotenv`)** | `MAM_ENV_FILE` 이 설정됐는데 파일이 없으면 → `logger.error("MAM_ENV_FILE is set to %s but no such file; refusing to auto-discover", path)` 후 **모듈 전역 플래그** `_env_file_missing = True` 설정. **자동 탐색을 시도하지 않음**(리뷰어 요구 반영). **예외를 던지지 않음** |
+| **`MAM_ENV_FILE` 미설정** | 순서 있는 탐색 수행: `MAM_REAL_ROOT` → `WORKSPACE_ROOT` → `walk_up(__file__)` → `walk_up(cwd)` |
+| **접속 지점 (`make_client()` / 브로커 설정 확정)** | ① `_env_file_missing` 이면 **명시적 예외로 거부**(fail-closed). ② 해석된 호스트가 내장 공개 기본값(`broker.hivemq.com`)과 같으면 **눈에 띄는 보안 경고** 출력 |
+
+이 배치가 두 요구를 모두 만족시킵니다: 명시적 설정이 깨졌을 때 조용히 다른 환경으로 새지 않고(리뷰어 C3-1), 자동 탐색이 아무것도 못 찾아 공개 브로커로 떨어질 때 반드시 경고가 나오며(리뷰어 C3-2), 그러면서도 읽기 전용 소비자의 import 를 깨뜨리지 않습니다.
+
+**보조 실측** — `_parse_env_file` 은 `if key and key not in os.environ` 로 기록하므로 **OS 환경변수가 파일보다 우선**합니다. 따라서 사용자가 `MQTT_BROKER` 를 직접 export 한 경우에는 공개 기본값으로 떨어지는 일이 애초에 없습니다. 위 ②의 조건을 "`MAM_ENV_FILE` 부재"가 아니라 "**해석 결과가 공개 기본값과 일치**"로 잡은 이유이며, 이 편이 탐색 경로 전체를 한 번에 덮습니다.
+
+---
+
+## B. Rev.1 → Rev.2 변경 요약
+
+| # | 변경 | 출처 |
+|---|---|---|
+| C-1 | **T-1 을 T-1a/T-1b/T-1c 로 분할** — `.gitmodules` 상대 URL은 `../../laa/nats-docker`(리뷰어 제시 형태는 오답), 비공개 서브모듈 자격증명 공급, 3개 선택지 비교 | A-1 |
+| C-2 | **D-31 스코프 축소** — "모든 checkout" → "테스트 수행 잡의 checkout". **공허 통과 방지 단언 추가** | A-2 |
+| C-3 | **T-9(B-17) 처방 재설계** — import 시점 기록 + 접속 지점 거부의 2단 구조. 명시적 경로 실패 시 자동 탐색 금지 | A-3 |
+| C-4 | 신규 발견 **S-13**(미푸시 2커밋 — S-1 발현 시점), **S-14**(공개 상위 / 비공개 서브모듈 비대칭) | A-1(5), A-1(1) |
+| C-5 | Rev.1 의 T-1 논거(“lint 잡 비대칭”) **철회** — 실측상 성립하지 않음 | A-2 |
+| C-6 | D-31 구현 주의 추가 — PyYAML 이 `on:` 을 `True` 키로 파싱 | A-2 |
+
+Rev.1 의 판정, 실측 원장(V-1~V-15), 발견 S-1~S-12, 작업 T-2~T-8·T-10~T-14, 가드 D-32 는 리뷰에서 전면 동의를 받았으며 변경 없이 유지합니다.
+
+---
+
+## 0. 판정
+
+테스트는 전건 통과하나 **문서 동기화 목표는 여전히 미충족**입니다(구현이 아직 수행되지 않았으므로 Rev.1 판정 유지).
+
+- `MESSAGING.md` 는 NATS·JetStream·Docker·원격·Tailscale 을 **0건** 언급하며, 확정 표준(`nats-server` MQTT **3.1.1**)과 모순되는 서술(`MQTT 5.0` / `Mosquitto·EMQX`)을 프로덕션 표준으로 제시합니다.
+- `IMPROVEMENTS.md` 는 해결된 B-14/B-15 를 미해결로 집계하고, Track 1R·D-22~D-30·서브모듈 전환을 0건 반영했습니다.
+- CI 는 서브모듈을 받지 않아 배포 신선도 가드 29건 중 **18건이 실패**하며(실측), 서브모듈이 **비공개**이므로 `submodules: recursive` 한 줄로는 해결되지 않습니다(신규).
+
+**[VERDICT: NOT PASS]**
+
+---
+
+## 1. 테스트 실행 결과
+
+| 명령 | 결과 |
+|---|---|
+| `.venv/bin/python -m pytest tests/test_deploy_freshness.py tests/test_sanity.py -q` | **31 passed in 21.43s** |
+| `.venv/bin/python -m pytest tests/ -q` (전체) | **306 passed in 375.81s** (exit 0) |
+| `pytest tests/ -q --collect-only` | **306 collected** |
+
+문서 회귀 0건. 양호 항목(조치 불필요): `_resolve_private_server_doc()`·`_resolve_docker_dir()` 3-후보 폴백 구현 ✅ / D-16 구멍 교정(`assert "alpine" in tag`) ✅ / `requirements.txt` 에 `PyYAML>=6.0` 추가 ✅ / CI 의 PyYAML 은 스킬 `requirements.txt` 의 `pyyaml` 로 확보되어 **결함 아님** ✅ / `implementation_plan.md` §5 P0.5·R-1~R-13 및 서브모듈 링크(`:7`, `:147`) 갱신 ✅.
+
+---
+
+## 2. 실측 원장
+
+Rev.1 의 V-1 ~ V-15 는 유지하며, 본 리비전에서 다음을 추가 측정했습니다.
+
+| # | 검증 | 방법 | 결과 |
+|---|---|---|---|
+| **V-16** | 서브모듈 공개 여부 | 자격증명 없이 `git ls-remote https://git.godopu.com/laa/nats-docker` | 🔴 `remote: Failed to authenticate user` → **비공개** |
+| **V-17** | 상위 저장소 공개 여부 | 동일 방식 `…/tmpl/multi-agent-mux` | 🟢 ref 목록 응답 → **공개** (원격 HEAD `629a67f`) |
+| **V-18** | 상대 URL 해석 | 임시 저장소에 동일 origin 설정 후 `git submodule init` | `../nats-docker` → `tmpl/nats-docker` ❌ / `../../laa/nats-docker` → `laa/nats-docker` ✅ |
+| **V-19** | 서브모듈 비밀 노출 | `git -C nats-docker ls-files` + `.gitignore` | 추적 파일 **10개, 비밀 파일 0개**. `.env` 제외, `.env.example` 빈 값, `nats.conf` 전부 `$VAR` |
+| **V-20** | 미푸시 커밋 | `git status -sb` | `## main...origin/main [ahead 2]` — `12ba30b`, `916185c` 미푸시 |
+| **V-21** | lint 잡의 서브모듈 의존 | `deploy/gitea-ci.yml:15-80` 의 shellcheck/flake8/py_compile 대상 경로 | `.agents/**`, `deploy/*.sh` 만 — **서브모듈 참조 0건** |
+| **V-22** | CI YAML 파싱 | PyYAML `safe_load` | 최상위 키 `['name', True, 'jobs']` (`on:` → 불리언). `pytest` 포함 잡 = `test` **1개**, 세 잡 모두 checkout 1개 · `with` 는 `None` |
+| **V-23** | `_load_dotenv` 호출 시점 | `mqtt_common.py:112` | **모듈 최상위 = import 부작용** |
+| **V-24** | `mqtt_common` import 소비자 | `grep -rln "import mqtt_common" tests/` | `test_tier1_unit.py`, `test_tier2_component.py`, `test_deploy_freshness.py` — **3개** |
+| **V-25** | 환경변수 우선순위 | `_parse_env_file`: `if key and key not in os.environ` | **OS 환경변수가 `.mam.env` 보다 우선** |
+
+---
+
+## 3. 발견 사항
+
+Rev.1 의 S-1 ~ S-12 를 유지하고, S-1 을 갱신하며 S-13/S-14 를 신설합니다. (S-2 ~ S-12 상세는 Rev.1 과 동일하므로 요지만 재수록합니다.)
+
+### 🔴 S-1 (P1, CI 차단) — **갱신**: 서브모듈 미체크아웃 + 비공개 저장소 인증
+
+`deploy/gitea-ci.yml` 의 checkout 3곳(`:21`, `:53`, `:87`)이 옵션 없이 `actions/checkout@v3` 를 씁니다. 트리를 복제해 `nats-docker/` 를 비운 시뮬레이션에서 **18 failed, 11 passed**(D-11~D-19, D-22~D-30 전멸)를 실측했습니다.
+
+**Rev.2 갱신**: `submodules: recursive` 추가만으로는 부족합니다. 서브모듈이 **비공개**(V-16)이고 상위 저장소는 **공개**(V-17)이며 **서로 다른 조직**이므로, 러너에 `laa/nats-docker` 읽기 권한이 별도로 공급되어야 합니다. §4 T-1a/T-1b/T-1c 참조.
+
+### 🔴 S-13 (P1, 타이밍) — **신설**: 아직 푸시되지 않았을 뿐이다
+
+`main` 이 `origin/main` 보다 **ahead 2**(V-20). 원격 HEAD 는 `629a67f` 이고, 서브모듈 문서 이전 커밋 `12ba30b`·`916185c` 는 로컬에만 있습니다. CI 는 아직 이 상태를 본 적이 없으며, **다음 푸시 순간 S-1 이 발현**합니다. T-1 은 푸시 이전에 완료되어야 하며, 그렇지 않으면 `main` 브랜치 CI 가 즉시 빨간불이 됩니다.
+
+### 🟠 S-14 (P2, 구조) — **신설**: 공개 상위 / 비공개 서브모듈 비대칭
+
+상위 저장소는 누구나 클론할 수 있으나(V-17) 서브모듈은 자격증명을 요구합니다(V-16). 결과적으로 **외부 사용자가 `deploy/install.sh` 경로로 이 프레임워크를 받으면 `nats-docker/` 는 빈 디렉터리**가 됩니다. 현재는 `install.sh` 가 `docker/` 나 `PRIVATE_SERVER.md` 를 배포하지 않으므로(Rev.1 D-8) 실사용에 지장은 없지만, 저장소를 클론해 테스트를 돌리려는 외부 기여자는 **18건 실패**를 만나게 됩니다. §4 T-1c 의 선택지 A(공개 전환)가 이 문제까지 함께 해소합니다.
+
+### 나머지 발견 (Rev.1 유지, 요지)
+
+| ID | 요지 |
+|---|---|
+| 🔴 **S-2** (P1) | `MESSAGING.md` 에 nats/jetstream/docker/remote/tailscale **0건**. §1.2 가 "MQTT **5.0** … Mosquitto or EMQX" 를 프로덕션 표준으로 제시 — NATS 는 MQTT 5.0 미지원이므로 단순 구식이 아니라 모순. §1.3 은 Mosquitto 설정을 유일한 레퍼런스로 제시 |
+| 🔴 **S-3** (P1) | `MESSAGING.md` §6.1-3 이 이미 해결된 B-15 를 현재 제약으로 서술("it exits, leaving the running herdr agent orphaned"). 실제로는 `job_subscriber.py:60 _check_disk_fallback`, `:230`, `:244`, `return 3` 존재. §4.2 도 B-14 수정 미반영 |
+| 🟠 **S-4** (P2) | `MESSAGING.md` 가 `broker_config_from_env` 파싱 10종 중 8종만 문서화 — `MQTT_CLIENT_ID_PREFIX`, `MQTT_KEEPALIVE` 누락. `.mam.env` 해석 순서(`_load_dotenv`) 절 부재 |
+| 🔴 **S-5** (P1) | `IMPROVEMENTS.md:3-6` 이 `276/276`, 미해결 5건(B-14·B-15 포함), 완료 24건. 실제로는 306/306, B-14/B-15 는 `c6b6c77` 에서 해결·G-1~G-10 봉인. 제목의 `✅ 완료` 마커도 이 둘만 누락(다른 42개는 보유) → 미해결 **3건**, 완료 **26건**. **A-2 는 M3 미완이므로 미해결 유지** |
+| 🔴 **S-6** (P1) | `IMPROVEMENTS.md` 에 `D-22`~`D-30`, `nats-docker`, `submodule`, `Track 1R` **0건**. 커밋 5종(`3523b9b`, `b09d420`, `629a67f`, `12ba30b`, `916185c`)의 성과가 백로그에 부재 |
+| 🔴 **S-7** (P1, 보안) | `B-17`/`B-18` 미등록(`implementation_plan.md:143` 은 등록 요구). HEAD 재현: `MAM_ENV_FILE=<오타경로>` → `broker.hivemq.com 1883 tls=False`, 대조군 → `vm-ubuntu 1883`. `.mam.env` 가 이미 사설 브로커를 가리키므로 지금이 더 위험 |
+| 🟠 **S-8** (P2) | `implementation_plan.md:3-5` 헤더가 `v1.0.0` / `a9934ad` / `276/276` — 실제 HEAD `916185c`, 306/306 |
+| 🟠 **S-9** (P2) | `:23` Track 1R 변경 지점이 구 경로. `:13-16` 트랙 다이어그램에 Track 1R 부재(§2 마일스톤 도식과 불일치). `:39` 테스트 수 `276 -> 280` |
+| 🟠 **S-10** (P2) | 서브모듈 전환(`629a67f`, `12ba30b`)이 로드맵에 기록 없음 |
+| 🟠 **S-11** (P2) | `:177` `.mam.env` 전환 미체크인데 실제로는 `MQTT_BROKER=vm-ubuntu`, `MQTT_USERNAME=mam_agent` 로 전환 완료 — 추적기가 현실보다 뒤처짐 |
+| 🟡 **S-12** (P3) | `:172` 의 `PRIVATE_SERVER.md:73`, `:146` 행 번호 인용이 낡음 → 절 번호로 교체 |
+
+---
+
+## 4. 동기화 작업 명세 (Creator 범위)
+
+**T-1 계열은 CI 를 되살리는 작업이며 S-13 때문에 다음 푸시 이전에 완료되어야 합니다.**
+
+### T-1a — `.gitmodules` 상대 URL 전환 (선택지 C 를 택할 경우 필수, 그 외에는 권고)
+
+```ini
+[submodule "nats-docker"]
+	path = nats-docker
+	url = ../../laa/nats-docker
+```
+
+⚠️ **`../nats-docker` 를 쓰지 마십시오.** 상위 origin 이 `tmpl/multi-agent-mux` 이므로 `tmpl/nats-docker` 로 해석되어 존재하지 않는 저장소를 가리킵니다(V-18). 변경 후 반드시 검증:
+
+```bash
+git submodule sync --recursive
+git config --get submodule.nats-docker.url   # → https://git.godopu.com/laa/nats-docker
+```
+
+효과는 **프로토콜·호스트 상속**(SSH 클론 시 서브모듈도 SSH, 미러/포크 이전 시 자동 추종)이며, **권한 문제는 해결하지 않습니다**.
+
+### T-1b — CI checkout 에 서브모듈 활성화
+
+`test` 잡의 checkout 스텝(`deploy/gitea-ci.yml:87`)에만 적용합니다(A-2).
+
+```yaml
+      - name: Checkout Code
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+```
+
+`lint-shell`/`lint-python` 은 **변경하지 않습니다** — 서브모듈 경로를 읽지 않음이 실측되었습니다(V-21).
+
+### T-1c — 비공개 서브모듈 접근 확보 (택 1, 정책 판단 필요)
+
+| 선택지 | 방법 | 장점 | 단점 |
+|---|---|---|---|
+| **A. `nats-docker` 공개 전환** 🏆 | Gitea 에서 저장소 visibility 를 public 으로 | CI 인증 문제 **완전 소멸**. 외부 기여자 S-14 도 동시 해소. 추적 파일에 비밀 0건이 실측됨(V-19) | 배포 토폴로지(포트·계정 구조)가 공개됨. 단, 비밀은 없으며 보안은 시크릿에 의존하지 모호성에 의존하지 않음 |
+| **B. 러너에 읽기 토큰 주입** | `test` 잡에 `laa/nats-docker` 읽기 스코프 토큰을 secret 으로 두고, checkout 앞에 `git config --global url."https://<user>:${{ secrets.SUBMODULE_TOKEN }}@git.godopu.com/".insteadOf "https://git.godopu.com/"` | 저장소 비공개 유지 | 토큰 수명 관리 필요. 토큰이 CI 로그에 노출되지 않도록 주의. 외부 기여자는 여전히 실패 |
+| **C. 배포 키 + SSH URL** | `.gitmodules` 를 SSH 로 두고 러너에 read-only deploy key 배치 (T-1a 와 병행) | 스코프가 저장소 단위로 최소화됨 | 러너 이미지에 키 배치·`known_hosts` 관리 필요. 사설 도메인 DNS/인증서 이슈는 별도 |
+
+**권고: A.** 실측(V-19)상 공개해도 잃을 비밀이 없고, 세 선택지 중 유일하게 CI·외부 기여자·미래 미러 문제를 한 번에 없앱니다. 비공개 유지가 조직 정책이라면 B 를 택하고, 그 경우 §5 의 D-31 은 "checkout 이전에 자격증명 설정 스텝이 존재하는가"까지 검사하도록 확장하십시오.
+
+**검증**: Rev.1 의 시뮬레이션(트리 복제 후 `nats-docker/` 를 비우고 `pytest tests/test_deploy_freshness.py -q`)을 재실행하여 `18 failed` → `0 failed` 확인. 가능하면 실제 CI 에서 `test` 잡 1회 통과까지 확인.
+
+### T-2 ~ T-14 (Rev.1 유지, T-9 만 재설계)
+
+| ID | 파일 | 작업 |
+|---|---|---|
+| **T-2** | `MESSAGING.md` §1.2 / §1.3 | 프로덕션 브로커 표준을 `nats-server`(MQTT **3.1.1**)로 재작성. mermaid 노드·ACL 예시를 `MAM` 계정 / `mam_agent`·`mam_observer` / NATS `permissions` 문법으로 교체. Mosquitto 설정은 §1.4 "대안"으로 강등하고 상세는 `nats-docker/PRIVATE_SERVER.md` 링크 |
+| **T-3** | `MESSAGING.md` 신설 절 | JetStream 요구(MQTT 리스너 전제), retained=MQTT 전용 경계(N-1), MQTT-over-WebSocket `/mqtt`(N-7), 원격 노출 모델(모델 T/P) 요약 + 서브모듈 링크 |
+| **T-4** | `MESSAGING.md` §4.2 / §4.3 / §6.1-3 | B-14(발행 실패와 무관한 상태 동기화), B-15(`_check_disk_fallback`), F-4(rc=3) 반영. §6.1-3 은 "해결됨" 처리하되 잔여 제약(자동 재연결 루프 부재)만 유지 |
+| **T-5** | `MESSAGING.md` §4.4 | `MQTT_CLIENT_ID_PREFIX`·`MQTT_KEEPALIVE` 추가. `.mam.env` 해석 순서 절 신설, **OS 환경변수 우선**(V-25) 명기, **B-17 미해결 경고** 포함 |
+| **T-6** | `IMPROVEMENTS.md` 헤더 | 갱신일 2026-08-23, `306/306`, 미해결 **3건**(A-2, B-16, O-5), 완료 **26건** |
+| **T-7** | `IMPROVEMENTS.md` `:76`, `:81` | B-14·B-15 제목에 `✅ 완료` 마커 + 해결 커밋(`c6b6c77`)·가드(G-1~G-10) 기록 |
+| **T-8** | `IMPROVEMENTS.md` 신설 | `O-6 (✅ 완료): 원격 프로덕션 브로커 자산 정본화 및 nats-docker 서브모듈 분리` — 커밋 5종, D-22~D-30, 동적 경로 해석기, 297→306 |
+| **T-9** 🔄 | `IMPROVEMENTS.md` 신설 + 처방 | **`B-17 (P1)`** 등록. 처방을 **2단 구조**로 명시(아래 상세). `B-18` 도 함께 등록 |
+| **T-10** | `implementation_plan.md` `:3-5` | 문서 버전 상향, 기준 커밋 `916185c`, `306/306` |
+| **T-11** | `implementation_plan.md` `:13-16`, `:23`, `:39` | 트랙 다이어그램에 Track 1R 포함, 변경 지점을 `nats-docker/…` 경로로, 마일스톤 표 테스트 수 갱신 |
+| **T-12** | `implementation_plan.md` §5, §8 | `P0.6 서브모듈 분리` 단계 + 체크리스트 3행(2행 완료, **CI 1행 미완료**) |
+| **T-13** | `implementation_plan.md` `:177` | `.mam.env` 전환 실태 반영 — 체크 처리하거나 절차 미이행 사실 기록 |
+| **T-14** | `implementation_plan.md` `:172` | 행 번호 인용을 절 번호로 교체 |
+
+#### T-9 상세 — B-17 처방 (C3 반영 재설계)
+
+```python
+# mqtt_common.py — import 시점: 기록만, 예외 없음
+_env_file_missing: Optional[str] = None
+
+def _load_dotenv(workspace_dir=None):
+    global _env_file_missing
+    explicit = os.environ.get("MAM_ENV_FILE")
+    if explicit:
+        if os.path.isfile(explicit):
+            _parse_env_file(explicit)
+        else:
+            _env_file_missing = explicit
+            logger.error(
+                "MAM_ENV_FILE is set to %s but no such file exists; "
+                "refusing to auto-discover another .mam.env", explicit)
+        return                      # 명시적 지정 시 자동 탐색 금지 (리뷰어 C3-1)
+    # 미설정일 때만 순서 있는 탐색 (first-hit-wins)
+    for cand in (_from_env("MAM_REAL_ROOT"), _from_env("WORKSPACE_ROOT"),
+                 _walk_up(os.path.dirname(os.path.abspath(__file__))),
+                 _walk_up(os.getcwd())):
+        if cand and os.path.isfile(cand):
+            _parse_env_file(cand); return
+```
+
+```python
+# 접속 지점(make_client 또는 설정 확정 함수) — 여기서 거부한다
+def make_client(role, cfg):
+    if _env_file_missing:
+        raise RuntimeError(
+            f"MAM_ENV_FILE points to a missing file ({_env_file_missing}); "
+            "refusing to connect with an unverified broker identity")
+    if cfg.host == "broker.hivemq.com":
+        logger.error("SECURITY: falling back to the PUBLIC broker "
+                     "broker.hivemq.com — job payloads will be world-readable")
+    ...
+```
+
+**왜 import 에서 던지지 않는가**: `_load_dotenv()` 는 `mqtt_common.py:112` 의 import 부작용이고(V-23), 테스트 3개 파일이 브로커 접속 의도 없이 이 모듈을 import 합니다(V-24). import 에서 예외를 던지면 낡은 `MAM_ENV_FILE` 하나로 스위트 전체가 수집 단계에서 붕괴합니다.
+
+**왜 경고 조건이 "공개 기본값과 일치"인가**: OS 환경변수가 파일보다 우선하므로(V-25), `MQTT_BROKER` 를 직접 export 한 사용자는 파일이 없어도 공개 브로커로 떨어지지 않습니다. 호스트 결과값을 기준으로 삼으면 탐색 경로 전체를 한 조건으로 덮습니다.
+
+---
+
+## 5. 권고 신규 가드
+
+| ID | 단언 | 공허 통과 방지 | 잡아내는 회귀 |
+|---|---|---|---|
+| **D-31** 🔄 | `deploy/gitea-ci.yml` 을 YAML 파싱 → 각 잡의 `run` 블록을 합쳐 `pytest` 또는 `tests/` 가 등장하면 **테스트 수행 잡**으로 판정 → 그 잡의 모든 `actions/checkout` 스텝이 `with.submodules` 를 truthy 로 가질 것. **`.gitmodules` 가 존재할 때만 활성**(서브모듈 제거 시 자동 무력화) | **테스트 수행 잡이 0건이면 FAIL** — 잡 이름 변경이나 래퍼 스크립트로 `pytest` 를 숨겨 가드를 조용히 비활성화하는 경로를 차단 | S-1 재발. 린트 잡은 검사 대상에서 제외되므로 경량 워크플로 추가를 방해하지 않음(A-2) |
+| **D-32** | `MESSAGING.md` 가 문서화한 `MQTT_*` 집합 ⊇ `mqtt_common.broker_config_from_env` 가 파싱하는 집합 | 코드에서 변수 0개 추출 시 FAIL | S-4 재발. D-11 이 `PRIVATE_SERVER.md` 에 대해 하는 검사를 `MESSAGING.md` 로 확장 |
+
+**D-31 구현 주의**: PyYAML 은 `on:` 을 불리언 `True` 키로 파싱합니다(V-22). `d["jobs"]` 만 읽으면 무해하나 `d["on"]` 접근은 `KeyError` 입니다. 현재 상태에서 이 가드는 `test` 잡 1개를 대상으로 삼고 **즉시 FAIL** 합니다(`with` = `None`) — 착수 시점에 공허 통과가 아님이 자동 증명됩니다.
+
+**뮤테이션 수용 기준**: ① `test` 잡의 `submodules: recursive` 제거 → D-31 FAIL. ② `test` 잡 이름을 `verify` 로 변경 → **여전히 FAIL 해야 함**(`run` 내용 기준 판정). ③ `pytest tests/ -q` 를 `bash deploy/run-tests.sh` 로 감싸고 `tests/` 문자열 제거 → D-31 이 대상 0건을 만나 **FAIL**(공허 통과 방지 단언). ④ `MESSAGING.md` 에서 `MQTT_PORT` 삭제 → D-32 FAIL.
+
+---
+
+## 6. 열린 질문
+
+| # | 질문 | 기본값(무응답 시) |
+|---|---|---|
+| **Q-1** | `.mam.env` 전환(S-11)이 §9.5 드레인 절차를 밟은 것인가? | 밟지 않은 것으로 간주, T-13 에서 사후 잔여 스캔을 과제로 기록 |
+| **Q-2** | A-2 를 완료로 전환할 시점은? | M3(지문 토픽 + 무조건 토큰) 이후 유지. 사설 브로커 전환만으로는 종결하지 않음 |
+| **Q-3** | `MESSAGING.md` 의 Mosquitto 절을 삭제할 것인가? | **남김**(§1.4 로 강등). `PRIVATE_SERVER.md` §4.2 가 mosquitto 를 여전히 대안으로 제시하므로 삭제하면 두 문서가 어긋남 |
+| **Q-4** | D-31 / D-32 를 이번 커밋에 포함할 것인가? | 포함 권고 |
+| **Q-5** 🆕 | **T-1c 선택지 — `nats-docker` 를 공개로 전환할 것인가?** | **A(공개 전환) 권고**. 추적 파일에 비밀 0건 실측(V-19). 비공개 유지가 정책이면 B(토큰 주입) |
+| **Q-6** 🆕 | B-17 의 접속 지점 거부를 예외로 할 것인가 종료 코드로 할 것인가? | **예외**(`RuntimeError`). `publish_event.py` 는 이미 B-14 로 예외를 잡아 디스크 상태를 동기화한 뒤 rc 를 매핑하므로, 예외가 루프를 멈추지 않고 fail-closed 만 달성 |
+
+---
+
+## 7. 결론
+
+- **테스트**: 충족. 요청 명령 31/31, 전체 306/306, 문서 회귀 0건.
+- **`MESSAGING.md`**: 미충족(S-2, S-3, S-4).
+- **`IMPROVEMENTS.md`**: 미충족(S-5, S-6, S-7).
+- **`implementation_plan.md`**: 부분 충족 — 서브모듈 링크는 갱신되었으나 헤더·트랙표·다이어그램·전환 기록·상태 드리프트 잔존(S-8 ~ S-12).
+- **최우선**: S-1 + S-13. CI 는 서브모듈을 받지 않고, 서브모듈은 비공개이며, 문제를 발현시킬 커밋 2개가 아직 푸시되지 않은 상태입니다. **푸시 이전에 T-1a~T-1c 를 완료하십시오.**
+
+리뷰어 `agy` 의 세 지적은 모두 실재하는 맹점이었고, C2·C3 는 Rev.1 의 처방을 직접 교정했습니다. C1 은 전제가 옳았으나 제시된 상대 URL 형태(`../nats-docker`)가 잘못된 조직을 가리키므로 `../../laa/nats-docker` 로 교정하여 반영했습니다.
+
+[VERDICT: NOT PASS]
@@ -0,0 +1,641 @@
+# 🌐 원격 서버 `nats-server` Docker 프로덕션 배포 계획서 **Rev.2** (Job `b11d499d`)
+
+- **역할**: Planner (`MULTI_AGENT_RULES.md` §1 — 저장소 코드/문서 미변경, 계획서만 산출)
+- **선행 리비전**: Rev.1 = Job `27236ab6`
+- **반영 챌린지**: Job `9a5cb88f` (`agy`) — `[VERDICT: PASS WITH CHALLENGE]`
+- **기준 커밋**: `c6b6c77` (Track 0 완료, **290 tests collected** 실측)
+- **검증 원칙**: 추론이 아닌 **실측**. 챌린지는 지시가 아니라 **가설**로 취급하여 재현·반증했습니다.
+
+---
+
+## 0. Rev.2 판정 요약 (Adjudication)
+
+| 챌린지 | 판정 | 요지 |
+|---|---|---|
+| **C1** 계정 격리가 교차 관측을 차단 | 🟡 **부분 인용 — 진단 유효, 귀속 부정확, 두 옵션 모두 결정적 한계 누락** | 계정 격리 사실은 맞음. 다만 "계획이 `HOME` 계정에서 MAM 이벤트 관측을 주장한다"는 귀속은 부정확 — `PRIVATE_SERVER.md:230`이 **정반대를 이미 처방**. 반면 내 Rev.1 config에 관측자 사용자가 **아예 없었던 것**은 실제 결함이므로 수용. **신규 실측**: retained 이벤트는 **MQTT 구독자에게만** 전달되므로 Option A/B 어느 쪽도 "사후 접속 대시보드가 종료 이벤트를 본다"를 만들지 못함 |
+| **C2** `_load_dotenv` 우선순위 | 🟢 **방향 수용 + 근본 결함 재정의 + 신규 결함 1건 발견** | 진짜 결함은 후보 목록이 아니라 **단일 후보 해석**. 그리고 `MAM_ENV_FILE`이 없는 파일을 가리키면 **다른 후보를 하나도 시도하지 않고 공개 브로커로 폴백**(실측) — 제안된 순서로는 고쳐지지 않음 |
+| **C3** `G-D5` 스코핑 | 🟡 **이미 Rev.1에 존재. 단 잔여 지적이 D-1을 강화** | 펜스 한정·오탐 부재 단언은 Rev.1 §6에 이미 명시. **신규 실측**: NATS 렉서는 **인용되지 않은 값에서만** `$VAR`를 해석 → `store_dir: "$HOME/..."`는 리터럴이며 인용 heredoc과 결합 시 **D-1과 동일하게 파손**. G-D5를 2항 검사로 강화 |
+
+**Rev.2 실질 변경 6건**
+1. §A-1에 **`mam_observer` 읽기 전용 사용자**를 명시적으로 추가(Option B 채택 — 저장소 §5.5 처방과 일치).
+2. **retained는 MQTT 전용**이라는 신규 실측을 §1.9로 신설하고 §5.2 브리징 주장의 경계로 명문화.
+3. Option A(export/import)를 **예외 경로**로 문법 검증까지 마쳐 부록에 배치(무조건 채택하지 않는 근거 3건 첨부).
+4. `B-17` 처방을 **first-hit-wins 후보 목록**으로 재정의하고 `MAM_ENV_FILE` 조기 탈출 결함을 추가.
+5. **G-D5를 2항 검사로 강화**(값 + heredoc 구분자), `$VAR` 인용 규칙을 §1.1 각주에 정밀화.
+6. **G-D9 신설** — 문서 config 예제의 subject 리터럴과 `DEFAULT_TOPIC_ROOT` 일치 강제(M3 토픽 전환 시 조용한 파손 차단). 테스트 전망 290 → **297** → 298.
+
+---
+
+## 1. 사전 실측 결과 (Pre-Flight Measurements)
+
+> Rev.1의 D-1 ~ D-5, H-1 ~ H-3은 챌린저가 "Verified 100% accurate"로 승인했습니다. 아래는 요지 유지 + **Rev.2 신규 실측 2건(§1.9, §1.10)** 및 §1.1 각주 정밀화입니다.
+
+### 1.1 D-1 — `store_dir`의 `~`는 확장되지 않는다 (P1)
+
+`PRIVATE_SERVER.md:73`, `:146`이 `store_dir: "~/.local/share/nats/data"`를 지시합니다.
+
+**증거 1 — NATS 설정 파서에 틸드 확장 없음** (`server/opts.go`):
+```go
+case "store", "store_dir", "storedir":
+    opts.StoreDir = mv.(string)      // 문자열 그대로 대입. os.UserHomeDir 호출 없음
+```
+**증거 2 — 인용 heredoc이 셸 확장까지 차단** (실측): `<<'EOF'` → `store_dir: "~/.local/share/nats/data"` 리터럴 유지 / `<<EOF` → `/Users/godopu16/.local/share/nats/data` 전개. 리터럴 `~` 경로에 `mkdir -p` → CWD 아래 `./~` 디렉터리 생성.
+
+**영향**: JetStream 스토리지가 `./~/.local/share/nats/data`에 생성됩니다. MQTT의 `$MQTT_rmsgs`(retained)·`$MQTT_sess`(세션)가 여기 있으므로, 다른 CWD에서 재기동하면 **retained 종료 이벤트가 통째로 사라집니다.**
+
+> [!IMPORTANT]
+> **각주 정밀화 (Rev.2, C3 파생)**: NATS 설정의 `$VAR` 참조는 **인용되지 않은 값에서만** 해석됩니다. 렉서 원문 — *"Check if the **unquoted** string is a variable reference, starting with `$`."* 이며 `lexQuotedString`은 *"It will not interpret any internal contents."* 입니다.
+> 따라서 **`store_dir: "$HOME/..."`는 리터럴 문자열**이며, 인용 heredoc과 결합하면 `./$HOME/.local/share/nats/data`가 만들어져 D-1과 **동일하게 파손**됩니다.
+> 규칙: `$HOME`은 **셸이 전개할 때만**(= 비인용 heredoc 안에서만) 허용. NATS가 해석해야 하는 변수(`password: $MAM_BROKER_PASS`)는 **따옴표를 씌우지 않습니다.**
+
+### 1.2 D-2 — `nats:latest`는 scratch 변형이라 healthcheck를 넣을 수 없다 (P1)
+
+`docker-library/official-images`의 `library/nats`: `SharedTags: 2.14.5, 2.14, 2, latest` @ `Directory: 2.14.x/scratch`. 해당 Dockerfile은 `FROM scratch` + `ENTRYPOINT ["/nats-server"]`. → 셸·wget·curl 부재로 **healthcheck 구현 불가**, 게다가 메이저 경계를 넘나드는 부동 태그.
+
+**교정**: `image: nats:2.12-alpine`. alpine 엔트리포인트가 첫 인자 `-` 감지 시 `nats-server`를 자동 prepend하므로 `command: ["-c", ...]` 라인은 **양쪽 변형에서 동일 동작**(실측):
+```sh
+if [ "$#" -eq 0 ] || [ "${1#-}" != "$1" ]; then set -- nats-server "$@"; fi
+```
+
+### 1.3 D-3 — 무인증 모니터링 포트를 전 인터페이스에 게시 (P1)
+
+현행 `PRIVATE_SERVER.md:120-124`가 `"8222:8222"`, `"8080:8080"`을 0.0.0.0에 게시합니다. NATS 공식 문서: *"The monitoring port is unauthenticated by default."* → `/varz`·`/connz`·`/jsz`·`/routez` 공개. 8080은 `no_tls: true` 평문.
+
+### 1.4 D-4 — TLS 사용 시 호스트명 검증이 강제된다 (P1)
+
+`make_client()`는 `tls_set(...)`만 호출하고 `tls_insecure_set()`을 부르지 않습니다. 실측(paho 2.1.0): `check_hostname=True`, `verify_mode=CERT_REQUIRED`, `_tls_insecure=False`, 우회 env **없음**.
+
+| 시나리오 | 결과 |
+|---|---|
+| **A)** IP 호스트 + 정확한 CA 번들 핀 | `IP address mismatch, certificate is not valid for '127.0.0.1'` |
+| **B)** 사설 CA + `MQTT_CA_CERTS` 미설정 | `self signed certificate` |
+| **C)** `MQTT_TLS=0`으로 TLS 포트 접속 | **`CONNECTED (handshake ok)`** ← 소켓만 열림 |
+
+→ (1) TLS 시 `MQTT_BROKER`는 **인증서 SAN의 DNS 이름** 필수(IP 금지). (2) 사설 CA면 `MQTT_CA_CERTS` 필수, Let's Encrypt면 **비워 둘 것**. (3) **소켓 연결 성공은 브로커 정상의 증거가 아님** — 검증은 CONNACK 또는 `/healthz`까지 도달해야 함.
+
+### 1.5 D-5 — 환경변수 템플릿 양방향 드리프트 (P2)
+
+`deploy/install.sh:521-522`가 `MQTT_RETRY_INTERVAL=2`, `MQTT_MAX_RETRIES=5`를 `.mam.env`에 **활성 기본값**으로 기록하지만 **읽는 코드 0건**. 실제 재시도는 `--attempts`(기본 3) + `with_retry(base_delay=0.5, factor=2.0, max_delay=8.0)`. 역으로 코드가 읽는 `MQTT_KEEPALIVE`(기본 60)는 `.mam.env.example`에 **0건**.
+
+### 1.6 H-1 — freeze 경로의 조용한 공개 브로커 회귀 (P1)
+
+`_load_dotenv()`는 `__file__`에서 위로 올라가다 `.agents` 또는 `.git`에서 멈춥니다. freeze 스냅샷 루트는 `.agents`만 담고 `.mam.env`는 없습니다(실측: `ls` 결과 `.agents` 단 하나).
+
+| # | 조건 | 해석된 브로커 |
+|---|---|---|
+| 1 | 저장소 경로 스크립트, `MAM_ENV_FILE` 없음 | `nats.example.internal:8883 tls=True` ✅ |
+| 2 | **freeze 경로, `MAM_ENV_FILE` 없음** | **`broker.hivemq.com:1883 tls=False`** ❌ |
+| 3 | freeze 경로 + `MAM_ENV_FILE` | `nats.example.internal:8883 tls=True` ✅ |
+
+정상 루프는 `run_loop.sh:106`의 `export MAM_ENV_FILE=...`으로 보호되나, **위임 브리프가 배포하는 명령줄은 freeze 경로를 직접 가리킵니다.**
+
+### 1.7 H-2 — 잡 레코드가 브로커를 핀 고정 (P1)
+
+`registry.py:73-74`가 등록 시점 브로커 블록을 스냅샷하고 `broker_config_from_job()`이 env보다 **우선** 적용합니다. → `.mam.env` 교체만으로는 기존 pending/running 잡이 전환되지 않습니다.
+
+### 1.8 H-3 — 비밀번호 평문 보관 / 자동 토큰 발급 이득 (P2)
+
+레코드에 `"password": "SUPERSECRET123"` 평문 확인(모드 0600, `.gitignore:14`에 `.mam/`). 동시에 **`tls` 또는 `username` 감지 시 `auth_token` 자동 발급** 확인 → 원격 인증 전환이 곧 HMAC 자동 활성화이며 `B-16`/`G-11` 위험을 대부분 부수 해소.
+
+### 1.9 🆕 **N-1 — retained 메시지는 MQTT 구독자에게만 전달된다** (P1, C1 파생 신규 실측)
+
+챌린저의 C1은 계정 경계만 다뤘으나, **계정 문제를 어떻게 풀든 바뀌지 않는 더 근본적인 경계**가 있습니다.
+
+`server/mqtt.go` 실측 — retained 전달은 **MQTT SUBSCRIBE 처리 경로에서만** 호출됩니다:
+```go
+case mqttPacketSub:                       // ← MQTT SUBSCRIBE 패킷 처리
+    ...
+    c.mqttEnqueueSubAck(pi, filters)
+    c.mqttSendRetainedMsgsToNewSubs(subs) // ← 여기서만 호출
+
+func (c *client) mqttSendRetainedMsgsToNewSubs(subs []*subscription) {
+    for _, sub := range subs {
+        if sub.mqtt != nil && sub.mqtt.prm != nil { ... }   // ← MQTT 구독에만 존재하는 필드
+    }
+}
+```
+
+**결론**: NATS 네이티브 구독자와 WebSocket(NATS) 구독자는 **retained 메시지를 절대 받지 못합니다.** 계정을 합치든(Option B), export/import를 걸든(Option A) 이 사실은 변하지 않습니다.
+
+**MAM에 주는 구체적 의미**:
+- `publish_event.py`는 `retain = args.retained or args.event in TERMINAL_EVENTS` — 즉 **종료 이벤트가 정확히 retained 대상**입니다.
+- 잡이 끝난 **뒤에** 접속한 NATS/WebSocket 대시보드는 **그 잡의 종료 이벤트를 보지 못합니다.** 라이브 스트리밍만 가능합니다.
+- `PRIVATE_SERVER.md` §5.2의 *"즉시 실시간 수신"* 주장은 **라이브 구간에 한정**해야 정확합니다.
+
+**대시보드가 사후 상태까지 알아야 한다면 선택지는 2개뿐**:
+1. 대시보드를 **MQTT로** 붙인다(같은 `nats-server`의 1883 리스너 사용, retained 그대로 수신).
+2. §5.3의 **JetStream 리플레이 스트림을 옵트인**한다(`python.mqtt.jobs.>` 구독 스트림 + `max_age`/`max_bytes` 상한 필수).
+
+이 두 갈래를 §5.2 개정안과 §A-1 주석에 명시합니다.
+
+### 1.10 🆕 **H-4 — `MAM_ENV_FILE`이 없는 파일을 가리키면 모든 폴백이 무력화된다** (P1, C2 파생 신규 실측)
+
+`_load_dotenv()` 도입부:
+```python
+explicit_file = os.environ.get("MAM_ENV_FILE")
+if explicit_file:
+    if os.path.isfile(explicit_file):
+        _parse_env_file(explicit_file)
+    return                      # ← 파일이 없어도 여기서 종료. 다른 후보를 시도하지 않음
+```
+실측:
+
+| 조건 | 해석된 브로커 |
+|---|---|
+| `MAM_ENV_FILE=<오타/이동된 경로>`, 저장소 경로 스크립트 | **`broker.hivemq.com tls=False`** ❌ |
+| `MAM_ENV_FILE=<정상 경로>` (대조군) | `nats.private.internal tls=True` ✅ |
+| freeze 경로 스크립트, cwd = 실제 저장소, env 없음 | **`broker.hivemq.com tls=False`** ❌ |
+
+**중요**: 챌린저가 제안한 우선순위 재배열(`MAM_ENV_FILE → MAM_REAL_ROOT → …`)은 **이 경로를 고치지 못합니다.** 1순위에서 이미 `return`으로 탈출하기 때문입니다. 근본 결함은 순서가 아니라 **단일 후보 해석**입니다(§8 `B-17` 재정의).
+
+세 번째 행은 챌린저의 `os.getcwd()` 도입 근거가 **실측으로 타당함**을 보여줍니다.
+
+---
+
+## 2. §A — `PRIVATE_SERVER.md` 개정안: §9 「원격 서버 프로덕션 배포」 신설
+
+### A-1. 프로덕션 `nats.conf` (**Rev.2 — 관측자 사용자 추가**)
+
+```conf
+# nats.conf — 원격 프로덕션 (컨테이너 내부 절대경로 기준)
+server_name: mam-hub
+
+# ── JetStream: MQTT retained/QoS1 저장소. MAM 종료 이벤트 재수신이 여기에 의존 ──
+jetstream {
+  store_dir: "/data"          # D-1: 절대경로. '~' 도, 인용된 "$HOME" 도 확장되지 않음
+  max_file: 10G
+  max_mem: 256M
+}
+
+http_port: 8222               # D-3: 호스트 게시는 loopback 한정 (§A-3)
+
+mqtt {
+  port: 1883                  # 공개 TLS 모델에서는 8883 + tls 블록 (§B-3)
+  ack_wait: 60s               # WAN RTT 흡수 (기본 30s)
+  max_ack_pending: 1024       # 기본 100 → 다중 에이전트 동시 발행 여유
+}
+
+websocket {
+  port: 8080
+  no_tls: true                # 사설망/tailnet 한정
+}
+
+# ── 인증 및 멀티테넌시 (Rev.2: C1 반영) ────────────────────────────────
+accounts {
+  MAM: {
+    jetstream: enabled                      # MQTT 내부 스트림이 이 계정 안에 생성됨
+    users: [
+      # 발행자 겸 구독자 — MAM 에이전트 본체
+      { user: mam_agent, password: $MAM_BROKER_PASS }
+
+      # 관측자 — 대시보드/모니터링. PRIVATE_SERVER.md §5.5 의 '동일 계정 배치' 처방
+      { user: mam_observer, password: $MAM_OBSERVER_PASS,
+        permissions: {
+          subscribe: { allow: ["python.mqtt.jobs.>"] }   # M3 이후: "mam.<fp>.jobs.>"
+          publish:   { deny:  [">"] }
+        }
+      }
+    ]
+  }
+  # MAM 과 무관한 홈랩 서비스 전용. MAM subject 는 보이지 않음(의도된 격리)
+  HOME: { jetstream: enabled, users: [ { user: home, password: $HOME_BROKER_PASS } ] }
+  SYS:  { users: [ { user: sys, password: $SYS_BROKER_PASS } ] }
+}
+system_account: SYS
+```
+
+> [!IMPORTANT]
+> **관측자는 반드시 `MAM` 계정 안에 둡니다.** NATS 계정은 하드 격리 경계이므로 `user: home`(계정 `HOME`)으로 접속한 클라이언트는 `python.mqtt.jobs.>`를 구독해도 **0건**을 받습니다. 이는 `PRIVATE_SERVER.md:230` §5.5가 이미 처방한 배치("MAM과 이를 관측하는 대시보드는 동일한 계정(`MAM`)에 배치")와 정확히 일치합니다. 서로 다른 신뢰 도메인이라 계정을 반드시 갈라야 하는 예외 상황은 **부록 X(Option A)** 를 따르십시오.
+
+> [!WARNING]
+> **관측자가 받는 것과 받지 못하는 것 (§1.9 N-1)**
+> - ✅ 잡 실행 **중** 발생하는 모든 이벤트 (라이브 스트리밍)
+> - ❌ **이미 끝난 잡의 retained 종료 이벤트** — retained 는 **MQTT 구독자에게만** 전달됩니다. NATS/WebSocket 대시보드는 접속 이전 상태를 재구성하지 못합니다.
+> - 사후 상태가 필요하면 대시보드를 **MQTT(1883)로** 붙이거나 §5.3의 **JetStream 리플레이 스트림을 옵트인**하십시오.
+
+> [!NOTE]
+> **계정별 JetStream 활성화는 필수**입니다. MQTT는 접속 계정 안에 `$MQTT_sess`·`$MQTT_rmsgs`·`$MQTT_out` 스트림을 만듭니다. 계정에 JetStream이 없으면 `JetStream not enabled for account`(ErrCode 10039, HTTP 503)로 실패합니다. 전역 요건도 별도로 존재합니다 — `mqtt requires JetStream to be enabled if running in standalone mode` (`mqtt.go:234`).
+> *다계정 구성에서의 계정별 요구는 스트림 생성 경로로부터의 추론이며, 위 처방은 fail-safe입니다. **M2b 스파이크 R-4에서 확인 항목으로 지정**합니다.*
+
+### A-2. 프로덕션 `docker-compose.yml`
+
+```yaml
+services:
+  nats:
+    image: nats:2.12-alpine          # D-2: latest(=scratch)는 healthcheck 불가
+    container_name: mam-nats
+    restart: unless-stopped
+    command: ["-c", "/etc/nats/nats.conf"]
+    environment:
+      # 미해결 $VAR 는 파싱 에러 → 시크릿 누락 시 '기동 실패'로 fail-closed
+      MAM_BROKER_PASS:   ${MAM_BROKER_PASS:?set in .env}
+      MAM_OBSERVER_PASS: ${MAM_OBSERVER_PASS:?set in .env}
+      HOME_BROKER_PASS:  ${HOME_BROKER_PASS:?set in .env}
+      SYS_BROKER_PASS:   ${SYS_BROKER_PASS:?set in .env}
+    ports:
+      - "${MQTT_BIND:-127.0.0.1}:1883:1883"
+      - "127.0.0.1:8222:8222"                  # D-3: 무인증 모니터링은 loopback 한정
+      - "${WS_BIND:-127.0.0.1}:8080:8080"
+    volumes:
+      - ./nats.conf:/etc/nats/nats.conf:ro
+      - nats-data:/data
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8222/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+volumes:
+  nats-data:
+```
+
+> [!WARNING]
+> **Docker의 published 포트는 UFW를 우회합니다.** Docker가 삽입하는 NAT/FORWARD 규칙이 `ufw`의 INPUT 체인보다 먼저 평가되므로, `ufw deny 1883`을 걸어도 `-p 1883:1883`으로 게시한 포트는 인터넷에 열립니다. 본 계획이 방화벽 대신 **published 포트 자체에 바인드 주소를 명시**하는 이유입니다.
+
+### A-3. 포트 노출 매트릭스
+
+| 포트 | 용도 | Tailscale 모델 (권장) | 공개 TLS 모델 | 절대 금지 |
+|---|---|---|---|---|
+| 1883 | MQTT 평문 | tailnet IP 바인드 | ✖ 미게시 | 0.0.0.0 게시 |
+| 8883 | MQTT TLS | (불필요) | `0.0.0.0` + LE 인증서 | 인증 없이 게시 |
+| 4222 | NATS 네이티브 | tailnet IP 바인드 | 미게시(또는 TLS+인증) | 0.0.0.0 평문 |
+| 8222 | HTTP 모니터링 | **`127.0.0.1` 한정** | **`127.0.0.1` 한정** | 어떤 경우에도 공개 |
+| 8080 | WebSocket(`no_tls`) | tailnet IP 바인드 | 미게시 | 공개 인터페이스 게시 |
+
+### A-4. 🆕 `PRIVATE_SERVER.md` §5.2 개정 (N-1 반영)
+
+기존 §5.2 문장 *"웹 브라우저나 타 프로젝트의 NATS 구독자는 … 즉시 실시간 수신할 수 있습니다"* 에 다음 경계를 병기합니다.
+
+```markdown
+- **경계 (필수 인지)**: 교차 프로토콜 브리징은 **라이브 스트리밍에 한정**됩니다. MQTT의
+  retained 메시지는 MQTT 구독자에게만 전달되므로(`mqttSendRetainedMsgsToNewSubs`가
+  MQTT SUBSCRIBE 경로 전용), 잡이 끝난 뒤 접속한 NATS/WebSocket 대시보드는 그 잡의
+  **종료 이벤트를 수신하지 못합니다**. 사후 상태가 필요하면 (a) 대시보드를 MQTT(1883)로
+  연결하거나 (b) §5.3 JetStream 리플레이 스트림을 옵트인하십시오.
+- **계정 배치**: 관측 클라이언트는 §5.5 처방대로 `MAM` 계정 안의 읽기 전용 사용자
+  (`mam_observer`)로 접속해야 합니다. 다른 계정에서는 subject 가 보이지 않습니다.
+```
+
+---
+
+## 3. §B — 원격 네트워킹 & 보안 가이드
+
+### B-1. 노출 모델 3안 비교 및 권고
+
+| 항목 | 🏆 **모델 T: Tailscale/WireGuard 오버레이** | 모델 P: 공개 TLS (Let's Encrypt) | 모델 S: SSH 터널 |
+|---|---|---|---|
+| 인터넷 노출 면적 | **0** | 8883 1개 | 0 |
+| 인증서 필요 | 불필요 (`MQTT_TLS=0`) | 필수 + 90일 갱신 | 불필요 |
+| **D-4 호스트명 제약** | **해당 없음** | 도메인 필수, IP 불가 | 해당 없음 |
+| 도메인 필요 | 불필요 | **필수** | 불필요 |
+| 이동성 | 자동 | 자동 | 터널 수동 관리 |
+| 장애 지점 | tailnet 코디네이터 | certbot 갱신 실패 | SSH 세션 |
+
+**권고: 모델 T.** 근거 — (1) D-4의 도메인·SAN 제약을 소거, (2) D-3의 모니터링/WS 노출을 구조적으로 제거, (3) 롤백이 `.mam.env` 한 줄, (4) MAM은 **관측 사이드카**이므로(제어 평면은 `wait_for_job` 파일 폴링) 오버레이 지연이 오케스트레이션 정확성에 영향을 주지 않음.
+
+### B-2. 방화벽 (UFW) — 2차 방어선
+
+```bash
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+sudo ufw allow 22/tcp
+
+# 모델 T: tailnet 인터페이스만 허용
+sudo ufw allow in on tailscale0 to any port 1883 proto tcp
+sudo ufw allow in on tailscale0 to any port 4222 proto tcp
+sudo ufw allow in on tailscale0 to any port 8080 proto tcp
+
+# 모델 P: 8883만 공개
+# sudo ufw allow 8883/tcp
+# sudo ufw allow 80/tcp          # certbot HTTP-01 챌린지 기간 한정
+
+sudo ufw enable && sudo ufw status verbose
+```
+**Docker 우회 대응(필수)** — compose 옆 `.env`에 바인드 주소를 주입하고 실제 바인딩을 단언합니다:
+```bash
+MQTT_BIND=100.x.y.z          # tailscale ip -4
+WS_BIND=100.x.y.z
+```
+```bash
+sudo ss -lntp | grep -E ':(1883|4222|8222|8080)\b'
+# 기대: 8222 는 127.0.0.1 에만, 1883/8080 은 tailnet IP 에만
+```
+
+### B-3. 모델 P 전용 — TLS / Certbot
+
+```bash
+sudo certbot certonly --standalone -d mam-broker.example.com
+
+# nats.conf 의 mqtt 블록:
+#   mqtt {
+#     port: 8883
+#     tls {
+#       cert_file: "/etc/letsencrypt/live/mam-broker.example.com/fullchain.pem"
+#       key_file:  "/etc/letsencrypt/live/mam-broker.example.com/privkey.pem"
+#     }
+#   }
+# compose 볼륨: live/ 는 archive/ 로의 심볼릭 링크 → /etc/letsencrypt 전체를 마운트
+#   - /etc/letsencrypt:/etc/letsencrypt:ro
+
+sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nats.sh >/dev/null <<'SH'
+#!/bin/sh
+docker compose -f /srv/mam-nats/docker-compose.yml kill -s HUP nats
+SH
+sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nats.sh
+sudo certbot renew --dry-run
+```
+**클라이언트 규칙 (D-4)**: `MQTT_BROKER`는 **도메인**(IP 금지). Let's Encrypt 사용 시 `MQTT_CA_CERTS`는 **설정하지 않음**. 사설 CA일 때만 지정하고 SAN에 접속명을 반드시 포함.
+
+### B-4. 사용자 인증 및 시크릿 주입
+
+```bash
+openssl rand -base64 32          # 계정/사용자별로 각각 생성 (mam_agent, mam_observer, home, sys)
+chmod 600 .env
+```
+NATS 파서는 미해결 `$VAR`를 **에러**로 처리하므로 시크릿이 비면 서버가 조용히 익명으로 뜨지 않고 **기동에 실패**합니다(fail-closed, 의도적 채택).
+
+**H-3 완화 규칙**: (1) `MQTT_PASSWORD`는 사람이 재사용하는 암호가 아니라 **기계 생성 토큰**만 사용(레코드에 평문으로 남음). (2) 회전 시 서버 `.env` → `docker compose up -d` → 클라이언트 `.mam.env` → **잔여 잡 레코드 정리**(§C-3과 동일 절차). (3) 장기 과제는 `B-18`.
+
+**권한 격리**: `mam_agent`는 발행/구독, `mam_observer`는 `publish: { deny: [">"] }`로 **발행 전면 금지**. 이는 A-2(외부 악의적 이벤트 주입) 대응과 같은 방향이며, HMAC(`auth_token`)과 이중 방어를 이룹니다.
+
+---
+
+## 4. §C — 클라이언트 설정 및 원격 검증 플레이북
+
+### C-1. `.mam.env` (모델별)
+
+```bash
+# ── 모델 T (Tailscale, 권장) ──────────────────────────────────
+MQTT_BROKER="mam-hub.tailXXXX.ts.net"   # 또는 100.x.y.z (평문이므로 IP 가능)
+MQTT_PORT=1883
+MQTT_TLS=0
+MQTT_USERNAME=mam_agent
+MQTT_PASSWORD=<기계 생성 토큰>
+MQTT_KEEPALIVE=60                        # D-5: 코드가 실제로 읽는 값. 템플릿에 추가 필요
+
+# ── 모델 P (공개 TLS) ────────────────────────────────────────
+# MQTT_BROKER="mam-broker.example.com"   # D-4: 인증서 SAN 의 DNS 이름. IP 금지
+# MQTT_PORT=8883
+# MQTT_TLS=1
+# MQTT_CA_CERTS 는 Let's Encrypt 사용 시 '설정하지 않음'
+```
+> **D-5 교정**: `MQTT_RETRY_INTERVAL` / `MQTT_MAX_RETRIES`는 어떤 코드도 읽지 않습니다. 템플릿에서 제거하거나 "미사용(historical)"로 강등하고, 재시도 조정은 `publish_event.py --attempts`임을 명시. 역으로 `MQTT_KEEPALIVE`는 추가.
+
+### C-2. 원격 검증 플레이북 (R-1 ~ **R-10**)
+
+| ID | 검증 항목 | 방법 | 통과 기준 |
+|---|---|---|---|
+| **R-1** | 브로커 헬스 | SSH 터널 후 `curl -sf http://127.0.0.1:8222/healthz` | **HTTP 200** |
+| **R-2** | 리스너 + TLS 신원 | `curl -s .../varz \| grep -i mqtt`; 모델 P는 `openssl s_client -connect H:8883 -servername H` | MQTT 리스너 노출, SAN에 `MQTT_BROKER` 포함 |
+| **R-3** | 노출 면적 단언 | 외부 망에서 `nmap -Pn -p 1883,4222,8222,8080 <공개IP>` | 전부 closed/filtered |
+| **R-4** | 왕복 pub/sub + 계정 JetStream | 임시 잡 등록 → 구독자 기동 → `progress` 발행 → 수신 → 종결 | 수신 성공, `JetStream not enabled for account` **미발생** |
+| **R-5** | **retained 종료 이벤트 (MQTT)** | `--event completed` 발행 **후** 신규 `job_subscriber.py` 기동 | 즉시 최종 이벤트 수신 |
+| **R-6** | 브로커 신원 단언 | `grep -c 'broker.hivemq.com' .mam/delegate_job_logs/$JID/events.ndjson` | **0**, 원격 호스트 등장 |
+| **R-7** | freeze 회귀 (H-1/H-4) | freeze 경로 `publish_event.py`를 `MAM_ENV_FILE` 없이 실행 / 그리고 오타 경로로 실행 | 공개 브로커로 나가지 않음 — **현재는 양쪽 다 실패가 기대값**이며 `B-17`의 근거 |
+| **R-8** | 전체 회귀 스위트 | `.venv/bin/python -m pytest tests/ -q` | 현재 기준 **290 passed** |
+| 🆕 **R-9** | **관측자 계정 경계** | `mam_observer`로 NATS 구독 → 이벤트 수신 확인. 이어서 `home`(계정 HOME)으로 동일 구독 | `mam_observer` **수신**, `home` **0건** (= 격리 정상) |
+| 🆕 **R-10** | **N-1 retained 경계 확인** | 잡 종료 **후** NATS 네이티브 구독자를 새로 붙임 | **0건 수신**이 정상. 수신되면 N-1 전제가 틀린 것이므로 §A-4 문구 재작성 |
+
+> R-9/R-10은 챌린지 C1이 제기한 계정 문제와, 그보다 근본적인 retained 경계를 **각각 실증**합니다. 특히 R-10은 **반증 가능한 형태**로 설계되어 있습니다.
+
+**R-4 구체 절차**:
+```bash
+JID=$(.venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py \
+        --registry-dir .mam/jobs \
+        register --prompt "remote broker connectivity test" --agent-session "herdr:test")
+
+.venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/publish_event.py \
+  --registry-dir .mam/jobs --job "$JID" --event progress --detail "remote broker verified" -v
+
+.venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py \
+  --registry-dir .mam/jobs status --job "$JID" --set completed   # 유령 잡 방지
+```
+> `--registry-dir`는 **부모 파서 인자**이므로 서브커맨드 앞에 옵니다. `register`에는 `--job-id`가 없어 ID는 stdout에서 캡처합니다(실측 확인).
+
+**지연 측정**:
+```bash
+.venv/bin/python - <<'PY'
+import sys, time, statistics
+sys.path.insert(0, '.agents/skills/multi-agent-mux-delegate-job/scripts')
+import mqtt_common as m
+cfg = m.broker_config_from_env()
+print(f"target: {cfg.host}:{cfg.port} tls={cfg.tls}")
+conn, rtt = [], []
+for _ in range(5):
+    c = m.make_client("latency", cfg)
+    t0 = time.perf_counter(); c.connect(cfg.host, cfg.port, 10); c.loop_start()
+    conn.append((time.perf_counter() - t0) * 1000)
+    t1 = time.perf_counter()
+    info = c.publish("mam/latency/probe", b"x", qos=1); info.wait_for_publish(10)
+    rtt.append((time.perf_counter() - t1) * 1000)
+    c.loop_stop(); c.disconnect()
+print(f"connect  p50={statistics.median(conn):.1f}ms max={max(conn):.1f}ms")
+print(f"qos1 rtt p50={statistics.median(rtt):.1f}ms max={max(rtt):.1f}ms")
+PY
+```
+**판정**: QoS1 RTT p50 > 200ms면 `mqtt.ack_wait` 상향, > 1s면 오버레이 경로(릴레이 폴백) 점검. `with_retry` 백오프가 0.5s→1s→2s이므로 수백 ms RTT에서는 재시도 없이 통과해야 정상입니다.
+
+### C-3. 전환(Cutover) 절차 — H-2 대응
+
+```
+[1 드레인] ──> [2 잔여 스캔] ──> [3 .mam.env 교체] ──> [4 R-1~R-10] ──> [5 레거시 차단]
+```
+1. **드레인**: 신규 위임 중단, 진행 중 잡이 모두 terminal 될 때까지 대기.
+2. **잔여 스캔** — 옛 브로커에 핀 고정된 레코드 확인:
+   ```bash
+   .venv/bin/python - <<'PY'
+   import json, glob
+   for p in sorted(glob.glob('.mam/jobs/*.json')):
+       d = json.load(open(p))
+       if d.get('status') not in ('completed', 'error', 'cancelled'):
+           b = d.get('broker') or {}
+           print(f"{d.get('job_id')}  status={d.get('status'):<9} broker={b.get('host')}:{b.get('port')}")
+   PY
+   ```
+   출력이 비어야 3단계 진입. 남으면 종결 처리하거나 `broker` 블록을 마이그레이션.
+3. `.mam.env` 교체 — **코드 변경 0줄.**
+4. R-1 ~ R-10 전건 통과.
+5. 레거시 차단: 공개 브로커 주소가 활성 기본값으로 남지 않도록 `.mam.env` / `deploy/install.sh` 점검.
+
+---
+
+## 5. §D — `implementation_plan.md` 개정안
+
+### D-a. M2 분할
+
+| 마일스톤 | 이름 | DoD | 게이트 |
+|---|---|---|---|
+| M0 | 문서 정합성 | (완료) | (통과, 290 실측) |
+| M1 | Track 0 내결함성 | (완료 — `c6b6c77`) | (통과) |
+| **M2a** | 로컬 스파이크 (Track 1) | 격리 클론에서 S-1 ~ S-9 완수 | S-3 retained 통과 |
+| **M2b** | 원격 프로덕션 전환 (Track 1R) | D-1~D-5 교정 + §A/§B 배포 + §C-3 전환 | **R-3 · R-5 · R-6 · R-9 동시 통과**, R-7·R-10 결과 기록 |
+| M3 | Track 2 보안 | A-2 지문 토픽, G-11 | 지문 토픽 확인 후 레거시 구독 제거 **+ 관측자 권한/Export subject 동시 갱신** |
+| M4 | Track 3 동기화 | 문서/배포 정합 | 전체 스위트 Green |
+
+> **M2b 진입 선행 조건**: D-1 ~ D-5 교정이 `PRIVATE_SERVER.md`에 반영되고 신규 가드가 통과해야 합니다. 교정 전 배포는 D-1(스토리지 유실)·D-2(healthcheck 불가)·D-3(모니터링 공개)·D-4(TLS 접속 불가)로 **반드시 실패**합니다.
+
+> 🆕 **M3에 추가된 결합 항목**: 토픽 루트가 `python/mqtt/jobs/…` → `mam/<fp>/jobs/…`로 바뀌면 §A-1의 `mam_observer.subscribe.allow`와 (Option A 채택 시) export subject가 **조용히 매칭 실패**합니다. 가드 `G-D9`가 이를 기계적으로 강제합니다.
+
+### D-b. Track 1R (신설)
+
+| 트랙 | 대상 | 목표 | 변경 지점 |
+|---|---|---|---|
+| **Track 1R** | 원격 배포 | VPS/홈랩 `nats-server` 상시 가동 및 MAM 전환 | `PRIVATE_SERVER.md` §9/§5.2, 서버측 `nats.conf`·`docker-compose.yml`, `.mam.env` |
+
+### D-c. M2b 단계별 로드맵
+
+```
+[P0 교정]      D-1~D-5 문서 교정 + §5.2 경계 명문화 + 신규 가드 7종
+   ▼
+[P1 서버 준비] VPS/홈랩 프로비저닝, Docker, Tailscale 가입
+   ▼
+[P2 배포]      nats.conf + compose 기동, healthcheck healthy 확인
+   ▼
+[P3 잠금]      바인드 주소 한정 + UFW + ss/nmap 로 노출 면적 0 단언 (R-3)
+   ▼
+[P4 전환]      드레인 → 잔여 스캔 → .mam.env 교체 (§C-3)
+   ▼
+[P5 검증]      R-1 ~ R-10. R-5(retained) / R-9(계정 경계) 를 최종 관문으로
+   ▼
+[P6 상시화]    로그 로테이션, JetStream 볼륨 백업, healthcheck 알림
+```
+**P6 최소 요건**: `nats-data` 볼륨 주기 스냅샷(**retained 종료 이벤트가 여기 있음 — 볼륨 유실 = 이벤트 유실**), healthcheck 상태 감시, JetStream 리플레이 스트림 사용 시 `max_age`/`max_bytes` 상한 필수.
+
+### D-d. 체크리스트
+
+```markdown
+### M2b: 원격 프로덕션 전환 (Track 1R)
+- [ ] D-1 store_dir 절대경로 교정 + 비인용 heredoc (PRIVATE_SERVER.md:73, :146)
+- [ ] D-2 이미지 핀 nats:2.12-alpine + /healthz healthcheck
+- [ ] D-3 8222/8080 바인드 주소 한정
+- [ ] D-4 TLS 절의 IP 예시 제거 및 DNS/SAN 요건 명시
+- [ ] D-5 .mam.env.example 정합 (MQTT_KEEPALIVE 추가 / RETRY·MAX_RETRIES 강등)
+- [ ] N-1 §5.2 에 retained=MQTT 전용 경계 명문화 + §A-1 mam_observer 추가
+- [ ] 신규 가드 G-D5(강화) ~ G-D9, G-R1, G-R2 구현 및 mutation 확인 (290 → 297)
+- [ ] 서버 배포 및 R-3 노출 면적 0 단언
+- [ ] §C-3 드레인·잔여 스캔 후 .mam.env 전환
+- [ ] R-1 ~ R-10 전건 통과 (R-5 / R-9 최종 관문)
+```
+
+---
+
+## 6. 회귀 가드 (7종) — `tests/test_deploy_freshness.py::test_d7` 계보
+
+| ID | 가드 내용 | 변이 검출 기준 (Mutation) |
+|---|---|---|
+| **G-D5** 🔺강화 | **2항 검사**: (i) 펜스 블록 내 모든 `store_dir:` 값이 `/`로 시작하는 절대경로, (ii) 해당 값을 기록하는 heredoc 구분자가 **비인용**(`<<EOF`). `$HOME`은 비인용 heredoc 안에서만 허용 | `~/.local/...` 복원 시 FAIL **그리고** `<<'EOF'` + `"$HOME/..."` 조합 도입 시에도 FAIL |
+| **G-D6** | 문서 내 모든 `nats:` 이미지 참조가 `latest`가 아니고 `-alpine` 포함 | `nats:latest` 복원 시 FAIL |
+| **G-D7** | compose 예제의 `8222` 게시 항목이 `127.0.0.1:` 접두를 가짐 | `"8222:8222"` 복원 시 FAIL |
+| **G-D8** | `MQTT_TLS=1`이 등장하는 예제 블록 안의 `MQTT_BROKER` 값이 IP 리터럴이 아님 | `MQTT_BROKER="192.168.1.100"` + TLS 조합 복원 시 FAIL |
+| 🆕 **G-D9** | 문서 config 예제의 subject 리터럴(`mam_observer.subscribe.allow`, Option A의 export/import subject)이 `mqtt_common.DEFAULT_TOPIC_ROOT`를 점 표기로 변환한 값과 **접두 일치** | `DEFAULT_TOPIC_ROOT`를 `mam/<fp>/jobs`로 바꾸고 문서를 갱신하지 않으면 FAIL |
+| **G-R1** | `run_loop.sh`에 `export MAM_ENV_FILE=` 라인 존재 단언 + `.agents`만 있고 `.mam.env`가 없는 임시 루트에서의 회귀 동작을 명시적으로 고정 | `run_loop.sh:106` export 제거 시 FAIL |
+| **G-R2** | 코드가 읽는 모든 `MQTT_*` 이름이 `.mam.env.example`에 존재(특히 `MQTT_KEEPALIVE`)하고, 코드가 읽지 않는 이름은 활성 기본값으로 기록되지 않음 | `MQTT_KEEPALIVE` 제거 또는 `MQTT_RETRY_INTERVAL=2` 활성 복원 시 FAIL |
+
+**구현 규칙(Rev.1 승계 + C3 반영 확인)**:
+- 문서 가드는 **펜스 코드 블록에 한정**해 스캔하고, 산문 errata(예: *"과거에는 `nats:latest`를 권장했으나…"*)가 오탐되지 않음을 **동반 단언**합니다. — *이 규정은 Rev.1 §6에 이미 있었으며 C3의 요청과 동일합니다. 변경 없이 재확인합니다.*
+- G-D9와 G-R2는 소스에서 값을 **정적으로 수집**해 문서와 대조합니다(브로커 접속 없음).
+
+**테스트 수 전망**: 290 (현재 실측) → **297** (G-D5 강화 + G-D6~G-D9, G-R1, G-R2) → **298** (M3의 G-11).
+
+---
+
+## 7. 롤백 전략
+
+| 실패 지점 | 롤백 | 비용 |
+|---|---|---|
+| R-5 retained 실패 | `.mam.env`의 `MQTT_BROKER`만 `eclipse-mosquitto`로 교체 | 코드 0줄, 즉시 |
+| R-9 계정 경계 실패 | `mam_observer` 권한 블록만 수정, MAM 본체 무영향 | 서버 설정 1곳 |
+| 원격 링크 불안정 | `.mam.env`를 직전 값으로 원복 | 코드 0줄 |
+| 서버 전소 | Track 0 덕분에 **루프는 계속 완주**(디스크 폴백). 관측만 일시 상실 | 0 |
+| JetStream 볼륨 유실 | retained 종료 이벤트 유실 → 백업 스냅샷 복구 | P6 백업 필요 |
+
+Track 0(`B-14`/`B-15`)은 브로커 제품·위치와 무관한 순이득이므로 롤백하지 않습니다. **원격 전환 전체가 가역적인 이유가 M1 완료 덕분입니다.**
+
+---
+
+## 8. 후속 코드 과제 (Rev.2 재정의)
+
+### B-17 🔺재정의 — `_load_dotenv` 단일 후보 해석 (P1)
+
+> **C2 판정**: 챌린저의 우선순위 목록은 방향이 옳으나, **근본 결함은 순서가 아니라 "루트를 하나만 정하고 끝낸다"는 구조**입니다(§1.10 H-4). 순서만 바꾸면 `MAM_ENV_FILE` 오타 경로에서 여전히 공개 브로커로 폴백합니다.
+
+**처방 — 순서 있는 후보 목록 + 첫 적중 우선(first-hit-wins)**:
+```
+1) $MAM_ENV_FILE            (파일이 실제로 존재할 때만 채택. 부재 시 return 하지 말고 계속 진행)  ← H-4 교정
+2) $MAM_REAL_ROOT           (run_loop.sh:104 가 export)
+3) $WORKSPACE_ROOT          (run_loop.sh:105 가 export)
+4) walk_up(__file__)        (저장소 직접 실행에서 이미 정상 동작함이 실측됨)
+5) walk_up(os.getcwd())     (freeze 경로를 수동 실행하는 경우를 구제 — 챌린저 근거가 실측으로 타당)
+→ 각 후보에서 .mam.env / .env 를 찾고, 첫 적중을 채택
+→ 전부 실패하면 반드시 경고 로그: "no env file found; falling back to public default broker"
+```
+**Rev.1 대비 / 챌린저 제안 대비 차이 3가지**:
+1. `MAM_ENV_FILE` 부재 시 **조기 탈출 제거**(H-4). 챌린저 제안으로는 고쳐지지 않는 경로입니다.
+2. `walk_up(__file__)`을 cwd보다 **앞**에 둡니다. 저장소 직접 실행은 이미 정확히 동작함이 실측되었고, cwd를 앞세우면 **다른 프로젝트의 `.mam.env`를 읽는 교차 오염** 위험만 커집니다(MAM은 다중 프로젝트 사용을 전제).
+3. cwd는 **`walk_up(os.getcwd())`** 로 둡니다. 저장소 하위 디렉터리에서 실행해도 동작해야 하기 때문입니다.
+4. **최종 폴백 경고는 순서와 무관한 안전망**이므로 필수 요건으로 유지합니다. 어떤 순서든 놓칠 수 있습니다.
+
+### B-18 — 잡 레코드 자격증명 평문 보관 (P2)
+
+`to_registry_block()`에서 `password`를 마스킹하거나 레코드 대신 실행 시점 env에서만 해석. `broker_config_from_job()`의 override 우선순위 계약(H-2와 동일 지점)과 함께 재검토.
+
+---
+
+## 9. 부록 X — Option A (계정 간 Export / Import): **예외 경로**
+
+챌린저가 1순위로 제안한 패턴입니다. **기본 채택하지 않으며**, 관측자가 실제로 **다른 신뢰 도메인**에 속할 때만 사용합니다.
+
+**문법 검증 완료** (소스 대조):
+```conf
+accounts {
+  MAM: {
+    jetstream: enabled
+    users: [ { user: mam_agent, password: $MAM_BROKER_PASS } ]
+    exports: [ { stream: "python.mqtt.jobs.>", accounts: [HOME] } ]   # accounts 로 수입자 제한 권장
+  }
+  HOME: {
+    users: [ { user: home, password: $HOME_BROKER_PASS } ]
+    imports: [ { stream: { account: MAM, subject: "python.mqtt.jobs.>" } } ]
+  }
+}
+```
+- `exports: [ { stream: "..." } ]` / `imports: [ { stream: { account: X, subject: "..." } } ]` 문법은 공식 문서와 일치합니다.
+- **`>` 와일드카드는 유효**합니다 — export subject는 `IsValidSubject`로 검증되며(`opts.go:3517`) 이 함수는 마지막 토큰의 `>`를 허용합니다(와일드카드 금지용 `IsValidLiteralSubject`는 별도 함수이며 export에 쓰이지 않습니다).
+- 수입 측은 `prefix:` / `to:`가 없으면 **동일 subject**로 구독합니다.
+
+**기본 채택하지 않는 근거 3가지**:
+1. **A-2 목적과 상충** — 범용 홈랩 계정에 **모든 잡의 페이로드**(`detail` 본문 포함)를 열어 줍니다. 워크스페이스 격리를 강화하려는 Track 2와 반대 방향입니다.
+2. **M3 조용한 파손** — export subject가 토픽 루트를 **두 번째로 하드코딩**하는 지점이 됩니다. 지문 토픽 전환 시 매칭이 조용히 끊깁니다(→ `G-D9`가 강제).
+3. **N-1을 해결하지 못함** — import는 라이브 스트림이며 **retained를 옮기지 않습니다.** 즉 Option A를 써도 사후 접속 대시보드는 종료 이벤트를 보지 못합니다. Option B와 동일한 한계입니다.
+
+→ 결론: 단일 사용자 홈랩에서는 **Option B(§A-1의 `mam_observer`)** 가 저장소 §5.5 처방과 일치하고 노출도 최소입니다. Option A는 "다른 사람/다른 신뢰 도메인이 관측한다"는 요구가 실제로 생겼을 때 도입합니다.
+
+---
+
+## 10. 미결 질문 (사용자/Creator 판단 사항)
+
+1. **노출 모델**: 모델 T(Tailscale) 권고. 보유 도메인이 있고 외부 협업자가 붙는다면 모델 P + §B-3.
+2. **관측 클라이언트의 프로토콜**: N-1 때문에 **사후 상태가 필요하면 MQTT로 붙는 것이 정답**입니다. WebSocket/NATS 대시보드를 고집한다면 §5.3 JetStream 리플레이 스트림 옵트인이 필요하며, 이는 추가 디스크 관리 부담을 동반합니다. 어느 쪽을 택할지 결정이 필요합니다.
+3. **서버측 자산의 위치**: `nats.conf`/`docker-compose.yml`을 `deploy/nats/`로 커밋할지, 서버 로컬에만 둘지. 커밋하면 G-D5~G-D7·G-D9를 **실제 파일에 직접** 걸 수 있어 문서 가드보다 강해집니다. 시크릿은 어느 쪽이든 `.env`로 분리.
+4. **`B-17` 우선순위**: H-1·H-4는 원격 전환의 보안 목적을 직접 훼손합니다. Planner 권고는 **M2b 진입 전 처리**입니다.
+5. **`implementation_plan.md` 파일명**: 저장소의 대문자 관례와 어긋납니다(이전 리비전에서도 제기).
+
+---
+
+### 부록 Y — Rev.2에서 새로 수행한 실측
+
+| 대상 | 확인 결과 |
+|---|---|
+| retained 전달 경로 | `mqttSendRetainedMsgsToNewSubs`는 `mqttPacketSub` 처리에서만 호출, `sub.mqtt.prm` 순회 → **MQTT 구독자 전용** |
+| NATS 변수 해석 범위 | `isVariable()`은 **비인용 문자열**에서만 도달. `lexQuotedString`은 *"will not interpret any internal contents"* |
+| export subject 와일드카드 | `IsValidSubject`가 마지막 토큰 `>`를 허용(`isValidSubject`의 `fwc` 분기). export는 `IsValidLiteralSubject`를 쓰지 않음 |
+| export/import 문법 | `exports: [{stream: "..."}]`, `imports: [{stream: {account: X, subject: "..."}}]`, `prefix`/`to` 지원 |
+| 계정 격리 | *"Accounts create isolated tenant subject spaces"*, `jetstream: enabled`는 계정 단위 |
+| `MAM_ENV_FILE` 오타 경로 | **`broker.hivemq.com tls=False`** (다른 후보 미시도) |
+| 대조군(정상 경로) | `nats.private.internal tls=True` |
+| freeze 스크립트 + cwd=저장소 | **`broker.hivemq.com tls=False`** (챌린저의 cwd 도입 근거 성립) |
+| `PRIVATE_SERVER.md:230` | *"MAM과 이를 관측하는 대시보드는 동일한 계정(`MAM`)에 배치"* — Option B는 기존 처방 |
@@ -0,0 +1,657 @@
+# 📐 구현 계획서 Rev.2: `docker/` 프로덕션 배포 자산 정본화 (Job `2168e631`)
+
+- **작성일**: 2026-08-23
+- **역할**: Planner (`.agents/MULTI_AGENT_RULES.md` §1 — Planner 는 저장소 코드/문서를 **수정하지 않으며**, 산출물은 본 계획서입니다)
+- **기준 커밋**: `3523b9b` (테스트 **297건 수집** 실측)
+- **선행 리비전**: `810987f6` (Rev.1) ← 본 문서가 대체합니다
+- **판정 대상 리뷰**: `2934740e` (agy, `[VERDICT: PASS WITH CHALLENGE]`) — WebSocket `same_origin` 기본값 이의제기
+- **대상 산출물**: `docker/docker-compose.yaml`, `docker/nats.conf`, `docker/.env.example`, `docker/README.md`, `tests/test_deploy_freshness.py` (D-22 ~ **D-30**)
+- **테스트 수 예상**: 297 → **306** (Rev.1 의 305 에서 D-30 추가)
+
+---
+
+## A. 리뷰 판정 (Adjudication of Challenge `2934740e`)
+
+### A-1. 판정 요약
+
+| 항목 | 판정 | 근거 |
+|---|---|---|
+| **전제**: "`websocket {}` 를 원점 설정 없이 정의하면 NATS 가 `same_origin: true` 로 기본 동작한다" | ❌ **기각 (사실과 반대)** | `SameOrigin` 은 평범한 `bool` 필드이고 **기본값을 `true` 로 설정하는 코드가 저장소 어디에도 없음**. `checkOrigin()` 은 `!checkSame && listEmpty` 일 때 **즉시 `nil` 반환** |
+| **귀결**: "브라우저 대시보드가 403 Forbidden 으로 거부된다" | ❌ **기각** | 403 경로는 실재하나(`websocket.go:869`) 도달 조건이 성립하지 않음. 현 설정에서 교차 출처 브라우저 접속은 **그대로 성공** |
+| **처방 1**: `same_origin: false` 추가 | ⚠️ **부분 수용 (무해하나 no-op)** | 유효한 키이나 기본값과 동일. "꺼야만 동작한다"는 잘못된 서사를 설정 파일에 새기게 됨 → **주석으로 사실을 기록**하는 형태로 변환 수용 |
+| **처방 2**: `allowed_origins: ["*"]` | 🔴 **강력 기각 — 서버가 기동하지 못함** | `validateWebsocketOptions` 가 `"*"` 의 scheme 이 http/https 가 아니라며 **에러 반환**(`websocket.go:1142-1143`). 이 처방을 따르면 브로커가 **아예 뜨지 않음** |
+| **처방 3**: Mixed Content(`https://` → `ws://`) 문서화 | ✅ **전면 수용** | NATS 와 무관한 브라우저 정책이며 실제로 홈랩에서 자주 발생. §3.4 트러블슈팅 표에 반영 |
+| **부수 효과** | 🟢 **신규 발견 N-7** | 챌린지가 지목한 "Plane B 브라우저 대시보드" 영역을 파다가, **8080 이 `/mqtt` 경로로 MQTT-over-WebSocket 도 서빙**한다는 사실을 확인. Rev.2 이래 미해결이던 열린 질문이 이걸로 **해소**됨 |
+
+### A-2. 전제가 왜 사실과 반대인가 — 실측
+
+**(1) 구조체 필드 주석이 명시적으로 반대를 말합니다.** `server/opts.go:672-677`:
+
+```go
+	// If true, the Origin header must match the request's host.
+	SameOrigin bool
+
+	// Only origins in this list will be accepted. If empty and
+	// SameOrigin is false, any origin is accepted.
+	AllowedOrigins []string
+```
+
+**(2) 기본값을 `true` 로 세우는 코드가 없습니다.** `SameOrigin = true` / `SameOrigin:` (구조체 리터럴) 로 grep 하면 `opts.go`·`websocket.go` 양쪽에서 **0건**입니다. 값은 오직 설정 파서에서만 대입됩니다(`opts.go:5545-5546`). 따라서 Go 제로값 `false` 가 그대로 유효 기본값입니다.
+
+**(3) 검사 자체가 단락(short-circuit)됩니다.** `server/websocket.go:1034-1041`:
+
+```go
+func (w *srvWebsocket) checkOrigin(r *http.Request) error {
+	checkSame := w.sameOrigin
+	listEmpty := len(w.allowedOrigins) == 0
+	if !checkSame && listEmpty {
+		return nil          // ← 우리 설정이 여기서 끝납니다
+	}
+	...
+```
+
+우리 `websocket { port: 8080, no_tls: true }` 는 `sameOrigin=false`, `allowedOrigins` 비어 있음 → 첫 조건에서 `nil` 반환. `Origin` 헤더를 읽지도 않습니다. **`http://localhost:3000` 에서 뜬 React 대시보드가 `ws://100.x.y.z:8080` 로 붙는 시나리오는 아무 변경 없이 성공합니다.**
+
+챌린지가 인용한 403 경로는 실재합니다(`websocket.go:868-870`, `StatusForbidden`, `"origin not allowed: %v"`). 다만 그 문은 `checkSame || !listEmpty` 일 때만 열립니다. 즉 **문은 있으나 우리 설정에서는 그 앞까지 가지 않습니다.**
+
+### A-3. 처방 2 를 따르면 브로커가 죽는다 — 실측
+
+`allowed_origins: ["*"]` 는 단지 불필요한 게 아니라 **기동 차단** 설정입니다. `server/websocket.go:1136-1150` (`validateWebsocketOptions`):
+
+```go
+	for _, ao := range wo.AllowedOrigins {
+		u, err := url.ParseRequestURI(ao)
+		if err != nil { return fmt.Errorf("unable to parse allowed origin: %v", err) }
+		if u.Scheme != "http" && u.Scheme != "https" {
+			return fmt.Errorf("unable to parse allowed origin %q: allowed origins must be "+
+				"absolute URLs with http or https scheme", ao)
+		}
+		if u.Host == _EMPTY_ { ... }
+```
+
+`"*"` 는 scheme 이 비어 있으므로 두 번째 분기에서 에러. 옵션 검증 실패는 기동 실패입니다. 게다가 논리적으로도 역효과입니다 — `AllowedOrigins` 를 비우지 않는 순간 `listEmpty` 가 `false` 가 되어 **원점 검사가 켜집니다**. "모두 허용"을 의도한 설정이 "검사 활성화"를 유발하는 구조입니다.
+
+> [!IMPORTANT]
+> 이 항목은 챌린지의 처방을 그대로 구현했다면 **프로덕션 브로커가 기동조차 못 했을** 사안입니다. 리뷰를 지시가 아니라 가설로 취급하고 측정한 결과이며, `MULTI_AGENT_RULES.md` §1 의 '[REBUT:]' 절차에 해당합니다.
+
+### A-4. 그럼에도 챌린지가 옳게 짚은 것
+
+1. **Mixed Content 는 100% 실재하는 제약**입니다. NATS 설정과 무관하게, `https://` 로 서빙된 페이지는 `ws://` 연결을 브라우저가 차단합니다. 홈랩에서 대시보드를 HTTPS 로 올리는 순간 8080 평문 WS 는 못 씁니다. §3.4 트러블슈팅에 반영합니다.
+2. **운영자가 반드시 궁금해할 지점을 정확히 지목**했습니다. Rev.1 의 `websocket { port: 8080, no_tls: true }` 는 원점 정책에 대해 **아무 말도 하지 않았고**, 그래서 리뷰어가 정반대로 추정했습니다. 설정 파일이 침묵하면 독자가 최악을 가정한다는 증거입니다 — 주석으로 사실을 명문화합니다(§3.1).
+3. **보안 방향은 오히려 반대로 열려 있습니다.** 기본값이 관대하므로, 8080 을 tailnet 밖으로 내보내는 순간 임의 웹 페이지가 핸드셰이크를 시도할 수 있습니다(인증은 별도로 막지만). 완화가 아니라 **강화** 처방(`allowed_origins` 에 실제 대시보드 URL)이 필요하며, 이를 주석 템플릿으로 제공하고 D-30 가드로 `"*"` 회귀를 봉인합니다.
+
+### A-5. 신규 발견 N-7 — 8080 은 MQTT-over-WebSocket 도 서빙한다 (열린 질문 해소)
+
+챌린지의 주제(Plane B 브라우저 대시보드)를 측정하다 확인한 사실입니다.
+
+```go
+// server/websocket.go:820-833
+	if r.URL != nil {
+		ep := r.URL.EscapedPath()
+		if strings.HasSuffix(ep, leafNodeWSPath) { kind = LEAF }
+		else if strings.HasSuffix(ep, mqttWSPath) { kind = MQTT }   // mqttWSPath = "/mqtt"
+	}
+	// Reject MQTT-over-WebSocket upgrades unless MQTT is enabled.
+	if kind == MQTT && opts.MQTT.Port == 0 { ... 404 ... }
+
+// server/websocket.go:1333-1335
+		case MQTT:
+			s.createMQTTClient(res.conn, res.ws)      // ← 1883 리스너와 동일 함수
+```
+
+- `mqttWSPath = "/mqtt"` (`server/mqtt.go:193`).
+- 게이트는 `opts.MQTT.Port != 0` 뿐이며, 우리 설정은 `mqtt { port: 1883 }` 이므로 **이미 충족**입니다.
+- 생성 함수가 네이티브 1883 리스너와 **동일한 `createMQTTClient`** (`mqtt.go:552` vs `websocket.go:1335`) 이므로, 이 연결은 트랜스포트만 WebSocket 인 **완전한 MQTT 클라이언트**입니다.
+
+**이것이 왜 중요한가**: Rev.2(`b11d499d`) 이래 남아 있던 열린 질문 — *"대시보드를 MQTT 로 붙일 것인가, 아니면 N-1(retained 는 MQTT 전용) 제약을 받아들이고 JetStream 리플레이 스트림을 만들 것인가"* — 가 **제3의 답으로 해소**됩니다.
+
+> 브라우저 대시보드가 **MQTT.js 로 `ws://mam-hub:8080/mqtt` 에 접속하면**, 그것은 MQTT 클라이언트이므로 `mqttSendRetainedMsgsToNewSubs` 경로를 그대로 타고 **retained 종료 이벤트를 받습니다**. 별도 리플레이 스트림도, 디스크 관리 부담도 필요 없습니다.
+
+반면 같은 8080 포트라도 **NATS 네이티브 WebSocket**(경로 없음 또는 `/`)으로 붙으면 N-1 이 그대로 적용되어 종료 이벤트를 못 받습니다. **같은 포트, 다른 경로, 다른 결과** — 이 함정은 반드시 문서화되어야 합니다.
+
+부수 효과로 노출 모델 서술도 정정이 필요합니다: 8080 은 "Plane B 전용"이 아니라 **MQTT 프로토콜 표면을 함께 노출**합니다(인증은 계정 설정이 동일하게 강제).
+
+---
+
+## B. Rev.1 → Rev.2 변경 요약
+
+| # | 변경 | 출처 |
+|---|---|---|
+| C-1 | `docker/nats.conf` `websocket {}` 블록에 **원점 정책 사실 주석 + `allowed_origins` 강화 템플릿(주석)** 추가. `same_origin: false` 는 **활성 라인으로 넣지 않음** | 챌린지 §2.3-1 변환 수용 |
+| C-2 | `docker/nats.conf` `websocket {}` 에 **`/mqtt` 경로 = MQTT-over-WS** 사실 주석 추가 | N-7 |
+| C-3 | `docker/README.md` 트러블슈팅에 **WS 403(정확한 발동 조건)** · **Mixed Content** · **`/mqtt` vs `/` 경로 차이** 3행 추가 | 챌린지 §2.3-2 + N-7 |
+| C-4 | `docker/README.md` 6절(클라이언트 연결)에 **브라우저 대시보드 접속 레시피** 신설 | N-7 |
+| C-5 | 신규 가드 **D-30**(WebSocket 원점 정책이 기동 가능한 형태인지) 추가 → 305 → **306** | A-3 |
+| C-6 | 문서 동기화 작업에 **T-5** 신설: `PRIVATE_SERVER.md` §5.1/§5.2 의 '두 소비 평면' 서술에 세 번째 경로(MQTT-over-WS) 반영 | N-7 |
+| C-7 | 실측 원장에 **M-19 ~ M-24** 추가 | A-2 / A-3 / N-7 |
+| C-8 | 열린 질문에서 'Rev.2 이월 질문' **삭제(해소됨)**, 대신 Q-5(대시보드 프로토콜 선택 권고) 로 대체 | N-7 |
+
+Rev.1 의 §2 설계 결정 D-1 ~ D-8, §3.2 compose, §3.3 `.env.example`, §4 가드 D-22 ~ D-29, §5 T-1 ~ T-4, §7 발견 N-2 ~ N-6 은 **리뷰에서 전부 승인**되었으며 변경 없이 유지합니다.
+
+---
+
+## 0. 요약 — 이 계획이 무엇을 확정하는가
+
+`PRIVATE_SERVER.md` §9 는 지금까지 **문서 안의 코드 펜스**로만 존재했습니다. 펜스는 복사-붙여넣기 대상이지 배포 자산이 아니므로,
+
+1. 서버에 실제로 올라간 설정이 문서와 갈라져도 아무도 알 수 없고,
+2. `test_deploy_freshness.py` 의 D-15 ~ D-19 가드는 **문서만** 검사하므로 실제 배포물의 회귀를 잡지 못하며,
+3. 시크릿을 어디에 두는지가 규약이 아니라 관습으로 남습니다.
+
+본 계획은 §9 의 펜스를 `docker/` 하위의 **정본(canonical) 파일**로 승격시키고, 문서↔파일 드리프트를 9종의 신규 가드(D-22 ~ D-30)로 봉인합니다.
+
+> [!IMPORTANT]
+> 현재 저장소에는 **0 바이트짜리 `docker/docker-compose.yaml`** 이 untracked 상태로 존재합니다(`git status` = `?? docker/`). 신규 가드 D-22 는 이 상태에서 **즉시 FAIL** 하도록 설계되어 있습니다 — 즉 가드가 공허하게 통과하지 않음이 착수 시점에 자동으로 증명됩니다.
+
+---
+
+## 1. 실측 기반 (Measurement Ledger)
+
+| # | 검증 항목 | 방법 | 실측 결과 |
+|---|---|---|---|
+| M-1 | 테스트 베이스라인 | `pytest tests/ -q --collect-only` | **297 collected** |
+| M-2 | `nats:2.12-alpine` 태그 실재 | Docker Hub API `library/nats/tags?name=2.12` | 존재. 최신 패치 **2.12.15** (2026-08-12) |
+| M-3 | alpine 이미지 베이스 | `nats-docker/main/2.12.x/alpine3.22/Dockerfile` | `FROM alpine:3.22` → **busybox `wget` 내장** |
+| M-4 | 엔트리포인트 인자 처리 | 동 디렉터리 `docker-entrypoint.sh` | `[ "${1#-}" != "$1" ] && set -- nats-server "$@"` → `command: ["-c", …]` **동작** |
+| M-5 | 이미지 HEALTHCHECK 유무 | 동 Dockerfile | **없음** → compose 가 반드시 정의 |
+| M-6 | 미해결 `$VAR` 동작 | `conf/parse.go:390` | 파싱 에러 = **fail-closed** |
+| M-7 | 환경변수 값 재파싱 | `conf/parse.go` `lookupVariable` → `parseEnv(...)` | 환경변수 값이 **NATS 렉서로 재파싱** (N-5) |
+| M-8 | 비인용 문자열 종결자 | `conf/lex.go:958-960` | NL, EOF, `;`, `,`, `]`, `}`, 공백. `=` `+` `/` 는 **비종결자** |
+| M-9 | `mqtt {}` 유효 키 | `server/opts.go` `parseMQTT` | `port`/`ack_wait`/`max_ack_pending` **전부 유효** |
+| M-10 | `max_ack_pending` 상한 | `opts.go:5673-5679` | `[0..65535]`. **1024 유효** |
+| M-11 | `jetstream {}` 유효 키 | `opts.go` `parseJetStream` | `store_dir`, `max_file`, `max_mem` **전부 유효** |
+| M-12 | 크기 접미사 대소문자 | `opts.go:2507` `suffixMap` | `{"K","M","G","T"}` **대문자 전용** (N-6) |
+| M-13 | `websocket {}` 유효 키 | `opts.go` `parseWebsocket` | `port`, `no_tls`, `same_origin`, `allowed_origins` 등 유효 |
+| M-14 | `.gitignore` 거동 | `git check-ignore -v` | `docker/.env` **ignored**(`:21`), `docker/.env.example` **tracked**(`:23`) |
+| M-15 | 비인용 `${VAR:?msg}` YAML | PyYAML 6.0.3 파싱 | 평문 스칼라 → **문서 원문 그대로 파일화 가능** |
+| M-16 | PyYAML 선언 여부 | `requirements.txt`=1행, `tests/test_sanity.py:3`=`import yaml` | **미선언 하드 의존** (N-2) |
+| M-17 | 설치 스크립트 배포 범위 | `deploy/install.sh:365-374` | `docker/`·`PRIVATE_SERVER.md` **미배포** |
+| M-18 | `DEFAULT_TOPIC_ROOT` | `mqtt_common.py:119` | `"python/mqtt/jobs"` |
+| **M-19** | **`SameOrigin` 기본값** | `opts.go` 전역 grep `SameOrigin = true` / `SameOrigin:` | **0건** → Go 제로값 `false`. 주석(`opts.go:676-677`)도 "empty and SameOrigin is false → any origin is accepted" 명시 |
+| **M-20** | **`checkOrigin` 단락 조건** | `websocket.go:1034-1041` | `!checkSame && listEmpty` → **즉시 `nil`**. `Origin` 헤더를 읽지 않음 |
+| **M-21** | **403 발동 지점** | `websocket.go:868-870` | `StatusForbidden "origin not allowed"` — `checkOrigin` 이 에러일 때만 |
+| **M-22** | **`allowed_origins: ["*"]`** | `websocket.go:1136-1150` `validateWebsocketOptions` | scheme 이 http/https 가 아니라며 **옵션 검증 실패 → 기동 실패** |
+| **M-23** | **`no_tls` 필요성** | `websocket.go:1132-1134` | `TLSConfig == nil && !NoTLS` → `websocket requires TLS configuration`. 현 설정의 `no_tls: true` 는 **필수** |
+| **M-24** | **MQTT-over-WebSocket** | `mqtt.go:193` `mqttWSPath="/mqtt"`; `websocket.go:824,832,1334-1335` | 8080 의 `/mqtt` 경로가 `createMQTTClient` 로 분기. 게이트는 `MQTT.Port != 0` 뿐 → **이미 활성** (N-7) |
+
+---
+
+## 2. 설계 결정 (Design Decisions)
+
+### D-1. 파일명은 `docker/docker-compose.yaml` + 문서 참조 정정
+브리프는 `.yaml`, `PRIVATE_SERVER.md` §9.2 제목은 `.yml` 을 씁니다. Compose 는 둘 다 인식하므로 기능 차는 없습니다. **브리프를 정본으로 채택**하고 문서 참조를 정정합니다(T-3). 두 곳이 다른 채로 남으면 D-23 doc↔file 가드가 무엇을 비교하는지 모호해집니다.
+
+### D-2. 계정 사용자명은 `mam_agent` / `mam_observer` 유지
+브리프의 `MAM with mam/observer` 축약은 **계정 구조**를 가리킨 것으로 읽습니다. 식별자를 바꾸면 `PRIVATE_SERVER.md` §6 (`MQTT_USERNAME=mam_agent`) 과 §9.4 R-9 플레이북이 조용히 깨집니다.
+
+### D-3. `version: '3.8'` 제거
+Compose V2 는 매 `up` 마다 `the attribute 'version' is obsolete` 경고를 냅니다. 프로덕션 자산이 상시 경고를 뿜으면 운영자가 경고를 무시하는 습관을 들입니다. 기능 영향 0.
+
+### D-4. `.env.example` 의 시크릿은 **빈 값**으로 출하 (fail-closed 의 핵심)
+
+| 방식 | `cp .env.example .env` 후 결과 |
+|---|---|
+| `MAM_BROKER_PASS=changeme` | 브로커 **정상 기동**. 전 세계가 아는 암호로 프로덕션 가동 = **fail-open** |
+| `MAM_BROKER_PASS=` (빈 값) ✅ | `${VAR:?…}` 는 콜론 형태라 **빈 값에서도 중단** → 컨테이너 생성 전 비영점 종료 |
+
+방어는 이중입니다: Compose 보간 실패(1차) → 그래도 떴다면 `nats.conf` 미해결 `$VAR` 파싱 에러(M-6, 2차).
+
+### D-5. `nats.conf` 는 시크릿을 한 글자도 담지 않는다
+모든 `password:` 는 `$VAR` 참조. 따라서 `docker/nats.conf` 는 커밋 가능하고, 시크릿은 gitignore 된 `docker/.env` 에만 존재합니다(M-14). D-25(e) 가 봉인합니다.
+
+### D-6. 암호 생성기는 `openssl rand -base64 32` 로 고정하고 이유를 문서화
+파서 제약입니다(M-7/M-8). 암호에 `공백 ; , ] } # ' " $` 가 들어가면 설정이 깨지거나 조용히 다른 값이 됩니다. base64 알파벳(`A-Za-z0-9+/=`)은 이 집합과 교집합이 0입니다.
+
+### D-7. healthcheck 는 `wget` 유지 — 이미지 계열과 **커플링**해서 봉인
+`wget` 은 alpine 베이스에만 있습니다(M-3). D-28 은 healthcheck 존재와 이미지 alpine 여부를 **한 테스트 안에서** 단언합니다. 분리하면 이미지만 바꾸는 커밋이 통과합니다.
+
+### D-8. `docker/` 는 하위 워크스페이스로 배포하지 않는다
+`install.sh` 는 `PRIVATE_SERVER.md` 조차 배포하지 않습니다(M-17). `docker/` 는 **이 저장소가 운영하는 서버**의 자산이므로 동일하게 저장소 전용으로 둡니다. `install.sh` 를 건드리지 않는 것이 명시적 결정입니다(Q-3).
+
+### D-9 (신규). WebSocket 원점 정책은 **활성 설정이 아니라 주석으로** 다룬다
+
+세 가지 선택지를 검토했습니다.
+
+| 선택 | 결과 |
+|---|---|
+| `same_origin: false` 활성 추가 (챌린지 처방 1) | 동작상 **no-op**(M-19). 그러나 설정 파일이 "이걸 꺼야 브라우저가 붙는다"는 **거짓 서사**를 후임자에게 전달 |
+| `allowed_origins: ["*"]` (챌린지 처방 2) | 🔴 **기동 실패**(M-22) |
+| **주석으로 기본 동작을 명문화 + 강화 템플릿을 주석 제공** ✅ | 동작 불변, 리뷰어가 실제로 겪은 정보 공백을 메움, 8080 을 tailnet 밖으로 낼 때 필요한 **강화** 경로를 즉시 제공 |
+
+세 번째를 채택합니다. 리뷰어의 관찰(설정이 원점 정책에 침묵한다)은 타당했고, 처방(끄기)만 방향이 반대였습니다. 침묵을 메우되 사실대로 메웁니다.
+
+---
+
+## 3. 산출물 명세 (Creator 구현 사양)
+
+### 3.1 `docker/nats.conf`
+
+```conf
+# ==============================================================================
+# docker/nats.conf — MAM 원격 프로덕션 브로커 (Track 1R)
+#
+# 정본 문서: PRIVATE_SERVER.md §9.1
+# 시크릿: 이 파일에는 없습니다. 모든 password 는 docker/.env → compose
+#         environment → 컨테이너 환경변수로 주입되는 $VAR 참조입니다.
+#
+# ⚠ 암호 문자 제약: NATS 는 환경변수 값을 자체 설정 렉서로 재파싱합니다.
+#   암호에 [공백 ; , ] } # ' " $] 가 들어가면 설정이 깨지거나 다르게 해석됩니다.
+#   반드시 `openssl rand -base64 32` (알파벳 A-Za-z0-9+/=) 를 사용하십시오.
+# ==============================================================================
+server_name: mam-hub
+
+# ── JetStream: MQTT retained/QoS1 저장소. 종료 이벤트 재수신이 여기에 의존 ──
+jetstream {
+  store_dir: "/data"      # 절대경로 고정. '~' 도 인용된 "$HOME" 도 확장되지 않음
+  max_file: 10G           # 접미사는 대문자만 유효 (K/M/G/T)
+  max_mem: 256M
+}
+
+http_port: 8222           # 무인증 모니터링 → 호스트 게시는 loopback 한정 (compose)
+
+mqtt {
+  port: 1883
+  ack_wait: 60s           # WAN RTT 흡수 (기본 30s)
+  max_ack_pending: 1024   # 다중 에이전트 동시 발행 여유 (상한 65535)
+}
+
+websocket {
+  port: 8080
+  no_tls: true            # 사설망/tailnet 한정. 생략하면 TLS 설정 필수라 기동 실패
+
+  # ── 원점(Origin) 정책 ────────────────────────────────────────────────
+  # 기본값은 이미 '모든 출처 허용'입니다. same_origin 의 기본값은 false 이고
+  # allowed_origins 가 비어 있으면 checkOrigin() 이 Origin 헤더를 읽지도 않고
+  # 즉시 nil 을 반환합니다 (server/websocket.go:1039).
+  #   → http://localhost:3000 의 브라우저 대시보드는 별도 설정 없이 접속됩니다.
+  #   → `same_origin: false` 를 적는 것은 no-op 입니다.
+  #
+  # 8080 을 tailnet 밖으로 노출한다면 아래를 켜서 출처를 좁히십시오.
+  # 주의: allowed_origins 를 비우지 않는 순간 원점 검사가 '켜집니다'.
+  #       "*" 는 절대 쓰지 마십시오 — 옵션 검증 실패로 서버가 기동하지 못합니다
+  #       (websocket.go:1142 "must be absolute URLs with http or https scheme").
+  # allowed_origins: ["https://dashboard.example", "http://localhost:3000"]
+
+  # ── 이 포트는 MQTT-over-WebSocket 도 서빙합니다 ───────────────────────
+  # 경로 /mqtt 로 붙으면 완전한 MQTT 클라이언트가 됩니다 (mqtt.go:193,
+  # websocket.go:1335 → createMQTTClient, 1883 리스너와 동일 함수).
+  #   ws://<host>:8080/mqtt  → MQTT. retained 종료 이벤트를 받습니다.
+  #   ws://<host>:8080/      → NATS 네이티브. retained 를 받지 못합니다 (N-1).
+  # 브라우저 대시보드는 MQTT.js 로 /mqtt 에 붙이는 것을 권장합니다.
+}
+
+# ── 인증 및 멀티테넌시 ────────────────────────────────────────────────────
+accounts {
+  MAM: {
+    jetstream: enabled                    # MQTT 내부 스트림이 이 계정 안에 생성됨
+    users: [
+      # 발행자 겸 구독자 — MAM 에이전트 본체 (.mam.env 의 MQTT_USERNAME)
+      { user: mam_agent, password: $MAM_BROKER_PASS }
+
+      # 관측자 — 대시보드/모니터링. 반드시 MAM 계정 안에 위치
+      { user: mam_observer, password: $MAM_OBSERVER_PASS,
+        permissions: {
+          subscribe: { allow: ["python.mqtt.jobs.>"] }   # M3 이후: "mam.<fp>.jobs.>"
+          publish:   { deny:  [">"] }
+        }
+      }
+    ]
+  }
+  # MAM 과 무관한 홈랩 서비스 전용. MAM subject 는 보이지 않음(의도된 격리)
+  HOME: { jetstream: enabled, users: [ { user: home, password: $HOME_BROKER_PASS } ] }
+  SYS:  { users: [ { user: sys, password: $SYS_BROKER_PASS } ] }
+}
+system_account: SYS
+```
+
+**계약 값** (가드 검사 대상): `store_dir` = `/data` · `mqtt.port` = `1883` · `websocket.port` = `8080` · `http_port` = `8222` · 계정 `MAM`/`HOME`/`SYS` · 사용자 `mam_agent`/`mam_observer`/`home`/`sys` · subject 접두 `python.mqtt.jobs` · 모든 `password:` 는 `$` 시작 · 활성 `allowed_origins` 에 `"*"` 없음(D-30).
+
+> [!NOTE]
+> `accounts {}` 를 정의하고 `no_auth_user` 를 두지 않았으므로 **익명 접속은 MQTT·NATS·WebSocket 전 경로에서 거부**됩니다. 이는 §9.4 R-3(노출 면적 0)과 독립된 두 번째 방어선이며, N-7 로 드러난 `/mqtt` 표면에도 동일하게 적용됩니다.
+
+### 3.2 `docker/docker-compose.yaml`
+
+```yaml
+# ==============================================================================
+# docker/docker-compose.yaml — MAM 원격 프로덕션 브로커 (Track 1R)
+# 정본 문서: PRIVATE_SERVER.md §9.2
+#
+# 사용법:  cd docker && cp .env.example .env && <시크릿 채우기> && docker compose up -d
+# ==============================================================================
+services:
+  nats:
+    image: nats:2.12-alpine          # alpine 필수: healthcheck 의 wget 이 여기에만 있음
+    container_name: mam-nats
+    restart: unless-stopped
+    command: ["-c", "/etc/nats/nats.conf"]
+    environment:
+      # 미설정/빈 값이면 컨테이너 생성 전에 compose 가 중단 → fail-closed
+      MAM_BROKER_PASS:   ${MAM_BROKER_PASS:?set MAM_BROKER_PASS in docker/.env}
+      MAM_OBSERVER_PASS: ${MAM_OBSERVER_PASS:?set MAM_OBSERVER_PASS in docker/.env}
+      HOME_BROKER_PASS:  ${HOME_BROKER_PASS:?set HOME_BROKER_PASS in docker/.env}
+      SYS_BROKER_PASS:   ${SYS_BROKER_PASS:?set SYS_BROKER_PASS in docker/.env}
+    ports:
+      # ⚠ Docker 의 published 포트는 UFW 를 우회합니다. 노출 통제는 방화벽이 아니라
+      #   여기의 바인드 주소가 담당합니다. 기본값은 전부 loopback.
+      - "${MQTT_BIND:-127.0.0.1}:1883:1883"    # MQTT 3.1.1 (평면 A: MAM)
+      - "${NATS_BIND:-127.0.0.1}:4222:4222"    # NATS 네이티브 (평면 B)
+      - "127.0.0.1:8222:8222"                  # 무인증 모니터링 — loopback 고정
+      - "${WS_BIND:-127.0.0.1}:8080:8080"      # WebSocket (NATS + /mqtt 경로의 MQTT)
+    volumes:
+      - ./nats.conf:/etc/nats/nats.conf:ro
+      - nats-data:/data                        # nats.conf 의 store_dir 와 일치
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8222/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+volumes:
+  nats-data:
+```
+
+**주의 사항**
+- `8222` 만 바인드 주소가 하드코딩입니다. 나머지 3개는 `${*_BIND:-127.0.0.1}` 로 tailnet IP 주입을 허용하되 기본값이 loopback 입니다. D-24 가 이 비대칭을 검사합니다.
+- `./nats.conf` 는 compose 프로젝트 디렉터리 기준 상대경로이므로 `docker/` 안에서 실행해야 합니다.
+- 비인용 `${VAR:?msg}` 는 PyYAML 로 평문 스칼라 파싱됨을 실측(M-15). 인용부호 추가 불필요.
+
+### 3.3 `docker/.env.example`
+
+```bash
+# ==============================================================================
+# docker/.env.example — 원격 브로커 서버 측 환경변수 템플릿
+#
+# 이 파일은 git 에 커밋됩니다 (.gitignore:23 의 `!.env.example`).
+# 복사본 docker/.env 는 git 에서 제외됩니다 (.gitignore:21 의 `.env`).
+#
+#   cd docker && cp .env.example .env && chmod 600 .env
+#
+# ⚠ 아래 시크릿 4종은 의도적으로 **빈 값**입니다. 채우지 않고 그대로 복사하면
+#   `docker compose up` 이 컨테이너를 만들기 전에 실패합니다 (fail-closed).
+#   플레이스홀더 문자열을 넣지 마십시오 — '알려진 암호로 가동'이 최악입니다.
+# ==============================================================================
+
+# ── 시크릿 (필수) ────────────────────────────────────────────────────────
+# 생성:  openssl rand -base64 32
+#
+# ⚠ 반드시 위 명령을 사용하십시오. NATS 는 환경변수 값을 설정 렉서로 재파싱하므로
+#   암호에 [공백 ; , ] } # ' " $] 가 포함되면 설정이 깨지거나 다르게 해석됩니다.
+#   base64 알파벳(A-Za-z0-9+/=)은 이 문자들과 교집합이 없어 안전합니다.
+
+# MAM 에이전트 발행/구독 계정 (.mam.env 의 MQTT_PASSWORD 와 동일 값)
+MAM_BROKER_PASS=
+
+# 관측 전용 계정 (구독 allow: python.mqtt.jobs.>, 발행 전면 deny)
+MAM_OBSERVER_PASS=
+
+# MAM 과 무관한 홈랩 서비스용 별도 계정
+HOME_BROKER_PASS=
+
+# 시스템 계정 ($SYS). 운영 이벤트/모니터링 전용
+SYS_BROKER_PASS=
+
+# ── 리스너 바인드 주소 (선택 — 미설정 시 전부 127.0.0.1) ──────────────────
+# ⚠ Docker 의 published 포트는 UFW 를 우회합니다. 아래 값이 실질적인 노출 통제입니다.
+# 모델 T(Tailscale) 권장 설정:  MQTT_BIND=$(tailscale ip -4)
+#
+# MQTT 1883 리스너 바인드 주소
+# MQTT_BIND=127.0.0.1
+#
+# NATS 4222 네이티브 리스너 바인드 주소
+# NATS_BIND=127.0.0.1
+#
+# WebSocket 8080 바인드 주소.
+# 참고: 이 포트는 NATS WebSocket 과 MQTT-over-WebSocket(/mqtt)을 함께 서빙합니다.
+# WS_BIND=127.0.0.1
+#
+# HTTP 모니터 8222 는 무인증이므로 바인드 주소를 변수화하지 않습니다 (loopback 고정).
+```
+
+**설계 포인트**: 시크릿 4종은 **주석 해제 없이 빈 값으로 활성**, 바인드 주소 3종은 **주석 처리**. 이 비대칭이 "시크릿은 반드시 채워야 하고, 바인드는 안 채워도 안전한 기본값"이라는 의도를 파일 형태로 표현합니다.
+
+### 3.4 `docker/README.md`
+
+| 절 | 내용 | 정본 |
+|---|---|---|
+| 1. 무엇인가 | 이 디렉터리가 MAM 관측 백플레인 브로커의 정본임. `PRIVATE_SERVER.md` §9 링크 | §9 |
+| 2. 사전 요구 | Docker Engine + Compose V2, (모델 T) Tailscale, 개방 포트 없음 | §9.3 |
+| 3. 5분 배포 | `docker/` 복사 → `cp .env.example .env` → `openssl rand -base64 32` ×4 → `chmod 600 .env` → `docker compose up -d` → `docker compose ps` **healthy** | §9.2 |
+| 4. 네트워크 잠금 | UFW 규칙 전문 + **published 포트가 UFW 를 우회**한다는 경고를 최상단에 | §9.3 |
+| 5. 노출 검증 | 외부 망에서 `nmap -Pn -p 1883,4222,8222,8080 <공개IP>` → 전부 closed/filtered (R-3) | §9.4 |
+| 6. 클라이언트 연결 | (a) MAM 저장소 `.mam.env` 기입 (b) **브라우저 대시보드 레시피** (아래) | §6 + N-7 |
+| 7. 검증 플레이북 | R-1 ~ R-10 표 + 지연 측정 스니펫 링크 | §9.4 |
+| 8. 운영 | 로그 로테이션(내장), JetStream 볼륨 백업, `docker compose pull && up -d`, `/varz`·`/jsz` 는 SSH 터널 경유 | §9 P6 |
+| 9. 트러블슈팅 | 아래 표 | 신규 |
+
+**6절 (b) 브라우저 대시보드 접속 레시피** — N-7 반영, 필수 신설:
+
+```js
+// MQTT.js — retained 종료 이벤트까지 받는 경로 (권장)
+const client = mqtt.connect("ws://mam-hub.tailXXXX.ts.net:8080/mqtt", {
+  username: "mam_observer",
+  password: "<MAM_OBSERVER_PASS>",
+  protocolVersion: 4,          // MQTT 3.1.1
+});
+client.subscribe("python/mqtt/jobs/+/events");
+// 이 클라이언트는 서버에서 완전한 MQTT 클라이언트로 취급되므로
+// 잡이 끝난 뒤에 접속해도 retained 최종 이벤트를 즉시 수신합니다.
+
+// nats.ws — 경로 없이 붙으면 NATS 네이티브. 라이브 스트림만 수신하며
+// 이미 끝난 잡의 종료 이벤트는 받지 못합니다 (N-1).
+```
+
+**9절 트러블슈팅 표(필수 항목)**
+
+| 증상 | 원인 | 조치 |
+|---|---|---|
+| `required variable MAM_BROKER_PASS is missing` | `.env` 미생성 또는 빈 값 | 의도된 fail-closed. 시크릿을 채울 것 |
+| `variable reference for 'MAM_BROKER_PASS' … can not be found` | compose 통과했으나 컨테이너에 변수 미주입 | `environment:` 블록 누락 확인 |
+| 컨테이너는 뜨는데 계속 `unhealthy` | 이미지를 `latest`/`scratch`/non-alpine 로 변경 → `wget` 부재 | `nats:2.12-alpine` 로 복귀 |
+| 설정이 알 수 없는 값으로 해석됨 | 암호에 렉서 종결자 포함 | `openssl rand -base64 32` 로 재발급 |
+| `max_file` 에러 | `10g` 등 소문자 접미사 | 대문자 `10G` |
+| 원격에서 접속 불가 | 바인드가 loopback 기본값 | `.env` 에 `MQTT_BIND=$(tailscale ip -4)` |
+| `JetStream not enabled for account` | 계정에 `jetstream: enabled` 누락 | `MAM` 계정 블록 확인 |
+| **WebSocket `403 origin not allowed`** | **기본 설정에서는 발생하지 않습니다.** `allowed_origins` 를 채웠거나 `same_origin: true` 를 켠 경우에만 발동 | 해당 설정을 지우거나, 대시보드 URL을 `allowed_origins` 에 추가 |
+| **서버가 `allowed origins must be absolute URLs…` 로 기동 실패** | `allowed_origins` 에 `"*"` 또는 scheme 없는 값 | `["https://dashboard.example"]` 처럼 절대 URL 로 |
+| **브라우저 콘솔의 Mixed Content 차단** | `https://` 페이지에서 `ws://` 연결 시도 | 대시보드를 tailnet 내부 `http://` 로 서빙하거나, 리버스 프록시로 `wss://` 종단 제공 |
+| **대시보드가 종료 이벤트를 못 받음** | 8080 에 **경로 없이**(NATS 네이티브) 접속함. retained 는 MQTT 전용 (N-1) | `ws://host:8080/**mqtt**` 로 MQTT.js 접속 (N-7) |
+
+---
+
+## 4. 신규 회귀 가드 D-22 ~ D-30
+
+`tests/test_deploy_freshness.py` 말미에 추가합니다. 기존 D-11 ~ D-21 스타일(모듈 상단 상수, 펜스 스코핑, 공허 통과 방지 단언)을 따릅니다.
+
+### 4.1 공통 헬퍼
+
+```python
+DOCKER_DIR = os.path.join(REPO_ROOT, "docker")
+COMPOSE_PATH = os.path.join(DOCKER_DIR, "docker-compose.yaml")
+NATS_CONF_PATH = os.path.join(DOCKER_DIR, "nats.conf")
+ENV_EXAMPLE_PATH = os.path.join(DOCKER_DIR, ".env.example")
+DOCKER_README_PATH = os.path.join(DOCKER_DIR, "README.md")
+
+SECRET_VARS = {"MAM_BROKER_PASS", "MAM_OBSERVER_PASS",
+               "HOME_BROKER_PASS", "SYS_BROKER_PASS"}
+
+
+def _load_compose():
+    """compose 파일을 dict 로. 파일이 비었거나 nats 서비스가 없으면 즉시 실패."""
+    import yaml
+    with open(COMPOSE_PATH, encoding="utf-8") as f:
+        doc = yaml.safe_load(f)
+    assert isinstance(doc, dict) and doc.get("services"), (
+        "docker/docker-compose.yaml is empty or has no services: — the docker/ "
+        "assets were never populated")
+    svc = doc["services"].get("nats")
+    assert svc, "compose file defines no 'nats' service"
+    return doc, svc
+
+
+def _active_conf_lines():
+    """nats.conf 에서 주석을 제외한 '활성' 라인만. 주석 템플릿을 오탐하지 않기 위함."""
+    with open(NATS_CONF_PATH, encoding="utf-8") as f:
+        lines = [ln.split("#", 1)[0].rstrip() for ln in f]
+    return [ln for ln in lines if ln.strip()]
+```
+
+> `_active_conf_lines()` 는 D-30 의 정확도를 위한 것입니다. §3.1 은 `allowed_origins` 를 **주석 템플릿**으로 제공하므로, 주석을 그대로 스캔하면 가드가 자기 문서를 오탐합니다.
+
+### 4.2 가드 명세
+
+| ID | 이름 | 단언 | 공허 통과 방지 | 잡아내는 회귀 |
+|---|---|---|---|---|
+| **D-22** | `docker_assets_exist_and_are_populated` | 4개 파일 존재 + 크기 > 0, compose 가 `nats` 서비스를 갖는 dict 로 파싱 | `_load_compose()` 가 `services` 비면 실패 | **현재의 0바이트 compose**, 자산 삭제 |
+| **D-23** | `compose_image_matches_doc_and_is_alpine` | compose 의 `nats:<tag>` == `PRIVATE_SERVER.md` 펜스에서 추출한 태그, `tag != "latest"`, `"alpine" in tag` | 양쪽에서 태그 추출 실패 시 실패 | 한쪽만 업그레이드하는 드리프트, scratch 회귀 |
+| **D-24** | `compose_port_exposure_contract` | 컨테이너 포트 집합 == `{1883,4222,8222,8080}`; 모든 게시가 3필드 → **bare `"1883:1883"` 금지**; `8222` 는 정확히 `127.0.0.1:8222:8222` | `ports` 비면 실패 | 바인드 누락으로 인터넷 노출, 포트 오타 |
+| **D-25** | `secrets_are_fail_closed` | (a) `nats.conf` 의 모든 `$VAR` ⊆ compose `environment:` 키 (b) 값이 전부 `:?` 형태 (c) `SECRET_VARS` 전부 `.env.example` 에 존재 (d) `.env.example` 의 시크릿 4종 값이 **빈 문자열** (e) `nats.conf` 의 모든 `password:` 값이 `$` 시작 | `$VAR` 0건이면 실패 | 플레이스홀더 암호, 평문 시크릿, `:?`→`:-` 완화 |
+| **D-26** | `nats_conf_jetstream_and_mqtt_contract` | `store_dir` 절대경로 + compose 볼륨 타깃과 **동일**; `max_file`/`max_mem` 이 `^\d+[KMGT]$`; `mqtt {` + `port: 1883`; `MAM` 계정 `jetstream: enabled` | 추출 실패 시 실패 | `store_dir`↔볼륨 불일치(데이터 유실), 소문자 접미사, 계정 JS 누락 |
+| **D-27** | `observer_permissions_match_topic_root` | subject 리터럴이 `mqtt_common.DEFAULT_TOPIC_ROOT.replace("/",".")` 로 시작; `mam_observer` 에 `publish` `deny` 존재 | 리터럴 0건이면 실패 | M3 지문 토픽 전환 시 관측자 권한 고아화 |
+| **D-28** | `healthcheck_contract_and_image_coupling` | healthcheck 존재 + `/healthz` + `127.0.0.1:8222` + `wget`; **동일 테스트에서** 이미지가 alpine 계열임을 단언 | healthcheck 키 없으면 실패 | healthcheck 삭제, wget 없는 이미지 |
+| **D-29** | `env_secrets_never_tracked` | `git check-ignore docker/.env` rc == 0; `.env.example` 은 not-ignored; `git ls-files docker/.env` 빈 출력 | — | `.gitignore` 완화로 실제 시크릿 커밋 |
+| **D-30** 🆕 | `websocket_origin_policy_is_startable` | **활성**(비주석) 라인 기준: (a) `websocket {` 블록에 `no_tls: true` 존재(M-23); (b) `allowed_origins` 가 활성이라면 그 항목이 전부 `http://` 또는 `https://` 로 시작 — 특히 **`"*"` 금지**(M-22); (c) `nats.conf` 가 `/mqtt` 경로 주석을 포함해 N-7 지식이 유실되지 않음 | `websocket {` 블록을 못 찾으면 실패 | **챌린지 처방 2를 그대로 구현했을 때의 기동 불능**, `no_tls` 누락으로 인한 TLS 요구 에러, N-7 문서 소실 |
+
+### 4.3 뮤테이션 수용 기준 (구현 완료의 정의)
+
+가드는 **깨져야 할 때 깨지는 것이 증명되어야** 통과로 인정합니다. Creator 는 아래를 각각 적용 → 해당 테스트 FAIL 확인 → 원복하고, 로그를 커밋 메시지 또는 리뷰 요청에 첨부합니다.
+
+| 뮤테이션 | FAIL 해야 하는 가드 |
+|---|---|
+| `docker-compose.yaml` 을 0바이트로 되돌림 | D-22 |
+| 이미지를 `nats:latest` 로 변경 | D-23, D-28 |
+| `- "1883:1883"` (바인드 주소 제거) | D-24 |
+| `8222` 를 `0.0.0.0:8222:8222` 로 변경 | D-24 |
+| `.env.example` 의 `MAM_BROKER_PASS=` → `=changeme` | D-25 |
+| compose 의 `:?` → `:-` 로 완화 | D-25 |
+| `store_dir: "/data"` → `"/var/lib/nats"` (볼륨 유지) | D-26 |
+| `subscribe.allow` 를 `"mam.>"` 로 변경 | D-27 |
+| healthcheck 블록 삭제 | D-28 |
+| `.gitignore` 에 `!docker/.env` 추가 | D-29 |
+| **`allowed_origins: ["*"]` 를 활성 라인으로 추가** | **D-30** |
+| **`websocket {}` 에서 `no_tls: true` 삭제** | **D-30** |
+
+> [!IMPORTANT]
+> **D-22 는 착수 시점에 이미 FAIL 합니다** (0바이트 compose 파일 때문). 가드를 먼저 커밋하고 자산을 채우는 **테스트 우선 순서**로 진행하면, 이 가드가 공허하게 통과하지 않는다는 사실이 별도 뮤테이션 없이 자동 증명됩니다.
+
+### 4.4 예상 테스트 수
+
+| 시점 | 수 |
+|---|---|
+| 현재 (`3523b9b`) — 실측 | **297** |
+| D-22 ~ D-30 추가 후 | **306** |
+
+---
+
+## 5. 문서 동기화 작업 (Creator 범위)
+
+`docker/` 만 만들고 문서를 두면 다음 리뷰에서 "무엇이 정본인가"가 다시 논쟁이 됩니다. 아래 5건을 **같은 커밋**에 포함합니다.
+
+| ID | 파일 | 작업 |
+|---|---|---|
+| **T-1** | `PRIVATE_SERVER.md` §9 서두 | "본 절의 설정은 [`docker/`](docker/) 에 정본 파일로 존재하며 아래 펜스는 그 사본입니다. 어긋나면 `tests/test_deploy_freshness.py` 의 D-22~D-30 이 실패합니다." 1문단 추가 |
+| **T-2** | `PRIVATE_SERVER.md` §9.1 / §9.2 | 펜스를 `docker/nats.conf`·`docker/docker-compose.yaml` 최종본과 **일치**시킴 (`version: '3.8'` 제거, **§3.1 의 websocket 주석 블록 포함**) |
+| **T-3** | `PRIVATE_SERVER.md` §9.2 제목 · §9.3 `.env` 블록 | `docker-compose.yml` → `docker/docker-compose.yaml`; `.env` 생성 절차를 `docker/.env.example` 복사 방식으로 교체 |
+| **T-4** | `implementation_plan.md` §5 / §8 | §5 로드맵에 **P0.5 `docker/` 자산 정본화** 삽입; §8 M2b 에서 이미 완료된 `G-D5~G-D9, G-R1, G-R2` 를 `[x]` 로 정정(N-4)하고 `docker/` 자산 + D-22~D-30 (297 → 306) 항목 신설 |
+| **T-5** 🆕 | `PRIVATE_SERVER.md` §5.1 / §5.2 | '두 개의 소비 평면' 서술에 **세 번째 경로**를 명문화: 8080 은 NATS WebSocket 과 **MQTT-over-WebSocket(`/mqtt`)** 을 함께 서빙하며, 후자만 retained 종료 이벤트를 받는다(N-1 ↔ N-7 연결). §5.2 의 브리징 문단이 현재 이 구분 없이 서술되어 있어 정정 대상 |
+
+T-2 수행 시 주의: §9.1/§9.2 펜스는 기존 D-15 ~ D-19 가드의 검사 대상이기도 하므로, 편집 후 **전체 스위트를 돌려** 기존 7종 가드의 회귀 없음을 확인해야 합니다.
+
+---
+
+## 6. 실행 순서 및 완료 정의
+
+```
+[1] 가드 선행 커밋 ──> [2] docker/ 자산 작성 ──> [3] 문서 동기화 ──> [4] 뮤테이션 검증 ──> [5] 서버 실배포
+    D-22~D-30 추가        3.1~3.4 (4개 파일)      T-1~T-5          §4.3 12건 전건        R-1~R-10 (+R-11)
+    D-22 FAIL 확인        306 전건 GREEN          기존 D-15~D-19    각 FAIL→원복          (별도 잡)
+                                                  회귀 없음
+```
+
+**DoD (본 잡의 완료 정의)**
+1. `docker/` 4개 파일이 §3 사양대로 존재하고, `docker/.env` 는 존재하지 않는다.
+2. `pytest tests/ -q` 가 **306건 전건 통과**.
+3. §4.3 뮤테이션 12건이 각각 지정된 가드를 FAIL 시킴이 로그로 확인된다.
+4. T-1 ~ T-5 문서 동기화가 동일 커밋에 포함된다.
+5. `git status` 에 `docker/.env` 가 나타나지 않는다(D-29 로 자동 보증).
+
+**게이트**: 3번(뮤테이션 전건 FAIL) 미충족 시 커밋 금지. 통과하지 않는 가드는 가드가 아니라 주석입니다.
+
+**신규 원격 검증 항목** (서버 배포 잡으로 이월):
+
+| ID | 검증 | 방법 | 통과 기준 |
+|---|---|---|---|
+| **R-11** | healthcheck 의 음성 대조 | 컨테이너 안에서 `wget -q -O /dev/null http://127.0.0.1:8222/healthzX` (404) | **비영점 종료** — 200 이 아닐 때 실제로 실패함을 증명 |
+| **R-12** | 교차 출처 브라우저 접속 | 다른 오리진의 페이지에서 `new WebSocket("ws://<host>:8080/")` | **핸드셰이크 성공** (A-2 의 반증 가능 형태 — 403 이 나오면 M-19/M-20 판정이 틀린 것) |
+| **R-13** | MQTT-over-WS retained | 잡 종료 **후** MQTT.js 로 `ws://<host>:8080/mqtt` 접속 → 구독 | **retained 최종 이벤트 수신** (N-7 확증. 0건이면 N-7 이 틀린 것) |
+
+R-12 와 R-13 은 **의도적으로 반증 가능하게** 작성했습니다. 실측이 틀렸다면 이 두 항목에서 드러나며, 그 경우 §A-2 와 §A-5 를 폐기하고 챌린지의 처방 1을 재검토해야 합니다.
+
+**본 잡 범위 밖**: 실제 서버 프로비저닝, Tailscale 가입, `.mam.env` 전환, R-1 ~ R-13 실행.
+
+---
+
+## 7. 발견 사항 (Findings)
+
+### N-2 (P2) — `PyYAML` 이 선언되지 않은 하드 테스트 의존
+`requirements.txt` 는 `pytest>=8.0` **단 한 줄**인데 `tests/test_sanity.py:3` 은 최상단에서 `import yaml` 합니다. 현재 venv 에는 설치되어 있어 드러나지 않지만, `requirements.txt` 만으로 새 venv 를 만들면 **수집 단계에서 다수 파일이 에러**납니다. D-22 ~ D-28 이 `yaml` 의존을 더 깊게 만듭니다.
+**처방**: `requirements.txt` 에 `PyYAML>=6.0` 추가. (`pytest.importorskip` 은 부적절 — 스킵되면 배포 가드가 조용히 사라집니다.)
+
+### N-3 (P2) — D-16 가드의 구멍: `nats:2.12` 가 통과한다
+`tests/test_deploy_freshness.py:387` 의 `assert "-alpine" in tag or tag.startswith("2.")` 는 `or` 때문에 `nats:2.12`(non-alpine) 나 `nats:2.12-scratch` 를 통과시킵니다. 그런데 healthcheck 는 alpine 에만 있는 `wget` 을 씁니다(M-3). 즉 D-16 은 자신이 막으려던 실패 모드의 **인접 변종을 놓칩니다**.
+**처방**: `assert "alpine" in tag` 로 단순화.
+
+### N-4 (P3) — `implementation_plan.md` 체크리스트가 실제보다 뒤처짐
+§8 M2b 의 `- [ ] 신규 가드 G-D5 ~ G-D9, G-R1, G-R2 …(290 -> 297)` 이 미체크이나 실측 수집 수는 **297** 이고 D-15 ~ D-21 이 이미 존재합니다. T-4 에서 정정합니다.
+
+### N-5 (P2) — NATS 는 환경변수 값을 **설정 렉서로 재파싱**한다
+`conf/parse.go` 의 `lookupVariable` 은 환경변수를 `parseEnv(fmt.Sprintf("%s=%s", pkey, vStr), p)` 로 **다시 파싱**합니다(M-7). 비인용 문자열 종결자는 NL·EOF·`;`·`,`·`]`·`}`·공백(M-8)이며 `#`·`$`·따옴표도 위험합니다. 문서는 `openssl rand -base64 32` 를 쓰면서 **왜 그래야 하는지**를 적지 않았습니다. §3.1/§3.3 주석과 README 트러블슈팅에 명문화합니다.
+
+### N-6 (P3) — 크기 접미사는 대문자 전용
+`opts.go:2507` `suffixMap` 은 `{"K","M","G","T"}` 뿐. `max_file: 10g` 는 기동 실패. D-26 이 `^\d+[KMGT]$` 로 봉인합니다.
+
+### N-7 (P1, 신규) — 8080 은 `/mqtt` 경로로 MQTT-over-WebSocket 을 서빙한다
+§A-5 참조. `mqttWSPath = "/mqtt"`(`mqtt.go:193`)이며 `websocket.go:1334-1335` 가 네이티브 1883 리스너와 **동일한 `createMQTTClient`** 로 분기합니다. 게이트는 `opts.MQTT.Port != 0` 뿐이라 우리 설정에서 **이미 활성**입니다. 세 가지 귀결:
+1. 브라우저 대시보드가 MQTT.js 로 `/mqtt` 에 붙으면 **retained 종료 이벤트를 받습니다** → Rev.2 이래의 열린 질문 해소, JetStream 리플레이 스트림 불필요.
+2. 같은 포트에 경로만 다르게 붙으면(NATS 네이티브) N-1 이 그대로 적용되어 종료 이벤트를 못 받습니다. **같은 포트, 다른 경로, 다른 결과** — 함정입니다.
+3. 노출 모델 서술 정정 필요: 8080 은 'Plane B 전용'이 아니라 **MQTT 프로토콜 표면을 함께 노출**합니다(인증은 동일 계정 규칙으로 강제).
+
+### N-1 재확인 (기존) — retained 는 MQTT 전용
+`mqttSendRetainedMsgsToNewSubs` 가 `mqttPacketSub` 핸들러에서만 호출되고 MQTT 전용 필드 `sub.mqtt.prm` 를 순회한다는 Rev.2 실측은 유효합니다. 다만 N-7 로 **경계가 프로토콜이지 포트가 아님**이 분명해졌습니다 — MQTT-over-WS 도 MQTT 이므로 retained 를 받습니다.
+
+---
+
+## 8. 열린 질문 (비차단)
+
+계획은 아래 답 없이 그대로 실행 가능합니다. 기본값을 명시했으므로 **응답이 없으면 기본값으로 진행**합니다.
+
+| # | 질문 | 기본값(무응답 시) |
+|---|---|---|
+| **Q-1** | 이미지 핀을 `nats:2.12-alpine`(마이너 추종) 로 둘 것인가, `2.12.15-alpine`(패치 고정) 으로 조일 것인가? | `2.12-alpine` 유지 — 문서 §9.2 와 일치, 보안 패치 자동 수령 |
+| **Q-2** | 컨테이너를 비루트(`user: "1000:1000"`) 로 돌릴 것인가? | 변경하지 않음 — `nats-data` 볼륨 소유권 초기화가 필요해 무증상 실패 위험. 별도 하드닝 잡으로 분리 |
+| **Q-3** | `docker/` 를 `deploy/install.sh` 로 하위 워크스페이스에 배포할 것인가? | 배포하지 않음 (D-8) |
+| **Q-4** | `.mam.env` 의 `MQTT_PASSWORD` ↔ 서버 `docker/.env` 의 `MAM_BROKER_PASS` 동기화를 스크립트화할 것인가? | 수동 — 두 파일이 다른 호스트에 있어 자동화는 시크릿 전송 경로를 새로 만드는 일. README 6절에 절차만 기술 |
+| **Q-5** 🆕 | 대시보드 프로토콜: MQTT.js(`/mqtt`) 로 통일할 것인가, `nats.ws` 도 허용할 것인가? | **MQTT.js 단일 권장.** retained 를 무상으로 얻고 N-1 함정이 사라짐. `nats.ws` 는 KV/JetStream 같은 NATS 고유 기능이 필요할 때만 |
+
+> Rev.2(`b11d499d`) 이래 이월되던 *"대시보드를 MQTT 로 붙일 것인가, JetStream 리플레이 스트림의 디스크 관리 부담을 수용할 것인가"* 는 **N-7 로 해소**되어 목록에서 제거했습니다. 브라우저에서도 MQTT 를 쓸 수 있으므로 리플레이 스트림은 불필요합니다.
+
+---
+
+## 9. 부록 — Creator 착수 체크리스트
+
+- [ ] `tests/test_deploy_freshness.py` 에 §4.1 헬퍼(`_load_compose`, `_active_conf_lines`) + D-22 ~ D-30 추가 → `pytest -k d22` 가 **FAIL** 하는지 먼저 확인
+- [ ] `requirements.txt` 에 `PyYAML>=6.0` 추가 (N-2)
+- [ ] `docker/nats.conf` 작성 — **websocket 주석 블록 포함** (§3.1)
+- [ ] `docker/docker-compose.yaml` 작성 — 기존 0바이트 파일 덮어쓰기 (§3.2)
+- [ ] `docker/.env.example` 작성 — 시크릿 4종 **빈 값** 확인 (§3.3)
+- [ ] `docker/README.md` 작성 — 브라우저 레시피 + 트러블슈팅 12행 (§3.4)
+- [ ] `PRIVATE_SERVER.md` T-1 ~ T-3, **T-5** (§5)
+- [ ] `implementation_plan.md` T-4 (§5)
+- [ ] D-16 단언 정정 (N-3)
+- [ ] `pytest tests/ -q` → **306 passed**
+- [ ] §4.3 뮤테이션 **12건** 각각 FAIL 확인 후 원복, 로그 첨부
+- [ ] `git status` 에 `docker/.env` 부재 확인
+- [ ] ⚠️ **`allowed_origins: ["*"]` 를 활성 설정으로 넣지 말 것** — 브로커가 기동하지 못합니다 (§A-3, M-22)
@@ -0,0 +1,212 @@
+# Cross-Code Review Report — Job 1ed5cf56
+
+- **Job ID**: `1ed5cf56`
+- **Reviewer**: cline
+- **Date**: 2026-08-23
+- **Scope**: Comprehensive code and security review of commit `b09d420` (`git diff main..refactor`) — Track 1R Docker deployment assets, test guards D-22~D-30, and documentation parity.
+- **Changeset**: 1 commit, 10 files changed (1524 insertions, 51 deletions)
+
+---
+
+## 1. Executive Summary
+
+This review independently evaluates the production Docker deployment assets for the MAM `nats-server` remote broker, the D-22~D-30 regression guards, documentation parity between `PRIVATE_SERVER.md` / `docker/README.md` / `implementation_plan.md`, and the full test suite. The changeset is well-structured, security-conscious, and fully tested. No blocking defects, security vulnerabilities, or correctness issues were found. Two Medium-severity documentation consistency findings and two Low-severity documentation issues are reported as actionable improvements.
+
+**[VERDICT: PASS]**
+
+---
+
+## 2. Changeset Overview
+
+| File | Change |
+|---|---|
+| `docker/docker-compose.yaml` | **New** (40 lines) — Production compose for `nats:2.12-alpine` |
+| `docker/nats.conf` | **New** (75 lines) — NATS server config (JetStream, MQTT, WebSocket, accounts) |
+| `docker/.env.example` | **New** (47 lines) — Secret template (empty values, fail-closed) |
+| `docker/README.md` | **New** (158 lines) — Deployment guide + verification playbook |
+| `tests/test_deploy_freshness.py` | **Modified** (+234 lines) — D-22~D-30 guards + D-16 tightening |
+| `PRIVATE_SERVER.md` | **Modified** (+129/-...) — §5.1/§5.2 transport paths, §9 canonical-asset note, §9.4 R-table |
+| `implementation_plan.md` | **Modified** (+21/-...) — P0.5 step, M2b checklist updates |
+| `requirements.txt` | **New** (2 lines) — `pytest>=8.0`, `PyYAML>=6.0` |
+
+---
+
+## 3. Review Area 1 — Docker Assets
+
+### 3.1 Security ✅
+
+| Check | Result |
+|---|---|
+| Fail-closed secrets (compose `${VAR:?error}`) | ✅ All 4 secrets use `${VAR:?set ...}` — empty `.env` aborts container creation |
+| No literal secrets in `nats.conf` | ✅ All `password:` values are `$VAR` references; regex `password:\s*([^\s,}]+)` confirms no plaintext |
+| `.gitignore` excludes `docker/.env`, tracks `.env.example` | ✅ D-29 verifies: `git check-ignore docker/.env` → ignored; `.env.example` → not ignored; `git ls-files docker/.env` → empty |
+| Loopback binding by default | ✅ `MQTT_BIND`, `NATS_BIND`, `WS_BIND` default to `127.0.0.1` via `${VAR:-127.0.0.1}` |
+| 8222 monitoring port hardcoded loopback | ✅ `127.0.0.1:8222:8222` — no variable override (unauthenticated endpoint) |
+| Observer write-protected | ✅ `publish: { deny: [">"] }` — observer cannot publish any subject |
+| Account isolation | ✅ `MAM`, `HOME`, `SYS` are separate NATS accounts; cross-account subjects invisible |
+| UFW bypass documented | ✅ Both `docker/README.md` §4 and `PRIVATE_SERVER.md` §9.2 WARNING explain Docker port-bypass |
+
+### 3.2 Correctness ✅
+
+| Check | Result |
+|---|---|
+| Image pinned `nats:2.12-alpine` (not `latest`) | ✅ D-23 enforces; tag found in PRIVATE_SERVER.md |
+| Healthcheck uses alpine `wget` → `/healthz` on `127.0.0.1:8222` | ✅ D-28 verifies `wget`, `/healthz`, `127.0.0.1:8222`, `"alpine" in image` |
+| JetStream `store_dir: "/data"` matches volume `/data` | ✅ D-26 verifies both sides |
+| `max_file: 10G`, `max_mem: 256M` (uppercase suffix) | ✅ D-26 regex `^\d+[KMGT]$` |
+| MQTT port 1883, `ack_wait: 60s`, `max_ack_pending: 1024` | ✅ |
+| WebSocket `no_tls: true` (required for startup) | ✅ D-30 enforces presence in active config |
+| `system_account: SYS` | ✅ |
+| MAM account `jetstream: enabled` (required for MQTT retained) | ✅ D-26 verifies |
+| `/mqtt` WebSocket path documented (N-7) | ✅ D-30 verifies `/mqtt` in conf |
+| `allowed_origins` never `"*"` (NATS rejects it) | ✅ D-30 scans active lines |
+
+### 3.3 Byte-Level Parity (docker/ ↔ PRIVATE_SERVER.md) ✅
+
+Automated comparison confirms exact byte-for-byte match (after strip) between:
+- `docker/nats.conf` ↔ `PRIVATE_SERVER.md` §9.1 code fence → **MATCH**
+- `docker/docker-compose.yaml` ↔ `PRIVATE_SERVER.md` §9.2 code fence → **MATCH**
+
+---
+
+## 4. Review Area 2 — Test Coverage (D-22 ~ D-30)
+
+Nine new guards protect the docker/ canonical assets against silent drift. Each was reviewed for correctness, mutation-sensitivity, and false-positive risk.
+
+| Guard | Purpose | Assessment |
+|---|---|---|
+| **D-22** | All 4 docker/ assets exist and are non-empty; compose parses as YAML with a `nats` service | ✅ Catches accidentally-empty or unpopulated assets |
+| **D-23** | Compose image tag ≠ `latest`, contains `alpine`, and the tag appears in PRIVATE_SERVER.md | ✅ Cross-doc coupling; catches pin drift |
+| **D-24** | Exactly 4 container ports (1883, 4222, 8222, 8080); all mappings are 3-part; 8222 hardcoded to `127.0.0.1:8222:8222` | ✅ Prevents bare port mappings and monitoring port exposure |
+| **D-25** | `$VAR` refs in active nats.conf ⊆ compose environment keys; all env values use `${VAR:?error}`; `.env.example` secrets are empty; no literal passwords in conf | ✅ Comprehensive fail-closed enforcement; catches placeholder secrets |
+| **D-26** | Volume mounts to `/data`; `store_dir: "/data"`; `max_file`/`max_mem` match `^\d+[KMGT]$`; `mqtt {` block with `port: 1883`; `MAM:` account has `jetstream: enabled` | ✅ JetStream/MQTT contract integrity |
+| **D-27** | Job subjects in nats.conf start with `python.mqtt.jobs.` (= `DEFAULT_TOPIC_ROOT` dotted); `mam_observer` present with `deny:` | ✅ Observer permissions track topic root; catches topic-root migration drift |
+| **D-28** | Healthcheck uses `wget`, targets `/healthz` at `127.0.0.1:8222`; image contains `alpine` | ✅ Healthcheck/image coupling; catches non-alpine image swap |
+| **D-29** | `docker/.env` git-ignored; `docker/.env.example` NOT ignored; `docker/.env` never tracked | ✅ Secret hygiene via `.gitignore` (lines 21-23: `.env` / `.env.*` / `!.env.example`) |
+| **D-30** | Active conf has `websocket {` + `no_tls: true`; no `"*"` in `allowed_origins`; `/mqtt` path documented | ✅ WebSocket startup safety; catches star-origin and missing MQTT path |
+
+### D-16 Guard Tightening
+
+D-16 (`test_d16_private_server_nats_image_alpine_pinned`) was tightened from the previous looser check to `assert "alpine" in tag`. This is correct: the healthcheck uses `wget` which only exists in the `alpine` variant, so any non-alpine image would produce a permanently `unhealthy` container. The tighter assertion closes the gap where a tag like `nats:2.12-scratch` would have passed.
+
+### Coverage Assessment
+
+The D-22~D-30 suite provides **comprehensive regression protection** for the docker/ assets. Key strengths:
+- **Cross-document coupling** (D-23, D-27) ties compose/conf to PRIVATE_SERVER.md and `mqtt_common.DEFAULT_TOPIC_ROOT`, preventing silent drift.
+- **Active-line filtering** (`_active_conf_lines()`) strips comments before assertion, preventing false passes from commented-out templates.
+- **Defense-in-depth** — fail-closed (D-25), port exposure (D-24), healthcheck coupling (D-28), and secret hygiene (D-29) are independently guarded.
+
+---
+
+## 5. Review Area 3 — Documentation Parity
+
+### 5.1 Byte-Level Parity (docker/ ↔ PRIVATE_SERVER.md) ✅
+
+As confirmed in §3.3, the `nats.conf` and `docker-compose.yaml` code fences in `PRIVATE_SERVER.md` §9.1/§9.2 are byte-for-byte identical to the canonical `docker/` files. The §9 NOTE correctly declares `docker/` as canonical and warns that D-22~D-30 guards enforce parity.
+
+### 5.2 R-ID Collision (PRIVATE_SERVER.md §9.4 vs docker/README.md §7) — M-1
+
+Both documents define an "R-1 ~ R-10" verification playbook table, but **6 of 10 R-IDs have different meanings**:
+
+| R-ID | PRIVATE_SERVER.md §9.4 | docker/README.md §7 | Match? |
+|---|---|---|---|
+| R-1 | Broker health (curl /healthz) | Health endpoint (curl /healthz) | ✅ Same |
+| R-2 | Listener + TLS identity (varz, SAN) | External monitoring blocked (curl public IP) | ❌ **Different** |
+| R-3 | Port exposure assertion (nmap) | Port exposure (nmap) | ✅ Same |
+| R-4 | Round-trip pub/sub + JetStream | WAN latency (`python latency_check.py`) | ❌ **Different** |
+| R-5 | Retained terminal event (MQTT) | Auth rejection (Not authorized) | ❌ **Different** |
+| R-6 | Broker identity assertion (no hivemq) | Auth success (rc=0) | ❌ **Different** |
+| R-7 | Freeze regression (H-1/H-4) | Retained event delivery | ❌ **Different** |
+| R-8 | Full regression suite (pytest) | Broker identifier (mam-hub) | ❌ **Different** |
+| R-9 | Observer account boundary | Tenant account isolation | ✅ Same |
+| R-10 | Retained boundary (N-1) | Retained boundary (N-1/N-7) | ✅ Same |
+
+**Impact**: An operator cross-referencing "R-5" between the two documents would execute the wrong test. For example, README's R-7 (retained delivery) ≈ PRIVATE_SERVER's R-5 (retained terminal event) — same concept, different number.
+
+**Recommendation**: Re-number the README table (e.g., `RD-1`~`RD-10` or a distinct prefix) or align both tables to a single canonical definition in PRIVATE_SERVER.md and have README reference it.
+
+### 5.3 Undefined R-11/R-12/R-13 — M-2
+
+`implementation_plan.md` references R-11~R-13 (specifically R-13 as a "final gate"), but neither `PRIVATE_SERVER.md` §9.4 nor `docker/README.md` §7 defines them:
+
+- `implementation_plan.md:122` — `R-1 ~ R-13. R-5(retained) / R-9(계정 경계) / R-13(MQTT-over-WS)`
+- `implementation_plan.md:182` — `R-1 ~ R-13 전건 통과 (R-5 / R-9 / R-13 최종 관문)`
+
+R-13 is described as "MQTT-over-WS" verification (the `/mqtt` WebSocket path from N-7), which is operationally critical, but no command/pass-criteria row exists for it in either document.
+
+**Recommendation**: Add R-11, R-12, R-13 rows to the PRIVATE_SERVER.md §9.4 table (canonical source) and update docker/README.md §7 to reference rather than duplicate.
+
+### 5.4 `latency_check.py` Reference — L-1
+
+`docker/README.md` §7 R-4 instructs `python latency_check.py` (expected: RTT P95 < 150ms), but **no `latency_check.py` file exists** anywhere in the repository (`find` confirms zero results). The canonical latency probe lives as an inline Python heredoc in `PRIVATE_SERVER.md` §9.4 (below the R-table). This is compounded by the R-4 collision (§5.2): README's R-4 is WAN latency, PRIVATE_SERVER's R-4 is pub/sub+JetStream.
+
+**Recommendation**: Either ship a `docker/latency_check.py` script or replace the README reference with the inline heredoc from PRIVATE_SERVER.md.
+
+### 5.5 UFW Rules Divergence — L-2
+
+| Rule | docker/README.md §4 | PRIVATE_SERVER.md §9.3 |
+|---|---|---|
+| Tailnet allow | `sudo ufw allow in on tailscale0 to any` (all ports) | `sudo ufw allow in on tailscale0 to any port 1883/4222/8080 proto tcp` (granular) |
+| SSH | `sudo ufw allow ssh` | `sudo ufw allow 22/tcp` |
+
+The README's broader `allow in on tailscale0 to any` is more permissive than PRIVATE_SERVER.md's granular per-port rules. Since Docker bypasses UFW (documented in both), UFW is secondary defense — but the README's broader rule weakens defense-in-depth on the tailnet interface.
+
+**Recommendation**: Align README §4 UFW rules with PRIVATE_SERVER.md §9.3 granular per-port rules.
+
+### 5.6 implementation_plan.md P0.5 Diagram Alignment — V-1
+
+The new P0.5 step was inserted into the §5 roadmap diagram. The `▼` markers and label spacing were adjusted, but content columns are not perfectly aligned across all lines (Korean double-width characters cause visual offset). Purely cosmetic; no functional impact.
+
+---
+
+## 6. Review Area 4 — Full Test Suite
+
+Command: `.venv/bin/python -m pytest tests/ -q`
+
+```
+306 passed in 353.84s (0:05:53)
+```
+
+| Metric | Value |
+|---|---|
+| Total tests collected | 306 |
+| Passed | 306 |
+| Failed | 0 |
+| Errors | 0 |
+| Skipped | 0 |
+| Duration | 353.84s |
+
+**Result**: 100% pass rate, 0 regressions. The full suite includes all unit tests, the 29 deploy-freshness guards (D-1~D-30), 5 tier3 integration tests, and 5 tier4 e2e tests. All green.
+
+Subset verification (fast path, 29s): `tests/test_deploy_freshness.py + tests/test_sanity.py + tests/test_tier1_unit.py` → **76 passed in 29.14s**.
+
+---
+
+## 7. Findings Summary
+
+| ID | Severity | Area | Description | Actionable? |
+|---|---|---|---|---|
+| M-1 | Medium | Docs parity | R-1~R-10 ID collision: 6/10 R-IDs have different meanings between PRIVATE_SERVER.md §9.4 and docker/README.md §7 | Yes — re-number or canonicalize |
+| M-2 | Medium | Docs parity | R-11, R-12, R-13 referenced in implementation_plan.md but undefined in both R-tables; R-13 is a "final gate" | Yes — add rows to §9.4 |
+| L-1 | Low | Docs | docker/README.md §7 R-4 references non-existent `latency_check.py` | Yes — ship script or use inline heredoc |
+| L-2 | Low | Docs | UFW rules in README §4 more permissive than PRIVATE_SERVER.md §9.3 | Yes — align to granular rules |
+| V-1 | Very Low | Cosmetic | P0.5 diagram label alignment inconsistent in implementation_plan.md | Optional |
+
+### Positive Highlights
+
+- **Fail-closed by design**: Empty `.env` aborts `docker compose up` before container creation. No placeholder secrets accepted.
+- **No secrets in source**: `nats.conf` contains only `$VAR` references; `password:` regex scan confirms zero literals.
+- **Loopback-first**: All variable-controlled ports default to `127.0.0.1`; 8222 is hardcoded loopback (unauthenticated monitoring).
+- **Healthcheck/image coupling**: D-28 enforces that the alpine image (providing `wget`) matches the healthcheck command — a subtle but critical invariant.
+- **D-16 tightening**: `assert "alpine" in tag` correctly prevents non-alpine images that would silently break the healthcheck.
+- **Byte-level parity**: docker/ canonical files are exact copies of PRIVATE_SERVER.md code fences; D-22~D-30 guards enforce this automatically.
+- **Active-line filtering**: `_active_conf_lines()` strips comments before assertions, preventing commented-out templates from causing false passes.
+- **Previous M-1 (missing 4222 port) resolved**: The current compose exposes all 4 ports (1883, 4222, 8222, 8080); D-24 enforces the complete set.
+
+### No Escalation Required
+
+All findings are documentation-level improvements (M/L/V severity). No blocking defects, security vulnerabilities, correctness errors, or architectural rework needs were identified. The implementation is production-ready.
+
+---
+
+[VERDICT: PASS]
@@ -0,0 +1,196 @@
+# Cross-Code Review Report — Job `354f9a22`
+
+- **Reviewer**: cline (session `herdr:canary-projects-multi-agent-mux-creator-cline`)
+- **Date**: 2026-08-23
+- **Changeset**: uncommitted working-tree, 3 files, +20/-1 (`deploy/INSTALL.md`, `deploy/README.md`, `deploy/install.sh`)
+- **Scope**: Cross-code review (lint / behavior / loss) of `deploy/` scripts & documentation
+  synchronization against the latest NATS messaging architecture and the `nats-docker`
+  submodule integration.
+
+---
+
+## 1. Changeset Summary
+
+| File | Δ | Nature |
+|---|---|---|
+| `deploy/INSTALL.md` | +6 | New §7 "전용 NATS 메시징 브로커 설정 (.mam.env)": `.mam.env` generation, `git submodule update --init --recursive` guidance, links to `nats-docker/PRIVATE_SERVER.md` + `MESSAGING.md` |
+| `deploy/README.md` | +13 | New §5 "Private NATS Broker & Submodule Integration (nats-docker)": broker description, `git clone --recurse-submodules` / `git submodule update --init --recursive` commands, links to `nats-docker/PRIVATE_SERVER.md` + `MESSAGING.md` |
+| `deploy/install.sh` | +1/-1 | Inline `.mam.env` default `MAM_CLIENT_PREFIX`: `mam-agent` → `hermes` |
+
+---
+
+## 2. Verification Methodology
+
+1. Gathered changeset via `git diff --stat` / `git --no-pager diff`.
+2. Audited all `deploy/` files for submodule-init support, stale root-`docker/` references,
+   and `MQTT_CLIENT_ID_PREFIX` default alignment.
+3. Verified cross-reference link resolution for every new doc link (target existence +
+   relative-path correctness vs. the document's location under `deploy/`).
+4. Confirmed `MAM_CLIENT_PREFIX="hermes"` consistency across `install.sh`, `.mam.env.example`,
+   `MESSAGING.md`, and `mqtt_common.py`.
+5. Verified `deploy/generate-env.sh` (the `.mam.env` generation path referenced by INSTALL.md)
+   works and relies on the committed `.mam.env.example` template.
+6. Verified `deploy/gitea-ci.yml` test job enables `submodules: recursive`.
+7. Ran mandated tests: `.venv/bin/python -m pytest tests/test_deploy_freshness.py tests/test_sanity.py -q`.
+
+---
+
+## 3. Verification Results
+
+### 3.1 `deploy/install.sh` — `MAM_CLIENT_PREFIX` default — PASS
+- Line 509: `MAM_CLIENT_PREFIX="hermes"` (was `mam-agent`), written to `MQTT_CLIENT_ID_PREFIX=hermes`
+  in the inline `.mam.env` block (line 520).
+- This now matches all other sources of the default:
+  - `mqtt_common.py:230` → `os.environ.get("MQTT_CLIENT_ID_PREFIX", "hermes")`
+  - `mqtt_common.py:218` docstring → `MQTT_CLIENT_ID_PREFIX (hermes)`
+  - `.mam.env.example:80-81` → `#default: hermes` / `# MQTT_CLIENT_ID_PREFIX=hermes`
+  - `MESSAGING.md:302` → `MQTT_CLIENT_ID_PREFIX | hermes`
+- No `mam-agent` references remain anywhere in code/docs (only in historical job briefs/logs).
+- The change is a correct, surgical alignment fix.
+
+### 3.2 Stale root `docker/` references — PASS
+- `grep -rn 'docker/' deploy/ | grep -v nats-docker` → **none found**.
+- All `deploy/` scripts (`install.sh`, `install_mam.sh`, `update.sh`, `remove.sh`,
+  `generate-env.sh`) and docs (`INSTALL.md`, `README.md`, `gitea-ci.yml`) contain zero
+  references to the removed root-level `docker/` directory. All Docker references now point to
+  the `nats-docker/` submodule. Migration is complete.
+
+### 3.3 Submodule initialization support — PASS
+- **CI**: `deploy/gitea-ci.yml` test job (line 82-89) uses `actions/checkout@v3` with
+  `submodules: recursive`, then runs `pytest tests/ -q`. Correct — CI test runs get the
+  `nats-docker` assets.
+- **Fresh install / update (documentation)**: `deploy/INSTALL.md` §7 and `deploy/README.md` §5
+  both instruct users to run `git submodule update --init --recursive` (README.md also shows
+  `git clone --recurse-submodules ...` for fresh clones).
+- **Scripts**: `install.sh`, `update.sh`, `install_mam.sh`, `remove.sh` do **not** auto-run
+  `git submodule update --init --recursive`. This is appropriate ("where appropriate" in the
+  task): the `nats-docker` submodule holds *optional private-broker deployment assets*
+  (docker-compose, nats.conf, guides), not the MAM runtime. Forcing git operations during a
+  user-environment install/update would be wrong for users who don't deploy a private broker
+  and could fail where git/submodule access is unavailable. Submodule init is therefore
+  *documented guidance* (present) rather than *automated* (correctly absent) — consistent
+  with the submodule being an optional deployment concern.
+
+### 3.4 `.mam.env` generation & default MQTT parameters — PASS
+- `deploy/generate-env.sh` copies `.mam.env.example` → `.mam.env` (idempotent, `--force`/
+  `--migrate-legacy` options, repo-root-relative path resolution). Works as documented.
+- `.mam.env.example` documents `MQTT_CLIENT_ID_PREFIX` default as `hermes` (line 80-81),
+  consistent with `install.sh` and code.
+- INSTALL.md §7 correctly directs users to `bash deploy/generate-env.sh` (or
+  `cp .mam.env.example .mam.env`) for `.mam.env` creation.
+- Note (pre-existing, **not** introduced by this changeset): `.mam.env.example:7` comments
+  `scripts/generate-env.sh` while the actual path is `deploy/generate-env.sh`. Out of scope
+  for this review; flagged for awareness only.
+
+### 3.5 `deploy/README.md` §5 — PASS
+- New §5 accurately describes the private NATS broker (`nats:2.12-alpine`, MQTT 3.1.1 +
+  JetStream) and the `nats-docker` submodule.
+- Provides both fresh-clone (`git clone --recurse-submodules <url>`) and existing-clone
+  (`git submodule update --init --recursive`) commands.
+- Clone URL `https://git.godopu.com/tmpl/multi-agent-mux.git` matches the actual remote origin.
+- Cross-reference links use the correct file-relative form:
+  `../nats-docker/PRIVATE_SERVER.md` and `../MESSAGING.md` (both resolve from `deploy/` to the
+  repo-root targets, confirmed to exist). ✓
+
+### 3.6 `deploy/INSTALL.md` §7 — see M-1 (link defect), content otherwise PASS
+- §7 content is accurate and well-placed: NATS broker purpose, `.mam.env` generation path,
+  submodule sync command, and broker/Tailscale guide pointer.
+- The `git submodule update --init --recursive` guidance is correct and consistent with
+  README.md §5.
+- **Link defect**: the two cross-reference links use a non-standard `file://./` scheme
+  (see Finding M-1). Content is correct; only the link URLs are wrong.
+
+### 3.7 Mandated tests — PASS
+- `.venv/bin/python -m pytest tests/test_deploy_freshness.py tests/test_sanity.py -q`
+  → **33 passed** in 22.58s. 100% pass rate, 0 regressions.
+- No test depends on the new doc sections, so the changeset is test-neutral; the prior D-31
+  (CI submodules) and D-32 (MESSAGING.md env coverage) guards remain green.
+
+---
+
+## 4. Detailed Findings
+
+### M-1 (Medium) — Non-standard / broken cross-reference links in `deploy/INSTALL.md` §7
+
+- **Location**: `deploy/INSTALL.md` line 134 (new §7):
+  - `[\`nats-docker/PRIVATE_SERVER.md\`](file://./nats-docker/PRIVATE_SERVER.md)`
+  - `[\`MESSAGING.md\`](file://./MESSAGING.md)`
+- **Observation**: These links use the `file://./<path>` URL scheme. Per RFC 8089, `file://`
+  introduces an authority; `file://./...` places a `.` (invalid) authority before the path, so
+  the form is non-standard. More importantly, `file://` URLs are **not** rewritten to
+  repo-relative paths by the Gitea/GitHub markdown renderer — they render as literal `file://`
+  links. Resolved relative to the document's location (`deploy/`), `./nats-docker/...` and
+  `./MESSAGING.md` point to `deploy/nats-docker/PRIVATE_SERVER.md` and `deploy/MESSAGING.md`,
+  both of which **do not exist** (confirmed: `deploy/nats-docker/` and `deploy/MESSAGING.md`
+  are missing; the real targets are at the repo root).
+- **Inconsistency**: The sibling `deploy/README.md` §5, added in the **same** changeset, uses
+  the correct file-relative form `../nats-docker/PRIVATE_SERVER.md` and `../MESSAGING.md`
+  (which resolve from `deploy/` to the repo-root targets). The two new sections therefore
+  disagree on link convention.
+- **Impact**: Medium. A user following INSTALL.md cannot click through to the private-broker
+  guide / MESSAGING reference in the Gitea web UI (the canonical viewing context). The link
+  *text* still shows the path, so a user can navigate manually, and README.md §5 provides
+  working links — impact is mitigated but the defect is real and functional (broken
+  navigation), not merely cosmetic. No runtime/test effect.
+- **Recommendation**: Replace the two `file://./` URLs with the file-relative form used by
+  README.md:
+  - `file://./nats-docker/PRIVATE_SERVER.md` → `../nats-docker/PRIVATE_SERVER.md`
+  - `file://./MESSAGING.md` → `../MESSAGING.md`
+  This is a 2-token surgical edit; no design change required.
+
+### Note (pre-existing, out of this changeset's scope)
+- `.mam.env.example:7` documents the generator path as `scripts/generate-env.sh` but the
+  actual location is `deploy/generate-env.sh`. This predates the changeset and is not
+  introduced or touched by it; flagged for awareness only (do not fix in this review's scope).
+
+### Positive observations
+- `install.sh` `MAM_CLIENT_PREFIX` → `hermes` is a clean, correct alignment that achieves
+  100% consistency across `mqtt_common.py`, `.mam.env.example`, `MESSAGING.md`, and fresh
+  `.mam.env` generation.
+- Zero stale root-`docker/` references across the entire `deploy/` tree.
+- Submodule-init guidance is consistently provided in both INSTALL.md and README.md, and CI
+  correctly automates it via `submodules: recursive`. Scripts appropriately do **not** force
+  the optional submodule during user install/update.
+- README.md §5 links and clone URL are correct.
+---
+
+## 5. Risk Assessment
+
+| Area | Status |
+|---|---|
+| Runtime behavior | No runtime code changed (docs + one shell default). `install.sh` default alignment is correct. PASS. |
+| Test suite | 33/33 mandated tests pass; 0 regressions. PASS. |
+| Stale references | Zero root-`docker/` references in `deploy/`. PASS. |
+| Submodule support | CI automates (`submodules: recursive`); docs guide manual init; scripts correctly leave optional submodule out of user install/update. PASS. |
+| `.mam.env` / MQTT defaults | `hermes` consistent across install.sh, .mam.env.example, MESSAGING.md, code. PASS. |
+| Cross-reference links | INSTALL.md §7 links use non-standard `file://./` → broken in Gitea renderer (M-1). README.md links correct. Minor / non-blocking. |
+| Loss / orphaned references | None — all `nats-docker/` and `MESSAGING.md` targets exist at repo root. PASS. |
+
+The single finding (M-1) is documentation-level, non-blocking, and fixable by a 2-token edit.
+No design-level rework is warranted; no `[ESCALATE: PLANNER]` is required.
+
+---
+
+## 6. Actionable Follow-up (optional, small cleanup commit)
+
+1. **M-1**: In `deploy/INSTALL.md` line 134, replace
+   `(file://./nats-docker/PRIVATE_SERVER.md)` → `(../nats-docker/PRIVATE_SERVER.md)` and
+   `(file://./MESSAGING.md)` → `(../MESSAGING.md)` to match README.md §5's working link form.
+2. *(Pre-existing, separate)*: Fix `.mam.env.example:7` path comment
+   `scripts/generate-env.sh` → `deploy/generate-env.sh`.
+
+---
+
+## 7. Verdict
+
+All mandated tests pass (33/33, 0 regressions). The `install.sh` `MAM_CLIENT_PREFIX` →
+`hermes` change correctly aligns the default across code, template, and docs. No stale
+root-`docker/` references remain anywhere in `deploy/`. Submodule initialization is properly
+supported (CI automates it; INSTALL.md and README.md document the manual step; scripts
+appropriately treat the optional `nats-docker` submodule as a deployment concern rather than
+a runtime one). The only finding (M-1) is a non-standard, non-functional cross-reference
+link scheme in `deploy/INSTALL.md` §7 — documentation-level, non-blocking, fixable by a
+2-token edit, and inconsistent only with the sibling README.md §5 added in the same changeset.
+No escalation to the planner is warranted.
+
+[VERDICT: PASS]
@@ -0,0 +1,350 @@
+# Cross-Code Review Report — Job 869d7874
+
+- **Reviewer**: cline (session: `herdr:canary-projects-multi-agent-mux-creator-cline`)
+- **Job ID**: 869d7874
+- **Review Target**: Commit `12ba30b` — `docs: move PRIVATE_SERVER.md and NATS_REPORT.md to nats-docker submodule`
+- **Base**: `origin/main` (commit `629a67f`)
+- **Date**: 2026-08-23
+- **Scope**: Pre-push review of all local commits ahead of remote (`origin/main..HEAD`), focusing on Git submodule configuration, test guard submodule compatibility, and legacy file removal/migration.
+
+---
+
+## 1. Executive Summary
+
+Commit `12ba30b` migrates two documentation files (`PRIVATE_SERVER.md`, `NATS_REPORT.md`) from the repository root into the `nats-docker` Git submodule and updates the deploy-freshness test suite to resolve their new locations dynamically. The submodule pointer is bumped from `c86cc98` → `a4b6e49`.
+
+**Changeset**: 4 files changed, +26 insertions, -772 deletions:
+- `NATS_REPORT.md` — **deleted** from root (176 lines)
+- `PRIVATE_SERVER.md` — **deleted** from root (584 lines)
+- `nats-docker` — submodule pointer updated (`c86cc98` → `a4b6e49`)
+- `tests/test_deploy_freshness.py` — added `_resolve_private_server_doc()`, updated D-11~D-19 + D-23 to use `PRIVATE_SERVER_DOC_PATH`
+
+**Verdict**: **[VERDICT: PASS]** — The migration is clean, byte-identical, and test-compatible. Two non-blocking documentation findings (orphaned markdown links and stale text references in `implementation_plan.md`).
+
+---
+
+## 2. Changeset Overview
+
+```
+12ba30b docs: move PRIVATE_SERVER.md and NATS_REPORT.md to nats-docker submodule
+
+ NATS_REPORT.md                 | 176 ---
+ PRIVATE_SERVER.md              | 584 ----
+ nats-docker                    |   2 +-
+ tests/test_deploy_freshness.py |  36 ++-
+ 4 files changed, 26 insertions(+), 772 deletions(-)
+```
+
+| File | Change | Lines |
+|---|---|---|
+| `NATS_REPORT.md` | Deleted from root; content now lives at `nats-docker/NATS_REPORT.md` | -176 |
+| `PRIVATE_SERVER.md` | Deleted from root; content now lives at `nats-docker/PRIVATE_SERVER.md` | -584 |
+| `nats-docker` | Submodule gitlink pointer updated `c86cc98` → `a4b6e49` | ±1 |
+| `tests/test_deploy_freshness.py` | New `_resolve_private_server_doc()` resolver; 9 test functions updated to use `PRIVATE_SERVER_DOC_PATH` | +26/-10 |
+
+### Commit Context (Accumulated Changeset `3523b9b..12ba30b`)
+
+The brief references the broader range `3523b9b..12ba30b` (4 commits). The first 3 commits (`3523b9b`, `b09d420`, `629a67f`) were already reviewed in job `1ed5cf56` (Track 1R Docker assets + D-22~D-30 guards). This review focuses on the new unpushed commit `12ba30b`, which is the final step in the submodule migration chain:
+
+| Commit | Description | Reviewed In |
+|---|---|---|
+| `3523b9b` | Established remote Docker deployment plan + D-15~D-21 guards | Job `1ed5cf56` |
+| `b09d420` | Created `docker/` assets + D-22~D-30 guards | Job `1ed5cf56` |
+| `629a67f` | Converted `docker/` to `nats-docker` submodule | Job `1ed5cf56` (prior state) |
+| **`12ba30b`** | **Moved docs to submodule + test resolver update** | **This review** |
+
+---
+
+## 3. Review Area 1 — Git Submodule Configuration
+
+### 3.1 `.gitmodules` ✅
+
+```ini
+[submodule "nats-docker"]
+    path = nats-docker
+    url = https://git.godopu.com/laa/nats-docker
+```
+
+- **Path**: `nats-docker` (relative to repo root) — correct
+- **URL**: `https://git.godopu.com/laa/nats-docker` — well-formed HTTPS URL
+- **Single submodule**: Only one submodule entry; no orphan or duplicate entries
+
+### 3.2 Submodule Pointer ✅
+
+```
+Parent records: Subproject commit a4b6e49a1f01dac4974fcd3c7e4e9382be665e33
+Submodule HEAD: a4b6e49a1f01dac4974fcd3c7e4e9382be665e33
+git submodule status: a4b6e49a1f01dac4974fcd3c7e4e9382be665e33 nats-docker (heads/main)
+```
+
+- Parent repo's gitlink and submodule's actual HEAD are **identical** (`a4b6e49`) — no detached/dirty state.
+- Mode `160000` (gitlink) — correct submodule entry type.
+- Previous pointer `c86cc98` → new pointer `a4b6e49` — the bump corresponds to the commit that added `PRIVATE_SERVER.md` and `NATS_REPORT.md` to the submodule.
+
+### 3.3 Submodule Git Directory ✅
+
+```
+nats-docker/.git → gitdir: ../.git/modules/docker
+.git/modules/docker/HEAD → ref: refs/heads/main
+```
+
+- Submodule's `.git` file correctly points to the parent's `.git/modules/docker/` directory (standard Git submodule layout).
+- HEAD tracks `refs/heads/main` — clean checkout, not detached.
+
+### 3.4 Submodule Contents ✅
+
+```
+nats-docker/
+├── .agents/
+├── .git (gitdir)
+├── .gitignore
+├── docker/
+│   ├── .env.example
+│   ├── docker-compose.yaml
+│   ├── nats.conf
+│   └── README.md
+├── NATS_REPORT.md
+├── PRIVATE_SERVER.md
+└── README.md
+```
+
+All expected assets are present. The `docker/` directory (moved in commit `629a67f`) and the two documentation files (moved in this commit `12ba30b`) coexist cleanly in the submodule.
+
+### 3.5 Byte-Level Content Verification ✅
+
+Verified that the moved files are **byte-for-byte identical** to the originals deleted from root:
+
+| File | Old root path | New submodule path | `diff` result |
+|---|---|---|---|
+| `PRIVATE_SERVER.md` | 584 lines (deleted) | `nats-docker/PRIVATE_SERVER.md` (584 lines) | **MATCH** (0 diff) |
+| `NATS_REPORT.md` | 176 lines (deleted) | `nats-docker/NATS_REPORT.md` (176 lines) | **MATCH** (0 diff) |
+
+No content was modified during the migration — pure file move.
+
+### 3.6 Submodule `.gitignore` ✅
+
+```gitignore
+# Environment files
+.env
+*.env
+!*.env.example
+
+# Runtime data & volumes
+docker/volumes/
+volumes/
+
+# Logs
+*.log
+```
+
+- `.env` and `*.env` are ignored; `!*.env.example` un-ignores the template — consistent with the parent repo's secret hygiene pattern.
+- `docker/volumes/` is ignored — runtime data won't leak into the submodule repo.
+
+---
+
+## 4. Review Area 2 — Test Guards (Submodule Compatibility)
+
+### 4.1 `_resolve_docker_dir()` ✅ (pre-existing, from commit `629a67f`)
+
+```python
+def _resolve_docker_dir() -> str:
+    for candidate in [
+        os.path.join(REPO_ROOT, "nats-docker", "docker"),  # submodule path (canonical)
+        os.path.join(REPO_ROOT, "nats-docker"),            # flat submodule layout
+        os.path.join(REPO_ROOT, "docker"),                 # legacy root path
+    ]:
+        if os.path.exists(os.path.join(candidate, "docker-compose.yaml")):
+            return candidate
+    return os.path.join(REPO_ROOT, "nats-docker", "docker")  # fail-safe default
+```
+
+- **Search order**: submodule → flat submodule → legacy root. Correct priority (new canonical first, legacy fallback last).
+- **Existence check**: Probes for `docker-compose.yaml` specifically, preventing false matches from empty directories.
+- **Fail-safe default**: Returns the expected canonical path even if nothing exists, so downstream assertions produce meaningful "file missing" errors rather than `None`-related crashes.
+- All D-22~D-30 guards use `DOCKER_DIR`, `COMPOSE_PATH`, `NATS_CONF_PATH`, `ENV_EXAMPLE_PATH`, `DOCKER_README_PATH` — all derived from this resolver. ✅
+
+### 4.2 `_resolve_private_server_doc()` ✅ (new in this commit)
+
+```python
+def _resolve_private_server_doc() -> str:
+    for candidate in [
+        os.path.join(REPO_ROOT, "nats-docker", "PRIVATE_SERVER.md"),      # submodule (canonical)
+        os.path.join(REPO_ROOT, "nats-docker", "docs", "PRIVATE_SERVER.md"), # alternate layout
+        os.path.join(REPO_ROOT, "PRIVATE_SERVER.md"),                     # legacy root
+    ]:
+        if os.path.exists(candidate):
+            return candidate
+    return os.path.join(REPO_ROOT, "nats-docker", "PRIVATE_SERVER.md")   # fail-safe default
+```
+
+- **Symmetrical design**: Mirrors `_resolve_docker_dir()`'s pattern — submodule first, legacy fallback last, fail-safe default.
+- **Alternate layout**: Includes `nats-docker/docs/` as a candidate, future-proofing against a potential reorganization within the submodule.
+- **Module-level constant**: `PRIVATE_SERVER_DOC_PATH = _resolve_private_server_doc()` is evaluated once at import time, not per-test — consistent with `DOCKER_DIR`.
+
+### 4.3 D-11 ~ D-19 Migration ✅
+
+Nine test functions updated from hardcoded `os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")` to the new `PRIVATE_SERVER_DOC_PATH`:
+
+| Guard | What it checks | Path source |
+|---|---|---|
+| D-11 | PRIVATE_SERVER.md env names valid | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-12 | No deprecated MAM_MQTT_* in code fences | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-13 | nats config blocks valid (mqtt {) | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-14 | CLI args valid | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-15 | store_dir valid + unquoted heredoc | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-16 | nats image alpine-pinned | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-17 | Port 8222 localhost-bound | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-18 | TLS examples use domain names | `PRIVATE_SERVER_DOC_PATH` ✅ |
+| D-19 | Subject literals match topic root | `PRIVATE_SERVER_DOC_PATH` ✅ |
+
+All 9 functions now resolve the document through the submodule-aware resolver. The assertion message in D-11 was also improved: `"PRIVATE_SERVER.md missing"` → `f"PRIVATE_SERVER.md missing at {doc_path}"` — provides the resolved path in the error, aiding debugging.
+
+### 4.4 D-23 Cross-Document Tag Matching ✅
+
+D-23 verifies that the compose image tag appears in `PRIVATE_SERVER.md`. This test was updated to use `PRIVATE_SERVER_DOC_PATH` instead of the hardcoded root path. Since the content is byte-identical (§3.5), the tag-matching logic produces the same result.
+
+### 4.5 D-22 ~ D-30 (Docker Assets Guards) ✅
+
+These guards use `DOCKER_DIR` (from `_resolve_docker_dir()`) and were **not modified** in this commit — they were already submodule-compatible from commit `629a67f`. Verified all 9 guards resolve through the correct paths:
+
+| Guard | Path variables used | Submodule-aware? |
+|---|---|---|
+| D-22 | `COMPOSE_PATH`, `NATS_CONF_PATH`, `ENV_EXAMPLE_PATH`, `DOCKER_README_PATH` | ✅ (via `DOCKER_DIR`) |
+| D-23 | `COMPOSE_PATH` + `PRIVATE_SERVER_DOC_PATH` | ✅ |
+| D-24 | `COMPOSE_PATH` | ✅ |
+| D-25 | `NATS_CONF_PATH`, `ENV_EXAMPLE_PATH` | ✅ |
+| D-26 | `NATS_CONF_PATH`, `COMPOSE_PATH` | ✅ |
+| D-27 | `NATS_CONF_PATH` + `mqtt_common.DEFAULT_TOPIC_ROOT` | ✅ |
+| D-28 | `COMPOSE_PATH` | ✅ |
+| D-29 | `DOCKER_DIR`, `ENV_EXAMPLE_PATH` + submodule-aware git commands | ✅ |
+| D-30 | `NATS_CONF_PATH` | ✅ |
+
+### 4.6 D-29 Submodule-Aware Git Commands ✅ (pre-existing, critical)
+
+D-29 is the most submodule-sensitive guard. It runs `git check-ignore` and `git ls-files` to verify `.env` is ignored and untracked:
+
+```python
+is_submodule = os.path.exists(os.path.join(REPO_ROOT, ".gitmodules")) and "nats-docker" in DOCKER_DIR
+target_repo = os.path.join(REPO_ROOT, "nats-docker") if is_submodule else REPO_ROOT
+rel_env = os.path.relpath(os.path.join(DOCKER_DIR, ".env"), target_repo)
+# ... runs git check-ignore / ls-files with cwd=target_repo
+```
+
+- **Submodule detection**: Checks both `.gitmodules` existence AND that `DOCKER_DIR` contains `nats-docker` — robust dual-condition check.
+- **Correct repo target**: When submodule is detected, git commands run with `cwd=nats-docker` (the submodule's own git repo), not the parent — ensuring the submodule's `.gitignore` is the one being checked.
+- **Relative path calculation**: `os.path.relpath(...)` computes the correct relative path from the submodule root to `docker/.env`.
+
+This is correctly implemented and will catch secrets leakage in both submodule and non-submodule layouts.
+
+---
+
+## 5. Review Area 3 — Legacy File Removal & Migration
+
+### 5.1 Root-Level Deletions ✅
+
+```
+git diff-tree --name-status -r 12ba30b:
+D    NATS_REPORT.md
+D    PRIVATE_SERVER.md
+M    nats-docker
+M    tests/test_deploy_freshness.py
+```
+
+- `NATS_REPORT.md` — deleted from root (176 lines). Confirmed absent: `ls NATS_REPORT.md` → "No such file or directory".
+- `PRIVATE_SERVER.md` — deleted from root (584 lines). Confirmed absent: `ls PRIVATE_SERVER.md` → "No such file or directory".
+- `docker/` — already removed in prior commit `629a67f`; confirmed absent from root.
+
+### 5.2 Submodule Migration Verification ✅
+
+| File | Root (deleted) | Submodule (new home) | Content match |
+|---|---|---|---|
+| `PRIVATE_SERVER.md` | 584 lines | `nats-docker/PRIVATE_SERVER.md` (584 lines) | **byte-identical** (diff: 0 lines) |
+| `NATS_REPORT.md` | 176 lines | `nats-docker/NATS_REPORT.md` (176 lines) | **byte-identical** (diff: 0 lines) |
+
+The migration is a pure file move — no content was modified, truncated, or reformatted. This preserves all documentation parity guarantees established in the prior review (job `1ed5cf56`).
+
+### 5.3 No Orphaned Imports or Code References ✅
+
+Searched all `.py`, `.sh`, `.md`, `.json` files (excluding `.mam/jobs`, `.agents/reports`, `nats-docker/`, `tests/test_deploy_freshness.py`) for references to the old root paths:
+
+- **No Python/shell code** references root-level `PRIVATE_SERVER.md` or `NATS_REPORT.md` — only the test file (already updated) and documentation files contain references.
+- **No `docker/` bare path references** in code — the test file's `_resolve_docker_dir()` handles this via the fallback chain.
+
+### 5.4 Submodule as Single Source of Truth ✅
+
+The `nats-docker` submodule now contains the complete deployment stack:
+- `docker/` — canonical deployment assets (compose, nats.conf, .env.example, README)
+- `PRIVATE_SERVER.md` — deployment guide with §9 verification playbook
+- `NATS_REPORT.md` — MQTT vs NATS feasibility analysis
+- `README.md` — submodule-level overview
+
+This consolidates all deployment-related artifacts in one versioned repository, enabling independent updates to the deployment stack without coupling to the MAM framework release cycle.
+
+---
+
+## 6. Findings
+
+### M-1: Orphaned Markdown Links in `implementation_plan.md` — Medium
+
+**Location**: `implementation_plan.md` lines 7, 147
+
+```
+Line 7:  [`NATS_REPORT.md`](NATS_REPORT.md), [`PRIVATE_SERVER.md`](PRIVATE_SERVER.md)
+Line 147: | [`PRIVATE_SERVER.md`](PRIVATE_SERVER.md) | 스파이크 결과 반영 및 최종 가이드 확정 |
+```
+
+**Issue**: These markdown links use relative paths to the repository root. Since both files moved to the `nats-docker/` submodule, the links now resolve to non-existent paths and will 404 in GitHub/rendered markdown.
+
+**Recommendation**: Update to `[NATS_REPORT.md](nats-docker/NATS_REPORT.md)` and `[PRIVATE_SERVER.md](nats-docker/PRIVATE_SERVER.md)`.
+
+### L-1: Stale Text References in `implementation_plan.md` — Low
+
+**Location**: Lines 23, 39, 112, 156, 172, 179 — text references to `PRIVATE_SERVER.md` and `docker/` without `nats-docker/` prefix. Not broken links, but don't indicate the new location.
+
+### L-2: Stale Text References in `IMPROVEMENTS.md` — Low
+
+**Location**: Lines 3, 4, 21, 77, 83, 84, 91, 100, 271 — text citations to `NATS_REPORT.md` sections. Content is accurate (section numbers unchanged) but file location moved.
+
+### Positive Highlights
+
+- **Byte-identical migration**: Both files moved with zero content modification.
+- **Symmetrical resolver design**: `_resolve_private_server_doc()` mirrors the proven `_resolve_docker_dir()` pattern.
+- **Backward-compatible fallback**: Both resolvers include legacy root path as fallback.
+- **D-29 submodule-awareness**: Correctly detects submodule layout and runs git commands against the correct repo.
+- **D-11 error improvement**: Assertion now includes resolved path for better debugging.
+- **Clean atomic commit**: Deletion, pointer bump, and test update in one commit — no intermediate broken states.
+- **No secrets in submodule**: `.gitignore` enforces same `.env` exclusion pattern.
+
+### No Escalation Required
+
+All findings are documentation-level (M/L severity). No blocking defects, security vulnerabilities, or correctness errors.
+
+---
+
+## 7. Full Test Suite
+
+Command: `.venv/bin/python -m pytest tests/ -q`
+
+```
+........................................................................ [ 23%]
+........................................................................ [ 47%]
+........................................................................ [ 70%]
+........................................................................ [ 94%]
+..................                                                       [100%]
+306 passed in 352.84s (0:05:52)
+```
+
+| Metric | Value |
+|---|---|
+| Total tests collected | 306 |
+| Passed | 306 |
+| Failed | 0 |
+| Errors | 0 |
+| Skipped | 0 |
+| Duration | 352.84s (5:52) |
+
+**Result**: 100% pass rate, 0 regressions. Identical to the baseline established in job `1ed5cf56` (306 passed, 353.84s). The submodule migration introduced no test breakage — all D-11~D-30 guards correctly resolve the new submodule paths and pass.
+
+---
+
+[VERDICT: PASS]
@@ -0,0 +1,212 @@
+# Cross-Code Review Report — Job 93a74271
+
+**Job ID**: 93a74271
+**Reviewer**: cline
+**Date**: 2026-08-23
+**Scope**: Track 1R — Docker deployment assets for `nats-server` on a remote server
+**Changeset**: 5 new files (`docker/` directory + `requirements.txt`) + 3 modified files (`PRIVATE_SERVER.md`, `implementation_plan.md`, `tests/test_deploy_freshness.py`)
+
+---
+
+## 1. Executive Summary
+
+This review covers the creation of production-ready Docker deployment assets in the `docker/` directory (`docker-compose.yaml`, `nats.conf`, `.env.example`, `README.md`) and the addition of 9 regression guards (D-22 ~ D-30) in `tests/test_deploy_freshness.py`, along with documentation updates to `PRIVATE_SERVER.md` and `implementation_plan.md`.
+
+**Verdict**: PASS. All 5 task objectives are met. The Docker assets are correct, internally consistent, and match the canonical documentation. All 306 tests collect; the 29 deploy-freshness guards (including 9 new) pass, and the fast subset (sanity + tier1_unit, 47 tests) shows no regressions. Findings are limited to documentation consistency issues that do not affect the functionality or security of the deployment assets.
+
+---
+
+## 2. Task Objective Verification
+
+### 2.1 docker/docker-compose.yaml — PASS
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| `nats:2.12-alpine` service | PASS | Line 9: `image: nats:2.12-alpine` |
+| MQTT 1883 | PASS | Line 22: `"${MQTT_BIND:-127.0.0.1}:1883:1883"` |
+| NATS 4222 | PASS | Line 23: `"${NATS_BIND:-127.0.0.1}:4222:4222"` |
+| WS 8080 | PASS | Line 25: `"${WS_BIND:-127.0.0.1}:8080:8080"` |
+| HTTP monitor 8222 (loopback only) | PASS | Line 24: `"127.0.0.1:8222:8222"` (hardcoded) |
+| JetStream volume `/data` | PASS | Line 28: `nats-data:/data` |
+| Healthcheck | PASS | Lines 29-34: `wget` to `/healthz` on `127.0.0.1:8222` |
+| Fail-closed secrets | PASS | Lines 15-18: `${VAR:?error}` syntax for all 4 secrets |
+| Log rotation | PASS | Lines 35-37: json-file, 10m max-size, 3 max-file |
+
+**Note**: The previous review (job `e1c4e9c3`) flagged M-1 (Medium): compose omitted NATS 4222 port. This is now **fixed** — `${NATS_BIND:-127.0.0.1}:4222:4222` is present in both `docker/docker-compose.yaml` and the `PRIVATE_SERVER.md` code fence.
+
+### 2.2 docker/nats.conf — PASS
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| MQTT block | PASS | Lines 23-27: `port: 1883`, `ack_wait: 60s`, `max_ack_pending: 1024` |
+| JetStream block | PASS | Lines 15-19: `store_dir: "/data"`, `max_file: 10G`, `max_mem: 256M` |
+| Multi-tenant accounts (MAM with mam/observer) | PASS | Lines 55-70: `MAM` account with `mam_agent` + `mam_observer` (sub-only, pub denied) |
+| HOME account | PASS | Line 72: `HOME: { jetstream: enabled, users: [...] }` |
+| SYS account | PASS | Line 73: `SYS: { users: [...] }` |
+| `system_account: SYS` | PASS | Line 75 |
+| WebSocket block | PASS | Lines 29-52: `port: 8080`, `no_tls: true`, origin policy, `/mqtt` path docs |
+| No hardcoded secrets | PASS | All passwords are `$VAR` references; D-25 guard verifies |
+
+### 2.3 docker/.env.example — PASS
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| Fail-closed security | PASS | All 4 secrets have empty values (lines 22, 25, 28, 31) |
+| Variable definitions | PASS | Each secret has a comment explaining purpose and generation method |
+| Bind address variables | PASS | Lines 37-47: `MQTT_BIND`, `NATS_BIND`, `WS_BIND` (commented, default 127.0.0.1) |
+| 8222 not variable-ized | PASS | Line 47: explicit note that HTTP monitor is loopback-fixed |
+| Git tracking | PASS | `.gitignore` line 23 `!.env.example` exempts it; D-29 guard verifies |
+
+### 2.4 docker/README.md — PASS (with findings — see section 3)
+
+| Requirement | Status | Evidence |
+|---|---|---|
+| Step-by-step deployment | PASS | Section 3: 5-step quick deploy guide |
+| Verification instructions | PASS | Section 5: R-3 port scan; Section 7: R-1~R-10 playbook |
+| Network/firewall guidance | PASS | Section 4: UFW rules with Docker bypass warning |
+| Client connection guide | PASS | Section 6: MAM `.mam.env` config + MQTT.js dashboard recipe |
+| Operations/maintenance | PASS | Section 8: logs, backup, upgrade, monitoring |
+| Troubleshooting | PASS | Section 9: 10-row troubleshooting table |
+
+### 2.5 tests/test_deploy_freshness.py — PASS
+
+9 new guards added (D-22 ~ D-30), all passing:
+
+| Guard | What it checks | Result |
+|---|---|---|
+| D-22 | docker/ assets exist and are populated | PASS |
+| D-23 | compose image matches doc and is alpine | PASS |
+| D-24 | compose port exposure contract (4 ports, 8222 loopback) | PASS |
+| D-25 | secrets are fail-closed (`${VAR:?}` syntax, empty .env.example, $VAR in nats.conf) | PASS |
+| D-26 | nats.conf jetstream/mqtt contract (store_dir /data, max_file/max_mem, mqtt 1883, MAM jetstream) | PASS |
+| D-27 | observer permissions match `mqtt_common.DEFAULT_TOPIC_ROOT` (`python.mqtt.jobs`) | PASS |
+| D-28 | healthcheck contract (wget, /healthz, 127.0.0.1:8222) and alpine coupling | PASS |
+| D-29 | env secrets never tracked (`.env` ignored, `.env.example` not ignored) | PASS |
+| D-30 | websocket origin policy startable (`no_tls: true`, no `*`, `/mqtt` documented) | PASS |
+
+**D-16 guard change**: Assertion tightened from `"-alpine" in tag or tag.startswith("2.")` to `"alpine" in tag`. Correct — healthcheck requires `wget` only in alpine. All `nats:` references in `PRIVATE_SERVER.md` use `nats:2.12-alpine`; no breakage.
+
+**Test count**: 306 collected (was 297), matching `implementation_plan.md` claim "297 to 306".
+
+---
+
+## 3. Findings
+
+### M-1 (Medium) — R-1~R-10 ID collision between PRIVATE_SERVER.md section 9.4 and docker/README.md section 7; R-11~R-13 undefined
+
+**Category**: Documentation consistency / Loss
+
+The R-1~R-10 verification playbook IDs have **different meanings** in `PRIVATE_SERVER.md` section 9.4 and `docker/README.md` section 7. Key collisions:
+
+| R-ID | PRIVATE_SERVER.md section 9.4 | docker/README.md section 7 |
+|---|---|---|
+| R-2 | Listener + TLS identity | External monitoring blocked |
+| R-4 | Round-trip pub/sub + JetStream | WAN latency |
+| R-5 | **Retained terminal event (MQTT)** | **Auth rejection (unauthorized)** |
+| R-6 | Broker identity assertion | Auth success (normal) |
+| R-7 | Freeze regression (H-1/H-4) | Retained event delivery |
+| R-8 | Full regression suite | Broker identity verification |
+
+Only R-1 (health), R-3 (port exposure), R-9 (tenant isolation), and R-10 (retained boundary) share the same concept.
+
+Additionally, `implementation_plan.md` (lines 122, 182) references "R-1 ~ R-13" with "R-5(retained) / R-9(account boundary) / R-13(MQTT-over-WS)" as final gates. However:
+- R-11, R-12, R-13 are **never defined** in either `PRIVATE_SERVER.md` section 9.4 or `docker/README.md` section 7.
+- The "R-5(retained)" reference matches `PRIVATE_SERVER.md`'s R-5, but **not** `docker/README.md`'s R-5 (auth rejection).
+- `PRIVATE_SERVER.md` section 9.5 cutover procedure still says "R-1 ~ R-10" (not R-1~R-13).
+
+**Impact**: An operator following `docker/README.md` who is told to verify "R-5(retained)" would check auth rejection instead of retained event delivery. The undefined R-11~R-13 create ambiguity about what constitutes the final acceptance gate.
+
+**Fix**: Either (a) align the README's R-IDs with `PRIVATE_SERVER.md` section 9.4 (use different ID ranges like RR-1~RR-10 for the README's deployment-focused checks), or (b) define R-11~R-13 in both documents and update section 9.5 to reference R-1~R-13.
+
+### L-1 (Low) — docker/README.md section 7 R-4 references non-existent `latency_check.py`
+
+**Category**: Operability / Loss
+
+`docker/README.md` section 7 R-4 states: `python latency_check.py` with expected result "RTT P95 < 150ms". No such file exists in the repository. `PRIVATE_SERVER.md` section 9.4 defines the latency probe as an inline Python heredoc (not a standalone script). An operator following the README would get a "file not found" error.
+
+**Fix**: Either (a) replace `python latency_check.py` with the inline heredoc from `PRIVATE_SERVER.md` section 9.4, or (b) create `docker/latency_check.py` as a standalone script, or (c) reference the `PRIVATE_SERVER.md` section 9.4 latency probe section.
+
+### L-2 (Low) — docker/README.md section 4 UFW rules more permissive than PRIVATE_SERVER.md section 9.3
+
+**Category**: Documentation consistency
+
+`docker/README.md` section 4 uses `sudo ufw allow in on tailscale0 to any` (allows all ports on the tailnet interface), while `PRIVATE_SERVER.md` section 9.3 uses granular per-port rules (`port 1883`, `port 4222`, `port 8080`). Both are valid for a trusted tailnet, but the README's approach is less defense-in-depth. The README also omits the 4222 UFW rule that `PRIVATE_SERVER.md` section 9.3 includes.
+
+**Fix**: Align the README's UFW rules with `PRIVATE_SERVER.md` section 9.3's per-port approach, or add a note explaining the intentional difference.
+
+### V-1 (Very Low) — implementation_plan.md P0.5 step indentation
+
+**Category**: Cosmetic
+
+The new P0.5 step in the roadmap diagram uses slightly different indentation alignment than the surrounding steps. Purely cosmetic; does not affect readability of the plan.
+
+---
+
+## 4. Cross-Reference Verification
+
+### 4.1 docker/ files vs PRIVATE_SERVER.md code fences
+
+| File | Method | Result |
+|---|---|---|
+| `docker/nats.conf` vs `PRIVATE_SERVER.md` section 9.1 code fence | Programmatic byte-level comparison | **EXACT MATCH** |
+| `docker/docker-compose.yaml` vs `PRIVATE_SERVER.md` section 9.2 code fence | Programmatic byte-level comparison | **EXACT MATCH** |
+
+The D-22~D-30 guards provide structural verification but not a full byte-level diff. The manual programmatic comparison confirms zero drift between the canonical files and the documentation code fences.
+
+### 4.2 Topic root consistency
+
+`mqtt_common.DEFAULT_TOPIC_ROOT` = `"python/mqtt/jobs"` -> dotted form = `"python.mqtt.jobs"`.
+`docker/nats.conf` observer `subscribe: { allow: ["python.mqtt.jobs.>"] }` — matches. D-27 guard verifies this programmatically.
+
+### 4.3 .gitignore verification
+
+- `docker/.env` -> ignored by `.gitignore` line 21 (`.env` pattern). D-29 guard passes.
+- `docker/.env.example` -> not ignored (`.gitignore` line 23 `!.env.example` overrides line 22 `.env.*`). D-29 guard passes.
+- `.env.example` lines 4-5 reference `.gitignore:23` and `.gitignore:21` — line numbers verified correct.
+
+### 4.4 Previous review findings (job e1c4e9c3) — resolution status
+
+| Previous Finding | Status | Evidence |
+|---|---|---|
+| M-1: section 9.2 compose omits NATS 4222 port | **FIXED** | Both `docker/docker-compose.yaml` and `PRIVATE_SERVER.md` section 9.2 include `${NATS_BIND:-127.0.0.1}:4222:4222` |
+| V-2: Unchecked M2b guard checkbox | **FIXED** | `implementation_plan.md` line 180: `- [x]` for guards G-D5~G-D9, G-R1, G-R2 (290 to 297) |
+| L-1/L-2 (lib.sh latency, handle_startup_dialogs timeout) | Out of scope | Not part of this changeset |
+| L-3 (D-19 regex scans full markdown) | Still present | D-19 unchanged; not part of this changeset |
+
+---
+
+## 5. Test Results
+
+| Suite | Tests | Result |
+|---|---|---|
+| `tests/test_deploy_freshness.py` (full) | 29 | **29 passed** (12.16s) |
+| `tests/test_sanity.py` + `tests/test_tier1_unit.py` | 47 | **47 passed** (16.99s) |
+| Full collection | 306 | 306 collected (0.04s) — matches `implementation_plan.md` "297 to 306" |
+| Full suite (`tests/`) | 306 | Not completed (integration/e2e tests with MQTT exceed 30s timeout; not affected by this changeset) |
+
+**No regressions detected** in the fast subset. The D-16 guard tightening is validated by all 29 deploy-freshness tests passing.
+
+---
+
+## 6. Security Review
+
+| Check | Status |
+|---|---|
+| No hardcoded secrets in any file | PASS — All passwords are `$VAR` references; D-25 guard verifies |
+| Fail-closed on missing secrets | PASS — `${VAR:?error}` compose syntax; empty `.env.example` values |
+| 8222 (HTTP monitor) loopback-only | PASS — Hardcoded `127.0.0.1:8222:8222`, not variable-ized |
+| Default bind addresses are loopback | PASS — `${MQTT_BIND:-127.0.0.1}`, `${NATS_BIND:-127.0.0.1}`, `${WS_BIND:-127.0.0.1}` |
+| `.env` never tracked in git | PASS — `.gitignore` + D-29 guard |
+| WebSocket `no_tls: true` explicit | PASS — Prevents startup failure from implicit TLS requirement |
+| No `*` in `allowed_origins` | PASS — D-30 guard verifies; comment explains NATS rejects `*` |
+| Observer publish denied | PASS — `publish: { deny: [">"] }` in nats.conf; D-27 guard verifies |
+
+---
+
+## 7. Conclusion
+
+The implementation fully satisfies all 5 task objectives. The Docker deployment assets are production-ready, internally consistent, and match the canonical documentation byte-for-byte. The 9 new regression guards (D-22~D-30) provide comprehensive structural verification of the deployment contract. The previous review's M-1 finding (missing 4222 port) is resolved.
+
+The findings (1 Medium, 2 Low, 1 Very Low) are all documentation consistency issues that do not affect the functionality or security of the deployment assets. They can be addressed with minor documentation edits without rework.
+
+[VERDICT: PASS]
@@ -0,0 +1,196 @@
+# Cross-Code Review Report — Job `9f9e7c2c`
+
+- **Reviewer**: cline (session `herdr:canary-projects-multi-agent-mux-creator-cline`)
+- **Date**: 2026-08-23
+- **Changeset**: uncommitted working-tree, 6 files, +235/-48
+- **Scope**: Cross-code review (lint / behavior / loss) of documentation synchronization
+  (`MESSAGING.md`, `IMPROVEMENTS.md`, `implementation_plan.md`), `.gitmodules` relative URL,
+  `deploy/gitea-ci.yml` submodule checkout, and test guards D-31/D-32 against the latest
+  NATS deployment + `nats-docker` submodule integration.
+
+---
+
+## 1. Changeset Summary
+
+| File | Δ | Nature |
+|---|---|---|
+| `.gitmodules` | 1 line | Absolute URL → relative `../../laa/nats-docker` |
+| `IMPROVEMENTS.md` | +52/-2 | Header counts, new §2/§3 sections (B-14✅/B-15✅/B-16/B-17/B-18, O-6✅), §6.6 refresh |
+| `MESSAGING.md` | +63/-45 | Mosquitto/EMQX → NATS broker (§1.2, ACLs, accounts), §4.4 10-env table, `.mam.env` resolution hierarchy (B-17) |
+| `deploy/gitea-ci.yml` | +2/-0 | `test` job checkout gains `submodules: recursive` |
+| `implementation_plan.md` | +21/-10 | Track 1R P0.6 submodule items, §7 description correction, M2b gate count (306) |
+| `tests/test_deploy_freshness.py` | +86/-0 | New guards `test_d31_*` (CI submodules) and `test_d32_*` (MESSAGING.md env coverage) |
+
+---
+
+## 2. Verification Methodology
+
+1. Gathered changeset via `git diff --stat` and per-file diffs.
+2. Verified `.gitmodules` relative URL resolution against the **actual** parent origin
+   (`git remote get-url origin` → `https://git.godopu.com/tmpl/multi-agent-mux`) and the
+   configured submodule URL in `.git/config` + submodule's own `origin`.
+3. Confirmed on-disk existence of every `nats-docker/` path referenced in the docs; confirmed
+   no orphaned root-level `PRIVATE_SERVER.md` / `NATS_REPORT.md` / `docker/`.
+4. Cross-checked all 10 `MQTT_*` env vars in `MESSAGING.md` §4.4 against
+   `mqtt_common.py` (`broker_config_from_env` + `make_client` defaults + docstring).
+5. Verified `deploy/gitea-ci.yml` test job enables `submodules: recursive`.
+6. Ran mandated tests: `.venv/bin/python -m pytest tests/test_deploy_freshness.py tests/test_sanity.py -q`.
+7. Ran D-31/D-32 in isolation.
+8. Audited `IMPROVEMENTS.md` section-header structure (`grep '^## '`) against the diff to detect
+   insertions that orphan or duplicate existing sections.
+
+---
+
+## 3. Verification Results
+
+### 3.1 `.gitmodules` relative URL — PASS
+- Parent origin: `https://git.godopu.com/tmpl/multi-agent-mux`.
+- `../../laa/nats-docker` resolves: `/tmpl/multi-agent-mux` → `../` → `/tmpl` → `../../` →
+  host root → `laa/nats-docker` = **`https://git.godopu.com/laa/nats-docker`**.
+- Confirmed equal to `git config --get submodule.nats-docker.url` and the submodule's own
+  `origin` fetch/push URL.
+- Submodule checked out at `a4b6e49` (heads/main). Relative form improves org-wide mirroring
+  portability vs the prior absolute URL. No functional regression.
+
+### 3.2 Submodule on-disk asset integrity — PASS
+All paths referenced by the docs exist under `nats-docker/`:
+- `nats-docker/docker/{docker-compose.yaml, nats.conf, .env.example, README.md}`
+- `nats-docker/PRIVATE_SERVER.md`, `nats-docker/NATS_REPORT.md`
+
+No orphaned root-level `PRIVATE_SERVER.md` / `NATS_REPORT.md` / `docker/` remain (confirmed via
+`ls`; all three return "No such file or directory"). The `12ba30b` / `629a67f` migration is
+complete on disk.
+
+### 3.3 `MESSAGING.md` — PASS
+- §1.2 cleanly switched from "Mosquitto/EMQX" to "NATS server (`nats:2.12-alpine`)"; mermaid
+  diagram, ACL accounts (`mam_agent` / `mam_observer`), and `nats-docker/docker/nats.conf`
+  references are consistent with the submodule assets.
+- §4.4 environment table now lists **all 10** supported `MQTT_*` variables.
+- `MQTT_CLIENT_ID_PREFIX` default documented as **`hermes`**, matching
+  `mqtt_common.py:230` (`os.environ.get("MQTT_CLIENT_ID_PREFIX", "hermes")`) and the
+  module docstring (`mqtt_common.py:218`). **Prior finding M-1 is RESOLVED.**
+- §4.4 `.mam.env` resolution hierarchy documents B-17 fail-closed behavior (explicit
+  `MAM_ENV_FILE` missing → log error + `RuntimeError` at connect; public-broker security
+  warning). Consistent with the B-17 action direction recorded in `IMPROVEMENTS.md`.
+
+### 3.4 `MQTT_*` env cross-check vs `mqtt_common.py` — PASS
+All 10 documented vars are parsed by code: `MQTT_BROKER`, `MQTT_PORT`, `MQTT_TLS`,
+`MQTT_USERNAME`, `MQTT_PASSWORD`, `MQTT_CA_CERTS`, `MQTT_CERTFILE`, `MQTT_KEYFILE`,
+`MQTT_CLIENT_ID_PREFIX`, `MQTT_KEEPALIVE`. No drift. D-32 enforces presence of these 10.
+
+### 3.5 `deploy/gitea-ci.yml` — PASS
+- `test` job (line 87-89): `actions/checkout@v3` with `submodules: recursive`.
+- The job runs `pytest tests/ -q` (line 112) → correctly classified as a test job by D-31.
+- `lint-shell` / `lint-python` jobs intentionally omit `submodules` (they do not touch
+  `nats-docker/` paths) — D-31's logic only requires submodules on pytest jobs, which is
+  the correct, minimal scope.
+
+### 3.6 `implementation_plan.md` — PASS
+- Track 1R row updated to cite `nats-docker/PRIVATE_SERVER.md` §9 and
+  `nats-docker/docker/docker-compose.yaml` (submodule-prefixed) instead of root-level paths.
+- M2b gate annotated with `(290 -> 297 -> 306)`.
+- P0.6 checklist block added (submodule split, dynamic path resolvers, CI checkout sync).
+- §7 `IMPROVEMENTS.md` description corrected: removed the prior false claim
+  "A-2 완료 전환, B-14/B-15/B-16/O-5 해결 상태 갱신" (A-2 is still open) and replaced with
+  "B-14/B-15 완료 상태 반영, O-6 신설, B-17/B-18 신설 등록" — factually accurate.
+
+### 3.7 Mandated tests — PASS
+- `pytest tests/test_deploy_freshness.py tests/test_sanity.py -q` → **33 passed** in 21.45s.
+- D-31 (`test_d31_gitea_ci_submodules_in_test_job`) — PASS in isolation.
+- D-32 (`test_d32_messaging_doc_covers_all_mqtt_env_vars`) — PASS in isolation.
+- No doc regressions; 100% pass rate confirmed.
+
+### 3.8 Prior-review findings disposition
+- **M-1** (MESSAGING.md `MQTT_CLIENT_ID_PREFIX` default mismatch) — **RESOLVED** (now `hermes`).
+- **M-2** (IMPROVEMENTS.md open-item count excluded B-18) — **RESOLVED** (now 5건 incl. B-18).
+- **L-1** (§6.6 stale conclusion listing B-14/B-15) — **RESOLVED** (now lists B-16/B-17/B-18).
+- **L-2** (§3 header count included completed O-6) — **PARTIALLY RESOLVED**: the new §3 (line 56)
+  correctly splits "추적 중 1건 / 완료 1건"; however the *old* §3 remains stale (see M-3).
+
+---
+
+## 4. Detailed Findings
+
+### M-3 (Medium) — Duplicate §2 and §3 section headers in `IMPROVEMENTS.md`
+
+- **Location**: `IMPROVEMENTS.md` — new §2 at line 28 and new §3 at line 56; pre-existing §2 now
+  at line 120 and §3 at line 143.
+- **Observation**: This changeset *inserted* new `## 2.` and `## 3.` sections (with updated
+  content: B-14/B-15 marked `✅ 완료`, B-17/B-18 added, O-6 added) immediately after the §1 intro,
+  but did **not remove** the pre-existing `## 2.` (Edge-case Bugs) and `## 3.` (Orchestration)
+  sections that remain further down. Confirmed via `grep -n '^## '` showing two `## 2.` and two
+  `## 3.` headers, and via `git diff` which contains only an insertion hunk (`@@ -23,6 +23,52 @@`)
+  with no deletion of the old sections.
+- **Contradiction introduced**: the duplicate sections disagree:
+  - New §2 (line 30-36): B-14 and B-15 carry `✅ 완료` markers with "조치 결과 (완료 — 커밋 `c6b6c77`)".
+  - Old §2 (line 120-141): B-14/B-15 are described as open with "조치 방향 (Track 0 Step 1/2/3)"
+    and no completion marker — implying unresolved.
+  - New §3 (line 56): header "추적 중 1건 / 완료 1건: O-5, O-6", lists O-5 + O-6 (✅).
+  - Old §3 (line 143): header "1건", lists only O-5.
+- Additionally, the `A-4` entry (a completed structural-improvement proposal) is now orphaned
+  between the new §3 and the old §2 (it originally sat under §1 Architecture).
+- **Impact**: Medium. Purely documentation-level (no runtime/test effect; no D-guard asserts
+  section-header uniqueness). However it directly undermines the stated goal of this changeset
+  ("synchronize documentation"): a reader navigating by section number hits contradictory
+  duplicate content, and stale "action direction" text for already-completed B-14/B-15 persists.
+- **Recommendation**: Delete the now-redundant old §2 (lines ~120-141) and old §3 (lines ~143-153)
+  blocks — the new §2/§3 supersede them. Re-home `A-4` (e.g., into §1 or §5 Completed) so it no
+  longer dangles between sections. This is a surgical delete, not a redesign.
+
+### M-4 (Low) — `§5` completed-tasks header count stale
+
+- **Location**: `IMPROVEMENTS.md` line 158 — `## 5. 🎉 완료된 과제 (Completed Tasks — 24건)`.
+- **Observation**: The header summary (line 6) was updated to claim **27** completed items
+  (adding B-14, B-15, O-6). But the §5 header still reads **24건** and the §5 body was not
+  extended to include B-14/B-15/O-6 (those three are instead described inline in the new §2/§3
+  with `✅` markers). This creates an internal count drift between the top summary and the §5
+  detail section.
+- **Impact**: Low. Internal consistency only; not enforced by any D-guard.
+- **Recommendation**: Either update §5 header to 27건 and migrate B-14/B-15/O-6 entries into §5,
+  or annotate §5 to note the three are tracked in §2/§3. Pick one location as the single source
+  of truth for the completed list.
+
+### Note (positive)
+- `MESSAGING.md` and `implementation_plan.md` changes are clean, accurate, and well-synchronized
+  with the NATS deployment and submodule state. No orphaned root-level files. The `MQTT_*`
+  table, broker architecture, ACL/account model, and `.mam.env` resolution hierarchy are all
+  consistent with `mqtt_common.py` and the `nats-docker/` assets.
+- D-31/D-32 are well-scoped, auto-disable gracefully when prerequisites are absent, and include
+  anti-void assertions (they assert at least one test job exists / at least one MQTT var is
+  documented).
+---
+
+## 5. Risk Assessment
+
+| Area | Status |
+|---|---|
+| Runtime behavior | No code change outside tests/docs; behavior unaffected. PASS. |
+| Test suite | 33/33 mandated tests pass; D-31/D-32 green in isolation. PASS. |
+| Submodule integrity | Relative URL resolves correctly; submodule checked out; assets on disk. PASS. |
+| Documentation sync (MESSAGING.md / implementation_plan.md) | Accurate and complete. PASS. |
+| Documentation sync (IMPROVEMENTS.md) | New content correct, but duplicate §2/§3 + stale §5 count (M-3/M-4). Minor. |
+| Loss / orphaned references | None — all `nats-docker/` doc links resolve; root-level originals removed. PASS. |
+
+All findings (M-3, M-4) are documentation-level, non-blocking, and fixable by surgical edits.
+No design-level rework is warranted; no `[ESCALATE: PLANNER]` is required.
+
+---
+
+## 6. Actionable Follow-ups (optional, separate cleanup commit)
+
+1. **M-3**: Remove the duplicate old §2 (lines ~120-141) and old §3 (lines ~143-153) blocks in
+   `IMPROVEMENTS.md`; re-home the orphaned `A-4` entry.
+2. **M-4**: Align `§5` header count (24건) with the summary (27건), or annotate §5 to delegate
+   B-14/B-15/O-6 to §2/§3.
+
+---
+
+## 7. Verdict
+
+All mandated tests pass, the `.gitmodules` relative URL resolves correctly, submodule assets
+are intact, `MESSAGING.md` and `implementation_plan.md` are accurately synchronized with the
+NATS deployment, and the prior review's M-1/M-2/L-1 findings are resolved. The two new findings
+(M-3 duplicate §2/§3 headers, M-4 stale §5 count) are documentation-level, non-blocking, and
+do not affect runtime behavior or test results. No escalation to the planner is warranted.
+
+[VERDICT: PASS]
@@ -0,0 +1,161 @@
+# Cross-Code Review Report - Job e1c4e9c3
+
+**Review Target**: Remote Docker deployment plan for `nats-server` (Track 1R)
+**Scope**: `PRIVATE_SERVER.md`, `implementation_plan.md`, `.agents/skills/lib.sh`, `.mam.env.example`, `tests/test_deploy_freshness.py`
+**Reviewer**: cline (herdr:canary-projects-multi-agent-mux-creator-cline)
+**Date**: 2026-08-22
+**Commit base**: c6b6c77 (HEAD)
+
+---
+
+## 1. Executive Summary
+
+The changeset establishes a comprehensive remote `nats-server` Docker production deployment plan (Track 1R / M2b) across 5 files (+413 / -66 lines). It delivers all four task deliverables: production Docker Compose & nats.conf, networking/security guide, client config & verification playbooks, and a phased rollout roadmap. Seven new regression guards (D-15~D-21) lock the documentation invariants.
+
+**Test results**: 297 tests collected (290 -> 297); deploy_freshness 20/20 pass; tier1+o2 67/67 pass; sanity 2/2 pass. No regressions detected in the fast subset.
+
+**Verdict**: PASS. One Medium documentation inconsistency (section 9.2 production compose omits NATS 4222 while section 9.3 UFW and R-3 reference it) and several Low/Very Low findings - none require re-planning.
+
+---
+
+## 2. Changed Files Overview
+
+| File | Delta | Purpose |
+|---|---|---|
+| `.agents/skills/lib.sh` | +8 / -5 | Claude startup dialog handling robustness in `wait_for_tui_ready` / `handle_startup_dialogs` |
+| `.mam.env.example` | +4 | Document `MQTT_KEEPALIVE` env var |
+| `PRIVATE_SERVER.md` | +239 / -36 | D-1~D-5 corrections, N-1 boundary, section 9 remote production guide, Appendix X |
+| `implementation_plan.md` | +44 / -20 | Split M2 -> M2a/M2b, add Track 1R roadmap section 5, renumber sections |
+| `tests/test_deploy_freshness.py` | +112 / -11 | D-11 cleanup (remove dead `recognized` set, add `MQTT_BIND`); add D-15~D-21 guards |
+
+---
+
+## 3. Detailed Review by File
+
+### 3.1 `.agents/skills/lib.sh`
+
+**Changes**:
+1. `wait_for_tui_ready()` (line 1519): adds `handle_startup_dialogs "$sess" 1 || true` inside the 30-iteration loop for `$agent = "claude"` only.
+2. `handle_startup_dialogs()` (line 1725): broadens trust-dialog regex to `'Do you trust the files|Yes, I trust this folder|Quick safety check'`.
+3. (lines 1733-1735): adds a new `'Press Enter to continue'` branch; adds `${_MAM_READY_TOKENS_CLAUDE:-Anthropic|Assistant|Chat|Welcome}` fallback default.
+4. (lines 1738-1739): reduces sleep from 2s->1s and `waited` increment from 2->1.
+
+**Verification**:
+- `bash -n` syntax check: PASS
+- `_MAM_READY_TOKENS_CLAUDE` is defined at line 63 -> the `:-` fallback is defensive but harmless (consistent with prior N5 observation).
+- The regex broadening correctly handles newer Claude dialog variants ("Quick safety check" appeared in recent Claude Code versions).
+
+**Findings**:
+
+**L-1 (Low) - Latency overhead in `wait_for_tui_ready`**: The new `handle_startup_dialogs "$sess" 1` call adds ~1s (one loop iteration with `sleep 1`) per `wait_for_tui_ready` iteration even when no dialog is present. Combined with the existing `sleep 1`, each of the 30 iterations now takes ~2s (max ~60s vs previous ~30s). Acceptable for TUI readiness but doubles worst-case latency. Not a blocker - the function returns early when ready tokens appear.
+
+**L-2 (Low) - `handle_startup_dialogs` default timeout halved**: Changing `sleep 2; waited+=2` -> `sleep 1; waited+=1` halves the default timeout from ~40s to ~20s. When called with the default `timeout=20`, the function now runs at most ~20s instead of ~40s. This is reasonable for Claude dialogs (which appear within seconds) but reduces the safety margin for slow environments. The `wait_for_tui_ready` call uses `timeout=1` (1s), so it is unaffected by this change.
+
+### 3.2 `.mam.env.example`
+
+Adds `MQTT_KEEPALIVE=60` with a descriptive comment. Verified `mqtt_common.py:234` reads it via `_env_int("MQTT_KEEPALIVE", 60)` and the dataclass default is `keepalive: int = 60` (line 179). Consistent. PASS
+
+### 3.3 `PRIVATE_SERVER.md`
+
+**D-1 store_dir correction**: Changed from literal `"~/.local/share/nats/data"` (which does not expand in nats.conf) to `"/data"` (Docker) and `"$HOME/..."` (native, via unquoted `<<EOF` heredoc). Verified by D-15 guard.
+
+**D-2 image pin**: `nats:latest` -> `nats:2.12-alpine`. The comment correctly notes `latest` is scratch-based (no `wget` for healthcheck). Alpine includes busybox `wget`. Verified by D-16 guard.
+
+**D-3 port binding**: All ports now bind to `127.0.0.1` or `${*_BIND:-127.0.0.1}`. Port 8222 (unauthenticated monitoring) is hardcoded to `127.0.0.1`. Verified by D-17 guard.
+
+**D-4 TLS examples**: TLS blocks use DNS domain names (`mam-broker.example.com`), not IP literals. Verified by D-18 guard.
+
+**N-1 retained boundary**: Section 5.2 now explicitly documents that NATS/WebSocket subscribers joining after job termination will not receive retained MQTT terminal events, with two remediation paths (MQTT reconnect or JetStream opt-in).
+
+**Section 9 Remote production guide**: Well-structured with:
+- 9.1: Production nats.conf with multi-tenant accounts, `mam_observer` read-only user, JetStream, `ack_wait: 60s` for WAN, `max_ack_pending: 1024`.
+- 9.2: Production compose with fail-closed env (`${VAR:?set in .env}`), healthcheck, log rotation.
+- 9.3: Tailscale vs TLS comparison table, UFW rules, secret generation.
+- 9.4: R-1~R-10 verification playbook + WAN latency probe.
+- 9.5: 5-step cutover procedure.
+- Appendix X: Account export/import for cross-trust-domain scenarios.
+
+**Findings**:
+
+**M-1 (Medium) - Section 9.2 production compose omits NATS 4222 port**: The section 9.2 `docker-compose.yml` (lines 405-408) publishes only ports 1883, 8222, 8080 - **missing `${NATS_BIND:-127.0.0.1}:4222:4222`**. This contradicts:
+- The task brief which explicitly requires "NATS 4222" in the production compose.
+- Section 9.3 UFW rule `sudo ufw allow in on tailscale0 to any port 4222 proto tcp` (line 447) - a dead rule since the container does not publish 4222 to the host.
+- R-3 verification playbook (line 473) which nmap-tests 4222.
+
+The section 4.1 *dev* compose (lines 101, 122) correctly includes 4222. The section 9.1 nats.conf enables NATS default port 4222 inside the container (nats-server listens on 4222 by default), but without the compose port mapping it is unreachable from the tailnet. For MAM-only deployments (MQTT 1883 only), 4222 is optional - but the UFW rule and R-3 test should then be updated to match, or the port should be added to section 9.2. **Fix**: Add `- "${NATS_BIND:-127.0.0.1}:4222:4222"` to section 9.2 ports, OR remove 4222 from section 9.3 UFW and R-3.
+
+**V-1 (Very Low) - Misleading `store_dir` comment (line 73)**: `store_dir: "/data"` is annotated `# Docker ... (native execution $HOME expansion)` - but `/data` is a fixed absolute path that does NOT expand to `$HOME`. Native execution uses a separate config block (line 145, `"$HOME/.local/share/nats/data"`). The parenthetical comment is slightly misleading; a reader might expect `/data` to auto-expand. Cosmetic only.
+
+### 3.4 `implementation_plan.md`
+
+Splits M2 -> M2a (local spike) + M2b (remote production), adds Track 1R roadmap (new section 5), renumbers sections 5->6, 6->7, and removes the old section 7 dependency graph (content folded into the milestone flow diagram at line 33). The M2b gate condition correctly cites R-3/R-5/R-6/R-9 as the final gates.
+
+**Findings**:
+
+**V-2 (Very Low) - Unchecked guard implementation checkbox**: The M2b checklist item `- [ ] new guards G-D5 ~ G-D9, G-R1, G-R2 implementation and verification (290 -> 297)` is marked `[ ]` (incomplete), but the guards (D-15~D-21) are implemented in `test_deploy_freshness.py` and verified passing (297 collected, 7 new pass). This is a tracking discrepancy - the work is done but the checkbox is not toggled. Recommend `- [x]`.
+
+### 3.5 `tests/test_deploy_freshness.py`
+
+**D-11 cleanup**: Removed the unused `recognized` set (which contained `MAM_MQTT_HOST` for exclusion-checking that was never exercised) and added `MQTT_BIND` to `valid_mqtt_vars`. Verified `MAM_MQTT_HOST` appears nowhere in the codebase. The test only checks `MQTT_*`-prefixed vars (regex `\b(MQTT_[A-Z0-9_]+)\b`), so `NATS_BIND`/`WS_BIND` are correctly excluded from validation. PASS
+
+**D-15~D-21 new guards**: All 7 guards pass. Verified:
+- D-15: store_dir absolute path + unquoted heredoc PASS
+- D-16: nats image alpine-pinned (no `latest`) PASS
+- D-17: port 8222 bound to 127.0.0.1 PASS
+- D-18: TLS blocks use DNS names, not IP literals PASS
+- D-19: subject literals match `DEFAULT_TOPIC_ROOT` (`python.mqtt.jobs`) PASS
+- D-20: `run_loop.sh` exports `MAM_ENV_FILE` (verified line 106) PASS
+- D-21: `.mam.env.example` documents `MQTT_KEEPALIVE`; no uncommented `MQTT_RETRY_INTERVAL`/`MQTT_MAX_RETRIES` PASS
+
+**Finding**:
+
+**L-3 (Low) - D-19 regex is brittle**: `re.findall(r'["\'](python\.mqtt\.jobs\.[>*\w.]+)["\']', content)` scans the entire markdown (not just code blocks) and matches subject literals in quoted strings. If a future prose sentence contains a quoted subject like `"python.mqtt.jobs.test"` without a wildcard, it would be validated. Currently passes but the scope is broader than "config examples". Non-blocking.
+
+---
+
+## 4. Task Deliverable Coverage
+
+| Requirement | Status | Location |
+|---|---|---|
+| Production Docker Compose (MQTT 1883, NATS 4222, WS 8080, HTTP 8222, JetStream volume, healthchecks) | Partial | section 9.2 compose has 1883/8222/8080 + healthcheck + nats-data volume; **missing 4222** (M-1) |
+| Production nats.conf (ports, JetStream, healthcheck endpoint) | PASS | section 9.1 nats.conf |
+| Remote networking & security (UFW, TLS/Certbot vs Tailscale, user auth) | PASS | section 9.3 comparison table + UFW rules + section 9.1 accounts/permissions |
+| Client configuration (.mam.env) | PASS | section 6 `.mam.env` template + `.mam.env.example` MQTT_KEEPALIVE |
+| Remote verification playbooks (ping, latency, pub/sub) | PASS | section 9.4 R-1~R-10 + WAN latency probe |
+| Phased rollout roadmap (M2 local spike + remote switchover) | PASS | implementation_plan.md M2a/M2b + section 5 Track 1R roadmap |
+
+---
+
+## 5. Test Validation Summary
+
+| Suite | Tests | Result |
+|---|---|---|
+| `tests/test_deploy_freshness.py` (full) | 20 | PASS 20 passed (13.55s) |
+| D-15~D-21 (new guards) | 7 | PASS 7 passed (0.02s) |
+| `tests/test_tier1_unit.py` + `test_o2_race_free_lock.py` | 67 | PASS 67 passed (19.08s) |
+| `tests/test_sanity.py` | 2 | PASS 2 passed (9.73s) |
+| `--collect-only` (full suite) | 297 | PASS 297 collected |
+| `bash -n .agents/skills/lib.sh` | - | PASS syntax OK |
+
+Full suite (297 tests) not executed end-to-end due to 30s tool timeout; tier2/3/4 tests require a live broker. The fast subset (89 tests across deploy, tier1, o2, sanity) passes cleanly with no regressions.
+
+---
+
+## 6. Findings Summary
+
+| ID | Severity | File | Description | Fix |
+|---|---|---|---|---|
+| **M-1** | Medium | PRIVATE_SERVER.md section 9.2 | Production compose omits NATS 4222; contradicts section 9.3 UFW rule and R-3 test | Add `4222:4222` port mapping to section 9.2, or remove 4222 from section 9.3/R-3 |
+| L-1 | Low | lib.sh:1519 | `handle_startup_dialogs` call adds ~1s/iteration to `wait_for_tui_ready` | Acceptable; consider gating on `_pane_dialog_open` first |
+| L-2 | Low | lib.sh:1738 | Default timeout halved (40s->20s) via sleep 2->1 | Acceptable for Claude; verify slow-env tolerance |
+| L-3 | Low | test_deploy_freshness.py D-19 | Regex scans full markdown, not just code blocks | Narrow to code_blocks scope if desired |
+| V-1 | Very Low | PRIVATE_SERVER.md:73 | Misleading store_dir comment ("$HOME expansion") | Clarify comment |
+| V-2 | Very Low | implementation_plan.md | Guard checkbox unchecked despite work done | Toggle to `[x]` |
+
+---
+
+## 7. Recommendation
+
+The changeset is production-ready for the M2b documentation milestone. The only Medium finding (M-1: section 9.2 missing 4222) is a documentation inconsistency resolvable by a one-line compose edit or removing the corresponding UFW/R-3 reference - no re-planning required. All 7 new guards pass; no test regressions; bash syntax valid; codebase cross-references (`mqtt_common.py` DEFAULT_TOPIC_ROOT, MQTT_KEEPALIVE; `run_loop.sh` MAM_ENV_FILE) all verified.
+
+[VERDICT: PASS]
@@ -1516,6 +1516,9 @@ wait_for_tui_ready() {
  fi
  local i
  for i in {1..30}; do
+    if [ "$agent" = "claude" ]; then
+      handle_startup_dialogs "$sess" 1 || true
+    fi
    if _pane_dialog_open "$sess"; then
      if printf '%s\n' "$(_pane_tail "$sess" 5)" | grep -q 'Press Enter to continue'; then
        _sks_herdr send-keys -t "$sess" Enter || true
@@ -1719,7 +1722,7 @@ handle_startup_dialogs() {
  local sess="$1" timeout="${2:-20}" waited=0 pane
  while [ "$waited" -lt "$timeout" ]; do
    pane=$(_pane_tail "$sess" 20)
-    if printf '%s\n' "$pane" | grep -q 'Do you trust the files'; then
+    if printf '%s\n' "$pane" | grep -Eq 'Do you trust the files|Yes, I trust this folder|Quick safety check'; then
      _sks_herdr send-keys -t "$sess" Enter
    elif printf '%s\n' "$pane" | grep -q 'Yes, proceed'; then
      _sks_herdr send-keys -t "$sess" Down
@@ -1727,11 +1730,13 @@ handle_startup_dialogs() {
      _sks_herdr send-keys -t "$sess" Enter
    elif printf '%s\n' "$pane" | grep -q 'Resuming the full session'; then
      _sks_herdr send-keys -t "$sess" Enter
-    elif printf '%s\n' "$pane" | grep -Eq "$_MAM_READY_TOKENS_CLAUDE"; then
+    elif printf '%s\n' "$pane" | grep -q 'Press Enter to continue'; then
+      _sks_herdr send-keys -t "$sess" Enter
+    elif printf '%s\n' "$pane" | grep -Eq "${_MAM_READY_TOKENS_CLAUDE:-Anthropic|Assistant|Chat|Welcome}"; then
      return 0
    fi
-    sleep 2
-    waited=$((waited + 2))
+    sleep 1
+    waited=$((waited + 1))
  done
  return 0
 }
@@ -0,0 +1,3 @@
+[submodule "nats-docker"]
+	path = nats-docker
+	url = ../../laa/nats-docker
@@ -80,6 +80,10 @@
 #default: hermes
 # MQTT_CLIENT_ID_PREFIX=hermes

+# MQTT keepalive interval (seconds). Used by paho-mqtt client connections.
+#default: 60
+# MQTT_KEEPALIVE=60
+
 # Log level for MAM runtime components (DEBUG, INFO, WARN, ERROR).
 #default: INFO
 # MAM_LOG_LEVEL=INFO
@@ -1,9 +1,9 @@
 # 🛠️ Multi-Agent Mux 종합 개선 및 미해결 과제 백로그 (`IMPROVEMENTS.md`)

- **최종 갱신일**: 2026-08-20 (`NATS_REPORT.md` 실측 분석 및 메시징 잠복 결함 B-14/B-15/B-16/O-5 발굴 반영, 276/276 통과 유지)
+- **최종 갱신일**: 2026-08-23 (`nats-docker` 서브모듈 분리, 프로덕션 Docker 자산 정본화, 가드 D-22~D-30 도입, 306/306 통과 유지)
 - **통합 관리 대상**: 기존 `CODEBASE_REVIEW_REPORT.md` + `OPTIMIZATION.md` + `NATS_REPORT.md`
- **총 추적 미해결 과제**: **5건** (아키텍처 1건: `A-2`, 엣지케이스 및 가용성 3건: `B-14`, `B-15`, `B-16`, 오케스트레이션 1건: `O-5`)
- **완료된 과제**: **24건** (A-1, A-3, A-4, A-5, B-1, B-3, B-4, B-5, B-7, B-8, B-9, B-10, B-13, C-1, C-2, C-3b, C-6, O-1, O-2, O-3, O-4-OrcOnboard, Herdr-0.8.0-Compat-SanitizeHash, P2-1-DelegateJobSafe-TrapFix, P2-2-C3a-C4-LegacyCleanup)
+- **총 추적 미해결 과제**: **5건** (아키텍처 1건: `A-2`, 엣지케이스 및 가용성 3건: `B-16`, `B-17`, `B-18`, 오케스트레이션 1건: `O-5`)
+- **완료된 과제**: **27건** (A-1, A-3, A-4, A-5, B-1, B-3, B-4, B-5, B-7, B-8, B-9, B-10, B-13, B-14, B-15, C-1, C-2, C-3b, C-6, O-1, O-2, O-3, O-4-OrcOnboard, O-6, Herdr-0.8.0-Compat-SanitizeHash, P2-1-DelegateJobSafe-TrapFix, P2-2-C3a-C4-LegacyCleanup)

 ---

@@ -23,6 +23,52 @@
  - 대신 **`nats-server`의 내장 MQTT 3.1.1 리스너를 전용 사설 브로커로 채택(Option C)**하여 클라이언트 코드 0줄 변경으로 NKey/JWT 계정·Subject별 ACL 격리 및 JetStream 영속성을 100% 확보하기로 확정했습니다.
  - 단, 브로커 제품과 무관하게 존재하는 **가용성 선행 결함(Track 0: B-14, B-15)**을 먼저 교정한 후 Track 1(스파이크) 및 Track 2(A-2 워크스페이스 지문 토픽 + 무조건 토큰 발급)를 순차 전개합니다.

+---
+
+## 2. 🟠 엣지 케이스 및 런타임 버그 (Edge-case Bugs — 3건)
+
+### **B-14 (✅ 완료 — F-1 / P1): `publish_event.py` 브로커 장애 시 `return 2` 조기 탈출로 인한 65분 루프 정지**
+- **현상**: `publish_event.py`에서 브로커 네트워크 장애 발생 시 `return 2`로 조기 종료되어, 뒤따르는 로컬 레지스트리 상태(`update_job_status(status=completed)`) 및 감사 로그(`append_event`, `registry.append_event`) 갱신이 누락되던 결함.
+- **조치 결과 (완료 — 커밋 `c6b6c77`)**: 네트워크 발행 실패 여부와 무관하게 로컬 레지스트리 및 감사 로그를 100% 먼저 동기화한 후 `published=False`와 함께 `return 2`를 반환하도록 실행 순서를 재배치 (G-1 ~ G-4 회귀 가드로 봉인 완료).
+
+### **B-15 (✅ 완료 — C1 & F-4 / P1): `job_subscriber.py` 디스크 폴백 부재 및 위임 경로 인프라 에러 오판정**
+- **현상**: `job_subscriber.py`가 네트워크 큐만 대기하며 로컬 디스크 상태를 확인하지 않아 브로커 다운 시 블로킹되거나 인프라 에러가 작업 `error`로 오판정되던 결함.
+- **조치 결과 (완료 — 커밋 `c6b6c77`)**: `_check_disk_fallback()`을 도입하여 로컬 디스크 상의 터미널 상태를 감지하면 합성 이벤트를 출력하고 즉시 `rc=0`으로 정상 종료하도록 개선. 브로커 인프라 접속 실패는 전용 `rc=3`으로 분리 (G-5 ~ G-10 회귀 가드로 봉인 완료).
+
+### **B-16 (F-5 / P3): `make_client()` 매 실행 랜덤 `client_id` 발급으로 인한 영속 세션(Durable Session) 구성 불가**
+- **현상**: `mqtt_common.py:258`에서 `client_id`를 매번 `uuid.uuid4().hex[:8]`로 생성하여, 브로커가 클라이언트 재연결을 식별할 수 없습니다 (`NATS_REPORT.md` §3.5 F-5).
+- **파급 효과**: 네트워크 재연결 시 미수신 이벤트 유실 가능성이 발생합니다.
+- **조치 방향**: B-15의 로컬 디스크 폴백을 표준 복원 경로로 확립하여 네트워크 세션 의존도를 제거하고, 필요 시 결정론적 식별자 규칙을 적용합니다.
+
+### **B-17 (P1): `_load_dotenv` 오타/부재 경로 지정 시 Fail-Closed 및 공용 브로커 폴백 방지**
+- **현상**: `MAM_ENV_FILE`이 명시적으로 지정되었으나 해당 경로가 존재하지 않는 경우, `_load_dotenv`가 조용히 리턴하여 `broker.hivemq.com` 공개 브로커로 폴백되는 위험.
+- **파급 효과**: 설정 오타 발생 시 잡 이벤트와 프롬프트가 공개 브로커로 전송될 수 있음.
+- **조치 방향 (2단 구조)**:
+  1. import 시점: 명시적 `MAM_ENV_FILE` 경로 부재 시 `logger.error` 기록 및 `_env_file_missing = True` 플래그 설정 (상위 임의 탐색 금지, import 예외 방지).
+  2. 접속 시점: `make_client()` 시 `_env_file_missing`이면 `RuntimeError`로 fail-closed 거부. 최종 호스트가 `broker.hivemq.com`인 경우 눈에 띄는 보안 경고 출력.
+
+### **B-18 (P2): `.mam.env`와 `.env` 공존 및 다중 워크스페이스 경계 탐색 정합성**
+- **현상**: `.mam.env`와 `.env`의 우선순위 및 워크스페이스 경계(`.agents`, `.git`) 탐색 과정에서 다중 워크스페이스 환경에서의 일관성 유지.
+- **조치 방향**: `MAM_REAL_ROOT` -> `WORKSPACE_ROOT` -> 상위 경계 디렉터리 -> `cwd` 순서의 first-hit-wins 탐색 규칙 적용.
+
+---
+
+## 3. 🟡 오케스트레이션 최적화 과제 (Orchestration Optimizations — 추적 중 1건 / 완료 1건: O-5, O-6)
+
+### **O-5 (P2): NATS/MQTT 메시징 백플레인 고도화 및 `nats-server` 스파이크 검증 (Track 1 ~ Track 2)**
+- **현상**: `NATS_REPORT.md` 아키텍처 실측 분석에 따라 `nats-server` 내장 MQTT 3.1.1 어댑터를 사설 전용 브로커로 채택하는 전략(Option C)이 확정되었습니다.
+- **조치 방향**:
+  1. **Track 1 (스파이크 검증)**: 격리 환경에서 `nats-server -js`의 MQTT 3.1.1 호환성 실측 검증.
+  2. **Track 2 (보안/격리)**: 워크스페이스 지문 기반 토픽(`mam/<sha256[:12]>/jobs/...`) 및 무조건 `auth_token` 발급(G-11)을 적용하여 A-2 보안 결함 완전 종결.
+  3. **Track 3 (문서/설정)**: `MESSAGING.md`, `VERSIONS.md`, `.mam.env`에 `nats-server` 서빙 가이드 및 설정 동기화.
+
+### **O-6 (✅ 완료 — P1): 원격 프로덕션 브로커 자산 정본화 및 `nats-docker` 서브모듈 분리**
+- **내용**:
+  1. 원격 Docker NATS 배포 가이드 및 자산(`docker-compose.yaml`, `nats.conf`, `.env.example`, `README.md`) 구현.
+  2. `nats-docker` 독립 Git 저장소 및 서브모듈(`.gitmodules`, `nats-docker/`) 분리 완료 (커밋 `629a67f`, `12ba30b`, `916185c`).
+  3. 배포 신선도 및 보안 회귀 가드 D-22 ~ D-30 9종 구축 (297 -> 306 tests 100% PASS 달성).
+  4. 테스트 프레임워크 내 `_resolve_docker_dir()` 및 `_resolve_private_server_doc()` 동적 경로 해석기 도입.
+
 ### **A-4 (✅ 완료 — P3-1): 에이전트 지식 산재 — `BaseAgentAdapter` 어댑터 계층 도입 (Rev.2)**

 > 결함 조치가 아니라 **구조 개선 제안**입니다. 상세 설계·실측 근거는 `.mam/jobs/44062a63/claude-reports/report-final.md` 및 `744ac67a` 를 참조하십시오.
@@ -366,4 +412,4 @@ CHANGES_DIFF=$(

 ### 6.6 결론

-`IMPROVEMENTS.md` 는 남은 백로그 항목(아키텍처 1건: `A-2`, 엣지케이스 및 가용성 3건: `B-14`·`B-15`·`B-16`, 오케스트레이션 1건: `O-5` — 총 5건)을 위 우선순위(Track 0 → Track 1 → Track 2)에 따라 일원화된 보완 로드맵으로 관리합니다.
+`IMPROVEMENTS.md` 는 남은 백로그 항목(아키텍처 1건: `A-2`, 엣지케이스 및 가용성 3건: `B-16`·`B-17`·`B-18`, 오케스트레이션 1건: `O-5` — 총 5건)을 위 우선순위(Track 0 → Track 1 → Track 2)에 따라 일원화된 보완 로드맵으로 관리합니다.
@@ -23,13 +23,13 @@ In the initial development/testing phase, the system defaults to the public brok

 ---

-### 1.2 Production Architecture (Secure Private Broker)
-For production deployments, the system is designed to run on a private, self-hosted MQTT 5.0 broker such as **Mosquitto** or **EMQX**. 
+### 1.2 Production Architecture (Secure Private NATS Broker)
+For production deployments, the system standardizes on a private, self-hosted **NATS server** (`nats:2.12-alpine`) with its built-in **MQTT 3.1.1** protocol engine and JetStream persistence enabled, managed via `nats-docker/docker/docker-compose.yaml`.

 ```mermaid
 graph TD
-    subgraph "Secure Corporate Network"
-        Broker["Private MQTT Broker (Mosquitto/EMQX) <br> Ports: 8883 (TLS)"]
+    subgraph "Secure Tailnet / Corporate Network"
+        Broker["Private NATS Broker (nats:2.12-alpine) <br> Native: 4222 | MQTT: 1883 | WS: 8080"]
        
        subgraph "Hermes (Delegator/Orchestrator)"
            SubClient["job_subscriber.py <br> (Role: subscriber)"]
@@ -39,35 +39,55 @@ graph TD
            PubClient["publish_event.py <br> (Role: publisher)"]
        end
        
-        SubClient -- "Subscribe (QoS 1) <br> Auth: hermes <br> ACL: Read jobs/+/events" --> Broker
-        PubClient -- "Publish (QoS 1 + Retain Terminal) <br> Auth: claude-worker <br> ACL: Write jobs/+/events" --> Broker
+        SubClient -- "Subscribe (QoS 1) <br> Auth: mam_agent / mam_observer <br> ACL: Read python/mqtt/jobs/+/events" --> Broker
+        PubClient -- "Publish (QoS 1 + Retain Terminal) <br> Auth: mam_agent <br> ACL: Write python/mqtt/jobs/+/events" --> Broker
    end
 ```

 #### Production Security & Hardening Controls:
-1. **Transport Layer Security (TLS v1.3)**: Traffic is encrypted over port `8883` using a private Certification Authority (CA). The orchestrator validates the broker using `MQTT_CA_CERTS` (CA bundle path). Optionally, Mutual TLS (mTLS) is supported via client-side certificate keys (`MQTT_CERTFILE`/`MQTT_KEYFILE`) for cryptographic device identities.
-2. **Strict Client Authentication**: All clients must supply credentials (`MQTT_USERNAME` / `MQTT_PASSWORD`) to establish a connection. Anonymous logins are explicitly disabled (`allow_anonymous false`).
+1. **Transport Layer Security & Overlay Networks**: Within a trusted mesh (Tailscale / Tailnet, Model T), traffic routes over encrypted WireGuard overlays to private endpoints. For public WAN exposures (Model P), TLS v1.3 encryption is terminated via private CA certificates (`MQTT_CA_CERTS`), and mutual TLS (mTLS) is supported via client keypairs (`MQTT_CERTFILE` / `MQTT_KEYFILE`).
+2. **Strict Client Authentication & Multi-Tenancy**: All clients authenticate against isolated NATS accounts (`MAM`, `HOME`, `SYS`) using dedicated credentials (`MQTT_USERNAME` / `MQTT_PASSWORD`). Anonymous access is explicitly disabled.
 3. **Role-Based Topic Access Control Lists (ACLs)**:
-   * **Orchestrator/Hermes (Subscriber)**: Authenticates as user `hermes` with read-only access to all event streams:
+   * **Worker / Agent (`mam_agent`)**: Granted full publish/subscribe access within the `MAM` account to manage job lifecycles:
     ```conf
-     user hermes
-     topic read python/mqtt/jobs/+/events
+     # nats-docker/docker/nats.conf
+     accounts {
+       MAM: {
+         jetstream: enabled
+         users: [
+           { user: mam_agent, password: $MAM_BROKER_PASS }
+         ]
+       }
+     }
     ```
-   * **Agent/Worker (Publisher)**: Authenticates as user `claude-worker` with write-only access restricted to the job event sub-topics:
+   * **Observer / Dashboard (`mam_observer`)**: Restricted to read-only access for monitoring streams while strictly preventing unauthorized command injection:
     ```conf
-     user claude-worker
-     topic write python/mqtt/jobs/+/events
+     # nats-docker/docker/nats.conf
+     { user: mam_observer, password: $MAM_OBSERVER_PASS,
+       permissions: {
+         subscribe: { allow: ["python.mqtt.jobs.>"] }
+         publish:   { deny:  [">"] }
+       }
+     }
     ```
-     This prevents workers from eavesdropping on sister agents or intercepting commands on other jobs.
 4. **Durable Message Queues & Session State**:
-   * The broker is configured with `persistence true` and a dedicated disk storage path.
-   * Subscribers connect with persistent session flags to ensure the broker buffers QoS 1 messages during temporary network drops.
-5. **Retained Terminal Events**: Terminal events (`completed`/`error`) are published with the `retain=True` flag. This allows a late-joining or recovering subscriber to instantly retrieve the final job status without waiting for active transmissions.
+   * JetStream is activated with a dedicated persistent store path (`store_dir: "/data"`), backing MQTT QoS 1 streams and persistent client sessions.
+5. **Retained Terminal Events**: Terminal events (`completed` / `error`) are published with `retain=True`. NATS stores retained payloads in JetStream, allowing late-joining subscribers to instantly recover final states without polling.

 ---

-### 1.3 Production Mosquitto Configuration Reference
-A hardened `/etc/mosquitto/mosquitto.conf` production configuration includes:
+### 1.3 NATS JetStream, Retained Messages & WebSocket Integration
+
+The production deployment in [`nats-docker/docker/nats.conf`](nats-docker/docker/nats.conf) includes key architectural primitives:
+1. **JetStream Requirement for MQTT Engine**: `nats-server` requires JetStream enabled at both the server level and the account level (`jetstream: enabled`) for MQTT sessions and QoS 1 message persistence.
+2. **Retained Message Scope Boundary (N-1)**: Retained messages published via MQTT are stored in JetStream by NATS and delivered to subsequent MQTT subscribers. Note that native NATS pub/sub subscribers do not receive historical retained messages upon connection unless queried via JetStream KV/Object APIs.
+3. **MQTT-over-WebSocket `/mqtt` Path (N-7)**: For web dashboards and browser clients, NATS exposes WebSocket listeners on port `8080` (or `443` in TLS mode). Standard MQTT-over-WebSocket clients connect to the `/mqtt` path (e.g. `ws://<host>:8080/mqtt` or `wss://<host>:8443/mqtt`), with `no_tls: true` and `same_origin: false` configured for secure cross-origin streaming behind reverse proxies.
+4. **Remote Deployment Models**: For full installation, Tailscale topology, and secret management guides, refer to [`nats-docker/PRIVATE_SERVER.md`](nats-docker/PRIVATE_SERVER.md) and [`nats-docker/NATS_REPORT.md`](nats-docker/NATS_REPORT.md).
+
+---
+
+### 1.4 Alternative: Hardened Mosquitto Reference
+If an environment requires a dedicated Mosquitto broker instead of NATS, a reference `/etc/mosquitto/mosquitto.conf` configuration is maintained:
 ```conf
 # Persistence settings
 persistence true
@@ -229,8 +249,9 @@ Two concurrency control schemes co-exist in this workspace to coordinate state m
 ---

 ### 4.2 `publish_event.py` (Retries and Handshakes)
-The publisher script enforces robust error handling when sending status updates:
+The publisher script enforces robust error handling and fail-safe local persistence:
 * **Fresh Connection Pattern**: Instead of maintaining a persistent socket connection (which is susceptible to socket timeouts or channel leaks), `publish_event.py` opens a fresh socket, completes the authentication/TLS handshake, publishes a single QoS 1 event, waits for `PUBACK`, and closes the connection.
+* **Guaranteed Disk Synchronization (B-14)**: Before attempting any network transmission over MQTT, `publish_event.py` records the event into the local registry (`append_event` and `update_job_status`). If the broker is unreachable or network publish fails, local audit logs and state machine files remain 100% accurate. The script returns exit code `2` at the very end to signal a transport failure without corrupting local state.
 * **Exponential Backoff**: Wrapped in the `with_retry()` decorator from `mqtt_common.py`. In case of socket errors (`OSError`, `TimeoutError`, `ConnectionError`), it retries up to 3 times (configurable via `--attempts`) with backoff:
  $$\text{delay} = \min(\text{base\_delay} \times \text{factor}^{\text{attempt}-1}, \text{max\_delay})$$
  Default parameters: `base_delay = 0.5s`, `factor = 2.0`, `max_delay = 8.0s`.
@@ -243,6 +264,12 @@ The publisher script enforces robust error handling when sending status updates:
 ### 4.3 `job_subscriber.py` (Timers and Queue Semantics)
 The subscriber acts as the central execution watchdog:
 * **Queue Serialization**: Uses a thread-safe `queue.Queue` internally. The Paho MQTT callback thread adds messages to the queue, and the main thread processes them sequentially. This separates network I/O from state machine validation.
+* **Local Disk Fallback Verification (B-15)**: On initial startup and upon any broker connection failure, `_check_disk_fallback()` immediately queries local job records (`.mam/jobs/<job_id>.json`) and audit logs (`status.json`). If the target job has already reached a terminal state locally, the subscriber completes immediately without waiting on a dead broker.
+* **Infrastructure Error Code Separation (F-4)**: The subscriber returns distinct exit codes:
+  * Exit `0`: Job completed successfully.
+  * Exit `1`: Job terminated with an application `error` event.
+  * Exit `2`: Activity idle or wall-clock timeout exceeded.
+  * Exit `3`: Broker infrastructure connection error (with disk fallback checked).
 * **State Machine Protection**: To safeguard against QoS 1 duplicate delivery or out-of-order broker retries, the subscriber runs a terminal state machine. It records job completion in an internal `terminal` dictionary. Once a job is marked `completed` or `error`, any subsequent events for that `job_id` are ignored:
  ```python
  if event in TERMINAL_EVENTS:
@@ -258,11 +285,32 @@ The subscriber acts as the central execution watchdog:

 ---

-### 4.4 `mqtt_common.py` (Logging & Config Resolution)
-* **Log Routing isolation**: Configured via `setup_logging()`. The root logger is bound to `sys.stderr`. This preserves the standard output stream (`stdout`) exclusively for clean JSON-lines payloads, enabling downstream bash tools to pipeline event feeds cleanly (e.g., `job_subscriber.py ... | jq`).
-* **Broker Config Resolution**: Configured in `broker_config_from_job()`. Resolves credentials hierarchically:
-  1. Defaults to environment configurations (e.g. `MQTT_BROKER`, `MQTT_PORT`, `MQTT_TLS`, `MQTT_CA_CERTS`).
-  2. Overlays credentials specified inside the job record JSON block (`broker.*`). This allows the agent to fetch its dedicated target broker credentials on a per-job basis.
+### 4.4 `mqtt_common.py` (Logging, Env Vars & Config Resolution)
+* **Log Routing Isolation**: Configured via `setup_logging()`. The root logger is bound to `sys.stderr`. This preserves the standard output stream (`stdout`) exclusively for clean JSON-lines payloads, enabling downstream bash tools to pipeline event feeds cleanly (e.g., `job_subscriber.py ... | jq`).
+* **Environment Variable Dictionary**:
+  The system parses and supports the following 10 configuration variables:
+  | Environment Variable | Default | Purpose |
+  |---|---|---|
+  | `MQTT_BROKER` | `broker.hivemq.com` | Broker hostname or IP address (e.g., `vm-ubuntu`, `127.0.0.1`) |
+  | `MQTT_PORT` | `1883` | Broker port (`1883` for plaintext/Tailscale, `8883` for TLS) |
+  | `MQTT_TLS` | `false` | Enable TLS encryption (`true` / `false` / `1` / `0`) |
+  | `MQTT_USERNAME` | `""` | Authentication username (e.g., `mam_agent`, `mam_observer`) |
+  | `MQTT_PASSWORD` | `""` | Authentication password |
+  | `MQTT_CA_CERTS` | `""` | Path to CA certificate bundle for TLS verification |
+  | `MQTT_CERTFILE` | `""` | Path to client certificate for mutual TLS (mTLS) |
+  | `MQTT_KEYFILE` | `""` | Path to client private key for mutual TLS (mTLS) |
+  | `MQTT_CLIENT_ID_PREFIX` | `hermes` | Prefix for dynamically generated random client IDs |
+  | `MQTT_KEEPALIVE` | `60` | MQTT keepalive ping interval in seconds |
+
+* **`.mam.env` Resolution Hierarchy (`_load_dotenv`)**:
+  Configuration files are resolved with strict precedence rules:
+  1. **OS Environment Precedence**: Any variable already defined in `os.environ` is preserved and never overwritten by file-based configs.
+  2. **Explicit Override (`MAM_ENV_FILE`)**: If `MAM_ENV_FILE` is set, only that specific file is parsed. If the specified file does not exist, an error is logged and ambient search is refused (preventing silent fallback to unintended parent configs). Connection attempts fail-closed (`RuntimeError`).
+  3. **Workspace Root Auto-Discovery**: If `MAM_ENV_FILE` is not set, the resolver searches candidate paths in order: `MAM_REAL_ROOT`, `WORKSPACE_ROOT`, upward directory walk searching for `.agents` or `.git` boundary markers, and `os.getcwd()`.
+  4. **Public Broker Security Alert (B-17)**: If the final resolved host falls back to the public sandbox `broker.hivemq.com`, a prominent security warning is emitted.
+* **Broker Config Resolution (`broker_config_from_job`)**:
+  1. Loads baseline settings from environment / `.mam.env`.
+  2. Overlays job-specific overrides specified inside the job record JSON block (`broker.*`).

 ---

@@ -311,8 +359,8 @@ graph LR
   The advisory locking system previously relied heavily on `fcntl.flock`. While `agent-sessions.yaml` has been migrated to SQLite WAL to solve concurrent writes, the job metadata in `.mam/jobs/` still relies on `fcntl.flock` which may behave non-atomically on NFS.
 2. **Bearer Token Leakage over Plaintext (Public Broker)**:
   The `auth_token` mechanism is a simple plaintext bearer comparison. If the transport layer is unencrypted (e.g., using `broker.hivemq.com` on port `1883`), any eavesdropper on the network can steal the token and spoof legitimate events.
-3. **Subscriber Network Drop Orphanage**:
-   `job_subscriber.py` does not implement automatic reconnection loops. If the subscriber loses connection to the broker, it exits, leaving the running herdr agent orphaned and without a validation/collection hook.
+3. **Subscriber Network Drop & Disk Fallback (Resolved via B-15 / Residual Active Reconnection Gap)**:
+   `job_subscriber.py` implements on-disk status fallback (`_check_disk_fallback`) to recover state upon broker connection loss (B-15). An active in-session auto-reconnection loop during continuous execution remains a recommended enhancement.
 4. **Lack of Ordering Guarantees in QoS 1**:
   QoS 1 guarantees delivery but not strict ordering. Under heavy backoff retries, a late-delivered progress event could land after a terminal event, causing state inconsistencies.

@@ -325,8 +373,8 @@ graph LR
   **Architecture Decision Note**: This means `agent-sessions.yaml` is **no longer a real-time view** of currently `running` sessions. We have explicitly accepted the trade-off of giving up real-time text readability of running sessions in favor of robust concurrency and solving NFS flock limits. Tooling and status checks must now query the SQLite DB to observe live `running` states.
 2. **Implement Signature-Based Payload Verification**:
   Rather than sending a plaintext token, utilize HMAC signatures. The delegator and worker share a secret key; the worker publishes a signature of the payload (e.g. `HMAC-SHA256(secret_key, payload_bytes)`). The subscriber validates the signature, preventing token interception.
-3. **Enforce Mandatory Broker-Side TLS and ACLs**:
-   De-prioritize plaintext support. Enforce connection over port `8883` with verified TLS certificates. Implement client certificates (mTLS) for agent authentication.
+3. **Enforce Mandatory NATS Broker-Side Authentication, JetStream and ACLs**:
+   Standardize on private `nats-server` with JetStream and account-level ACL isolation (`nats-docker/docker/nats.conf`). For public WAN exposures, terminate TLS v1.3 (`MQTT_TLS=true`) over port `8883`.
 4. **Build Auto-Reconnecting Subscriber Loops**:
   Upgrade `job_subscriber.py` to handle disconnect callbacks. Maintain a persistent queue in memory and allow the client to reconnect with exponential backoff, preventing socket dropout from terminating the orchestration flow.

@@ -1,176 +0,0 @@
-# 📊 MAM 메시징 백플레인 아키텍처 심층 분석 보고서: MQTT vs NATS
-
- **문서 버전**: Rev.2 Final Synthesis (`f1956d2e` / `5ac88ca0`)
- **작성/검토 주체**: MAM Multi-Agent Orchestration Team (`claude`, `agy`)
- **기준 커밋**: `ac82f9b` (`refactor`, 276/276 tests passing)
- **문서 목적**: MAM 프레임워크의 메시징 인프라(MQTT)를 NATS로 전면 전환할 것인지 여부에 대한 종합적인 기술·운영·보안 타당성 분석 및 실행 로드맵 확정.
-
---
-
-## 0. 최종 판정 (Executive Verdict)
-
-> ### 🎯 **[VERDICT: DO NOT MIGRATE CLIENT PROTOCOL — ADOPT `nats-server` AS DEDICATED BROKER]**
->
-> **클라이언트 전송 프로토콜(MQTT)은 유지하고, 전용 브로커로서 `nats-server`의 내장 MQTT 3.1.1 어댑터를 채택합니다.**
-
-### 0.1 3대 핵심 근거 요약
-
-```
-[MAM Control Plane]  ────> run_loop.sh (wait_for_job: 3s Local Disk Polling)  ──> 100% Broker-Independent
-[Observability Plane] ────> publish_event.py ──(MQTT 3.1.1)──> nats-server (JetStream + nkeys)
-```
-
-1. **제어 평면과 관측 평면의 분리**:
-   MAM의 핵심 루프(`run_loop.sh`)는 MQTT 메시지를 구독하지 않으며, 로컬 파일시스템(`.mam/jobs/<id>.json`)을 3초 주기로 폴링(`wait_for_job`)하여 작업 완료를 판정합니다. 브로커는 **비동기 관측(observability) 사이드카**이며 제어 평면을 차단하지 않습니다.
-2. **NATS의 실질적 이점은 '서버'에 존재**:
-   NATS의 핵심 강점(단일 무의존 Go 바이너리, JetStream 영속성, nkeys/JWT 계정·Subject별 ACL)은 서버 계층의 속성입니다. `nats-server`는 **MQTT 3.1.1 프로토콜을 네이티브로 수용**하므로, 클라이언트 코드를 한 줄도 바꾸지 않고 서버의 모든 운영·보안 이점을 100% 확보할 수 있습니다.
-3. **네이티브 NATS(`nats-py`) 전환의 비용 대비 무익함**:
-   `nats-py`는 asyncio 전용 라이브러리로, bash 기반의 단명(short-lived) 동기 CLI 도구들(`publish_event.py` 등)과 심각한 구조적 마찰을 일으키며, 최소 46건의 테스트 재작성 및 276건 green 베이스라인 훼손 위험을 초래합니다. 반면 NATS 고유 기능(Req/Reply, 초당 수백만 처리량, 클러스터링)은 MAM 워크로드(단일 워크스페이스, 잡당 수 개 이벤트)에서 전혀 사용되지 않습니다.
-
---
-
-## 1. 3대 전략적 선택지 비교 분석
-
-| 평가 항목 | (A) 현행 유지 (공개 HiveMQ) | (B) 네이티브 NATS 전환 (`nats-py`) | (C) `nats-server` + MQTT 프로토콜 유지 (채택안) |
-|---|---|---|---|
-| **클라이언트 코드 변경** | 0줄 | 4개 호출부 전면 비동기 재작성 | **0줄** (환경변수만 구성) |
-| **테스트 코드 재작성** | 0건 | 최소 46건 재작성 (276건 베이스라인 위험) | **0건** (기존 276건 100% 보존) |
-| **A-2 보안 결함 해소** | ❌ 불가 (공개 브로커) | ✅ 완전 해소 | ✅ **완전 해소** (nkeys/JWT subject ACL) |
-| **단일 정적 바이너리 배포** | ❌ 불가 | ✅ 지원 | ✅ **지원** (`nats-server` 바이너리 1개) |
-| **이벤트 영속성 (JetStream)** | ❌ 미지원 | ✅ 지원 | ✅ **지원** (내장 JetStream 엔진) |
-| **동기 CLI 호환성** | ✅ 우수 (paho-mqtt) | ❌ 심각 (asyncio 강제) | ✅ **우수** (기존 동기 핫패스 유지) |
-| **되돌리기(Rollback) 비용** | — | 🔴 높음 (비가역 코드 재작성) | 🟢 **0 (가역적 환경변수 스위치)** |
-| **최종 평가** | **기각 (보안 위험)** | **기각 (비용 대비 실익 전무)** | 🏆 **최종 채택** |
-
---
-
-## 2. 현행 아키텍처 실측 및 기술적 진단 (Ground Truth)
-
-### 2.1 제어 경로 상의 MQTT 의존도 실측
- `run_loop.sh` (899줄, 메인 오케스트레이터) 내 MQTT 직접 참조는 `:889`의 임시 구독자 로그 파일 삭제 1건뿐입니다.
- 작업 완료 감지는 11개 호출 지점(전체 12개 참조) 전체가 `wait_for_job()` 함수를 통해 `.mam/jobs/<id>.json` 파일의 `status` 필드를 3초 간격으로 검사합니다.
- 따라서 브로커가 다운되어도 제어 평면 자체는 독립적으로 완주할 수 있는 구조입니다.
-
-### 2.2 paho-mqtt 결합도 (Blast Radius)
- `import paho`는 `mqtt_common.py:32` 단 1곳에 캡슐화되어 있습니다.
- 그러나 `make_client()`가 raw `mqtt.Client` 인스턴스를 반환하여 다음 4개 지점에서 구동됩니다:
-  1. `mqtt_common.py:250-276` (`make_client`)
-  2. `publish_event.py:102-122` (발행 및 ACK 대기)
-  3. `job_subscriber.py:172-251` (이벤트 큐잉 및 구독)
-  4. `reconcile.sh:245-292` (내장 python 이벤트 수신)
-
---
-
-## 3. 코드베이스 잠복 결함 분석 (F-1 ~ F-5)
-
-브로커 제품 선택과 무관하게 현행 코드에 잠복해 있는 5가지 구조적 결함이 발굴되었습니다.
-
-```
-[발굴된 결함 체인]
-F-1: publish 실패 시 return 2 ──> 레지스트리 상태 동기화 누락 ──> run_loop 3900초(65분) 정지
-F-4: subscriber 미포착 예외 rc=1 ──> loop/discuss 경로에서 job_status="error" 오판정
-F-2/F-3: 전역 토픽 + auth_token 조건부 ──> 워크스페이스 격리 및 HMAC 검증 사각지대 (A-2)
-F-5: 매 실행 랜덤 client_id ──> 문서가 주장하는 durable session 구성 불가
-```
-
-### 3.1 F-1 (Critical): 발행 실패 시 레지스트리 갱신 누락 (65분 루프 정지)
- `publish_event.py:195-199`에서 브로커 네트워크 오류 발생 시 `return 2`로 조기 종료됩니다.
- 이로 인해 뒤따르는 `append_event`, `registry.append_event`, `update_job_status(status=completed)`가 실행되지 못합니다.
- `wait_for_job`은 `status=running` 상태에서 `max_wait=3900s`를 소진할 때까지 **65분간 정지**합니다.
-
-### 3.2 F-2 (High): 워크스페이스 지문 토픽 미발행 (A-2)
- `reconcile.sh:236`은 지문 토픽(`mam/<fp>/jobs/+/events`)을 구독하지만, `mqtt_common.py:119`는 전역 토픽(`python/mqtt/jobs`)으로만 발행합니다.
- 워크스페이스 간 메시지 격리가 실질적으로 비활성화되어 있습니다.
-
-### 3.3 F-3 (High): HMAC 인증 조건부 공허화 (A-2)
- `registry.py:75-79`는 TLS나 사용자 인증이 켜진 보안 브로커 감지 시 `secrets.token_urlsafe(32)`를 자동 생성하나, 기본 공개 브로커(또는 평문 TCP 브로커) 환경에서는 토큰이 발급되지 않아 `auth_token=None`으로 남습니다.
- 이로 인해 `verify_hmac`의 `if not auth_token: return True` 분기가 무조건 참이 되어 공개 브로커 환경에서 HMAC 검증이 무력화됩니다 (Track 2에서 전 브로커 대상 무조건 발급으로 심층 방어 적용 필요).
-
-### 3.4 F-4 (Critical): `loop`/`discuss` 위임 경로의 오판정 결함
- `multi-agent-mux-delegate-job:331-341`에서 `wait "$sub_pid"`의 `sub_rc`를 직접 `job_status`로 매핑(`rc=1` -> `job_status="error"`).
- 브로커 연결 실패 시 `job_subscriber.py`가 미포착 예외로 `rc=1`을 내므로, **브로커 접속 실패가 작업 에러로 둔갑**합니다.
-
-### 3.5 F-5 (Medium): 영속 세션(Durable Session) 구성 불가
- `make_client()`가 매 실행마다 `uuid.uuid4().hex[:8]`로 랜덤 `client_id`를 생성하므로, 브로커가 재연결 세션을 식별할 수 없습니다.
-
---
-
-## 4. 리뷰 및 챌린지 검증 (Challenge Resolution)
-
-### 4.1 C1 챌린지 분석 및 판정
-Reviewer (`agy`)가 제기한 `job_subscriber.py`의 제어 경로 블로킹 및 디스크 폴백 누락 지적을 실측 검증하였습니다.
-
-1. **C1-a (위임 대기 경로 실재)**: `multi-agent-mux-delegate-job:227`에 `wait "$sub_pid"`가 존재하며, `run_loop.sh`의 모든 호출부가 `--type direct`로 이 경로를 통과함을 확인 (수용).
-2. **C1-b (디스크 폴백 부재)**: `job_subscriber.py`는 오직 `watcher.events.get()`만 대기하므로 브로커 단절 시 이벤트를 수신하지 못함 (수용).
-3. **C1-c (메커니즘 선후관계)**: C1은 F-1이 해결되어 디스크에 완료 상태가 쓰여진 이후에 드러나는 연쇄 결함임 (정정 및 반영).
-4. **C1-d (지연 시간 실측)**: 브로커 도달 불가 시 구독자는 15~40초 내 `rc=1`로 조기 종료되어 실제 추가 블로킹은 0초임 (지연 영향 기각, 그러나 감사 로그 오염 및 거짓 실패 판정의 심각성으로 채택).
-5. **C1-e (해결책 채택)**: `job_subscriber.py`의 대기 루프에 로컬 디스크(`load_job` / `read_logged_status`) 폴백을 도입하여 브로커 단절 시에도 즉시 정상 종료하도록 보강.
-
---
-
-## 5. 단계별 실행 계획 (Actionable Roadmap)
-
-```
-[Track 0: 결함 교정] ──> [Track 1: nats-server 스파이크] ──> [Track 2: A-2 보안/격리 해소] ──> [Track 3: 문서화]
-(F-1, C1, F-4 해결)     (S-1 ~ S-9 매트릭스 검증)         (F-2, F-3, Token, ACL)       (MESSAGING, VERSIONS)
-```
-
-### 5.1 Track 0 — 가용성 및 결함 교정 (최우선 과제, 브로커 무관)
-
-#### Step 순서 의존성 (Strict Ordering)
-1. **Step 1 (`publish_event.py`)**: 발행 실패 시에도 레지스트리 상태 동기화 및 감사 로그 작성을 완수하고 `return 2` 반환.
-2. **Step 2 (`job_subscriber.py`)**: `queue.Empty` 시 3초 스로틀로 디스크 터미널 상태를 확인하여 `source: disk-fallback` 합성 이벤트 출력 후 `rc=0` 조기 종료.
-3. **Step 3 (`multi-agent-mux-delegate-job`)**: 인프라 예외에 전용 `rc=3`을 부여하고 `job_status="broker_unavailable"` 분기 처리.
-
-#### 회귀 가드 매트릭스 (11종 신설 — G-1 ~ G-11, 목표 287/287 PASS)
- **G-1**: 브로커 도달 불가 발행 시 `rc=2`이면서 레지스트리 `status=completed` 확인.
- **G-2**: 감사 로그에 `published: false` 및 `publish_error` 필드 기록 확인.
- **G-3**: 정상 브로커 발행 시 `rc=0` 및 `published: true` 무회귀 확인.
- **G-4**: 발행 실패 시 단조 `last_seq` 증가 및 후속 발행 seq 보존 확인.
- **G-5**: 디스크 `status=completed` 선작성 시 브로커 다운 상태에서도 `job_subscriber.py`가 3초 내 `rc=0` 종료.
- **G-6**: 디스크 폴백 종료 시 stdout에 `disk-fallback` 명시 확인.
- **G-7**: 디스크 `status=error` 시 폴백 `rc=1` 반환 확인.
- **G-8**: 다중 잡 감시 시 전체 완료 전까지 조기 종료 방지.
- **G-9**: 디스크 터미널 부재 + 브로커 실패 시 `rc=3` 반환 확인 (F-4 방어).
- **G-10**: `loop` 위임 경로에서 `rc=3` 수신 시 `job_status`가 `"error"`로 오판되지 않음을 확인.
- **G-11**: `registry.register_job()` 호출 시 `auth_token`이 항상 비어있지 않게 생성됨을 단언 (`secrets.token_urlsafe(32)` 유지).
-
-### 5.2 Track 1 — `nats-server` 스파이크 검증 매트릭스 (S-1 ~ S-9)
-
-격리 클론(`$SCRATCH/nats-spike`)에서 검증 수행:
- **S-1**: `nats-server -js` MQTT 리스너 기본 구동 및 `started/progress/completed` 발행 수용 (`rc=0`).
- **S-2**: paho-mqtt 2.x `CallbackAPIVersion.VERSION2` CONNACK 호환성 검증.
- **S-3 (핵심 관문)**: **Retained terminal event 정상 전달 검증** (늦은 구독자의 즉시 최종 상태 수신). *실패 시 mosquitto로 회귀*.
- **S-4**: QoS 1 `wait_for_publish` ACK 동작 검증.
- **S-5**: 와일드카드 토픽(`mam/<fp>/jobs/+/events`) 구독 및 라우팅 검증.
- **S-6**: TLS 암호화 및 유저 인증 접근 제어 검증.
- **S-7**: Subject/Topic 레벨 권한 분리(Publisher write-only / Subscriber read-only) 검증.
- **S-8**: 전체 287건 회귀 테스트 100% PASS 검증.
- **S-9**: Track 0 디스크 폴백이 `nats-server` 장애 상황에서도 정상 동작함을 통합 검증.
-
-### 5.3 Track 2 — A-2 보안 및 워크스페이스 격리 해소
-1. **F-3 해소**: `registry.register_job()`에서 브로커 설정(TLS/인증 유무)과 무관하게 `secrets.token_urlsafe(32)` 기반 `auth_token`을 **무조건 항상 발급**.
-2. **F-2 해소**: `DEFAULT_TOPIC_ROOT`를 `mam/<sha256[:12]>/jobs`로 전환. 발행측 전환 후 `reconcile.sh`의 레거시 구독 단계적 제거.
-3. 배포 설정에 nkeys 기반 계정 분리 적용.
-
-### 5.4 Track 3 — 문서 및 설정 동기화
- `MESSAGING.md`: 브로커 사양을 `nats-server`로 갱신, F-1/C1 해소 기록, F-5 실측에 맞춘 영속 세션 설명 정정.
- `IMPROVEMENTS.md` & `VERSIONS.md`: A-2 완료 전환, F-1/F-4/F-5 백로그 이력 반영.
- `.mam.env`: `nats-server` 포트(1883/8883) 및 인증 템플릿 갱신.
-
---
-
-## 6. 비-목표 (Explicit Non-Goals)
-
-1. ❌ **`nats-py` 라이브러리 도입 및 클라이언트 비동기 재작성**: 불필요한 복잡도 및 장애 유발.
-2. ❌ **`.mam/jobs/*.json`의 JetStream KV 대체**: 파일시스템 폴링 제어 계약을 훼손하므로 상태 계층 변경 제외.
-3. ❌ **Durable Session 강제 도입을 위한 `client_id` 고정**: 동시성 충돌 위험이 크며, Track 0 디스크 폴백이 동일 복원력을 무비용으로 제공함.
-4. ❌ **`requirements.txt` 내 `paho-mqtt>=2.0.0` 제거**: 현행 종속성 유지.
-
---
-
-## 7. 결론
-
-MAM 프레임워크의 메시징 백플레인은 **클라이언트 프로토콜(MQTT)을 100% 보존한 상태에서 `nats-server`를 전용 브로커로 채택(Option C)**하는 것이 기술적·운영적·보안적 최적해입니다. 
-
-선행 필수 과제인 **Track 0(F-1 + C1 + F-4 가용성 결함 교정)**을 우선 완수한 후, 스파이크 검증(Track 1) 및 A-2 보안 강화(Track 2)를 순차 전개합니다.
@@ -1,327 +0,0 @@
-# 🔒 MAM 개인 전용 브로커(Private Broker) 구축 및 연동 가이드 (`PRIVATE_SERVER.md`)
-
- **작성일**: 2026-08-20 (Rev.2)
- **문서 목적**: MAM(Multi-Agent Mux)의 공개 브로커 의존성 및 보안 결함(A-2)을 해소하기 위한 개인 전용 브로커(NATS / Mosquitto) 구축, 운영, 다능성 활용 및 MAM 클라이언트 연동 가이드.
- **연계 문서**: [`NATS_REPORT.md`](NATS_REPORT.md), [`implementation_plan.md`](implementation_plan.md), [`IMPROVEMENTS.md`](IMPROVEMENTS.md)
-
---
-
-## 1. 개요 및 도입 배경
-
-현재 MAM 프레임워크의 기본 메시징 브로커는 공개 서버(`broker.hivemq.com:1883`)로 설정되어 있습니다. 개인 전용 브로커(Private Broker)를 구축하여 연결하면 **클라이언트 코드 변경 없이(0줄 변경)** 보안 위험을 원천 차단하고 네트워크 안정성을 대폭 향상시킬 수 있습니다.
-
-```
-[MAM Orchestrator / Agents]
-       │
-       ▼ (MQTT 3.1.1 / TLS)
-[Private Dedicated Broker]  ───> 사설망/개인 서버 (NATS Server / Mosquitto)
-                                 • 외부 불법 트래픽 100% 차단 (A-2 보안 해소)
-                                 • JetStream 영속성 및 NKey/JWT ACL 지원
-                                 • 초저지연 (<1ms) 및 무제한 대역폭
-```
-
-MAM의 제어 평면(`run_loop.sh`의 `wait_for_job` 파일시스템 폴링)은 브로커와 100% 독립적으로 작동하므로, 브로커는 **비동기 관측(observability) 사이드카** 역할을 수행합니다.
-
---
-
-## 2. 해결 영역 매트릭스 (브로커 전환 vs 코드 패치)
-
-전용 브로커 구축으로 즉시 해결되는 영역과, 로컬 코드 패치(Track 0)가 병행되어야 하는 영역의 명확한 구분입니다.
-
-| 구분 | 당면 과제 | 개인 브로커 구축 시 | 로컬 코드 패치 필요 여부 (Track 0) |
-|---|---|:---:|:---:|
-| **보안 (A-2)** | 공개 브로커 노출 및 외부 악의적 이벤트 수신 위협 | 🟢 **100% 즉시 해소** (사설망/ACL 격리) | Track 2에서 토큰 발급 강제 |
-| **안정성** | 공개 브로커의 예고 없는 순단 및 속도 제한(Rate-limit) | 🟢 **100% 즉시 해소** (전용 리소스) | — |
-| **내결함성 (B-14)** | 브로커 일시 장애 시 65분 루프 정지(Hang) 결함 | ⚠️ 브로커 점검/순단 시 여전히 위험 | 🔴 **필수 (Track 0 Step 1 선행 패치)** |
-| **지연/오판 (B-15)** | 브로커 다운 시 120초 지연 및 정상 작업의 에러 오판정 | ⚠️ 브로커 점검/순단 시 여전히 위험 | 🔴 **필수 (Track 0 Step 2 & 3 선행 패치)** |
-
-> [!IMPORTANT]
-> **방탄 아키텍처 원칙:**
-> "Track 0(`B-14`, `B-15`) 패치를 통해 브로커가 다운되어도 루프가 100% 정상 완주하도록 로컬 디스크 내결함성을 먼저 확보하고, 개인 브로커를 연결하여 A-2 보안과 성능을 완결합니다."
-
---
-
-## 3. 전용 브로커 추천 및 비교
-
-MAM 클라이언트는 표준 `paho-mqtt`를 사용하므로, MQTT 3.1.1을 지원하는 모든 브로커와 100% 호환됩니다.
-
-| 비교 항목 | 🏆 `nats-server` (강력 권장) | `eclipse-mosquitto` (대안) |
-|---|---|---|
-| **아키텍처** | Go 단일 정적 바이너리 (Zero Dependency) | C 기반 경량 오픈소스 브로커 |
-| **주요 특징** | • 내장 MQTT 3.1.1 리스너 (`mqtt { port: 1883 }`)<br>• JetStream 엔진 내장 (이벤트 영속화 및 복구)<br>• NKey/JWT 기반 계정 및 Subject별 세분화된 ACL<br>• WebSocket 및 NATS 네이티브 프로토콜 동시 서빙 | • 가장 널리 쓰이는 표준 경량 MQTT 브로커<br>• 낮은 메모리 점유율 (~10MB) |
-| **추천 용도** | 모던 인프라, 확장성, 감사 로그 영속화, 홈랩 통합 | 정통 초경량 임베디드/단일 목적 환경 |
-| **배포 난이도** | 🟢 바이너리 1개 실행 또는 Docker 1줄 | 🟢 패키지 매니저 (`apt`, `brew`) 또는 Docker |
-
---
-
-## 4. 개인 서버 브로커 배포 가이드
-
-### 4.1 `nats-server` 배포 (권장)
-
-`nats-server`에서 MQTT를 활성화하려면 설정 파일(`nats.conf`)에 `mqtt { port: 1883 }` 블록과 `jetstream { }` 블록이 반드시 포함되어야 합니다.
-
-> [!NOTE]
-> `nats-server`의 `-m` 플래그는 HTTP 모니터링 포트(`--http_port`)를 지정하는 옵션이며, MQTT를 켜는 플래그가 아닙니다. MQTT 활성화는 반드시 `-c nats.conf` 설정 파일을 통해 구성해야 합니다.
-
-#### 1) 공통 설정 파일 (`nats.conf`)
-```conf
-# nats.conf
-server_name: mam-hub
-
-# JetStream 영속 스토리지 (MQTT QoS 1 및 Retained 메시지 처리에 필수)
-jetstream {
-  store_dir: "~/.local/share/nats/data"   # Docker 환경에서는 "/data"로 매핑
-  max_file:  10G                          # 홈랩 디스크 상한 설정
-}
-
-# HTTP 모니터링 엔드포인트 (/varz, /jsz 대시보드)
-http_port: 8222
-
-# 평면 A: MAM MQTT 3.1.1 프로토콜 리스너
-mqtt {
-  port: 1883
-}
-
-# 평면 B: 홈랩/웹 브라우저 대시보드용 WebSocket 리스너 (선택 사항)
-websocket {
-  port: 8080
-  no_tls: true                            # 내부 사설망 한정
-}
-```
-
-#### 2) 배포 방법 A. Docker / Docker Compose (권장)
-
-**단일 Docker 실행:**
-```bash
-# 호스트에 nats.conf 생성 후 실행
-docker run -d \
-  --name mam-nats \
-  --restart unless-stopped \
-  -p 1883:1883 \
-  -p 4222:4222 \
-  -p 8222:8222 \
-  -p 8080:8080 \
-  -v ./nats.conf:/etc/nats/nats.conf:ro \
-  -v nats-data:/data \
-  nats:latest \
-  -c /etc/nats/nats.conf
-```
-
-**Docker Compose (`docker-compose.yml`):**
-```yaml
-version: '3.8'
-
-services:
-  nats:
-    image: nats:latest
-    container_name: mam-nats
-    restart: unless-stopped
-    command: ["-c", "/etc/nats/nats.conf"]
-    ports:
-      - "1883:1883"   # MQTT 3.1.1 포트 (평면 A: MAM)
-      - "4222:4222"   # NATS 기본 포트 (평면 B)
-      - "8222:8222"   # HTTP 모니터링 (/varz, /jsz)
-      - "8080:8080"   # WebSocket (평면 B)
-    volumes:
-      - ./nats.conf:/etc/nats/nats.conf:ro
-      - nats-data:/data
-
-volumes:
-  nats-data:
-```
-
-#### 3) 배포 방법 B. 네이티브 바이너리 설치 (macOS / Linux — 비루트 사용자 공간)
-
-macOS의 sealed APFS 루트 볼륨(`/data`) 권한 문제를 방지하기 위해 사용자 홈 디렉터리(`~/.config/nats/`, `~/.local/share/nats/data`)를 기본 스토리지로 사용합니다.
-
-```bash
-# 설정 및 데이터 디렉터리 생성 (sudo 불필요)
-mkdir -p ~/.config/nats ~/.local/share/nats/data
-
-# 설정 파일 작성
-cat <<'EOF' > ~/.config/nats/nats.conf
-server_name: mam-hub
-jetstream {
-  store_dir: "~/.local/share/nats/data"
-  max_file:  10G
-}
-http_port: 8222
-mqtt {
-  port: 1883
-}
-websocket {
-  port: 8080
-  no_tls: true
-}
-EOF
-
-# macOS (Homebrew 설치 및 실행)
-brew install nats-server
-nats-server -c ~/.config/nats/nats.conf &
-
-# Linux (x86_64 단일 바이너리 설치 및 실행)
-curl -L https://github.com/nats-io/nats-server/releases/download/v2.10.20/nats-server-v2.10.20-linux-amd64.tar.gz | tar xz
-sudo mv nats-server-v2.10.20-linux-amd64/nats-server /usr/local/bin/
-nats-server -c ~/.config/nats/nats.conf &
-```
-
---
-
-### 4.2 `mosquitto` 배포 (대안)
-
-#### Docker 실행:
-```bash
-docker run -d \
-  --name mam-mosquitto \
-  --restart unless-stopped \
-  -p 1883:1883 \
-  -v ./mosquitto.conf:/mosquitto/config/mosquitto.conf \
-  eclipse-mosquitto:latest
-```
-
-**기본 `mosquitto.conf` 설정 파일 예시:**
-```conf
-listener 1883
-allow_anonymous true
-persistence true
-persistence_location /mosquitto/data/
-```
-
---
-
-## 5. 하나의 서버로 여러 프로젝트 — `nats-server` 다능성 (Versatility)
-
-`nats-server`의 다능성은 **MAM을 네이티브 NATS로 이관할 이유가 아니라, MAM 코드를 한 줄도 바꾸지 않고도 얻을 수 있는 부가적 이득**입니다.
-
-### 5.1 두 개의 소비 평면 (Two Consumption Planes)
-
-`nats-server`는 단일 프로세스 내에서 여러 프로토콜 리스너를 동시에 구동하므로, MAM의 단순성과 개인 홈랩의 확장성을 완벽히 양립시킵니다.
-
-```
-                  ┌───────────────────────────────────────────────────────────┐
-                  │                 nats-server (단일 인스턴스)                 │
-                  ├─────────────────────────────┬─────────────────────────────┤
-                  │     평면 A: MAM 워크로드     │    평면 B: 홈랩/개인 프로젝트 │
-                  ├─────────────────────────────┼─────────────────────────────┤
-  프로토콜         │ MQTT 3.1.1 (포트 1883)       │ NATS(4222), WebSocket(8080) │
-  클라이언트       │ paho-mqtt (코드 변경 0줄)    │ nats-py, nats.js, CLI 등 자유 │
-  사용 기능       │ QoS 1, Retain, 와일드카드, TLS│ JetStream 리플레이, KV, Object│
-  설계 원칙       │ 초경량 동기 CLI 핫패스 보존   │ 고급 비동기 이벤트 스트리밍   │
-  공유 자원       │ └───── 단일 정적 바이너리 / JetStream 스토리지 / ACL ─────┘│
-                  └───────────────────────────────────────────────────────────┘
-```
-
-### 5.2 교차 프로토콜 브리징 (Cross-Protocol Bridging)
- `nats-server`는 내부적으로 MQTT 토픽(`/`)을 NATS Subject(`.`)로 실시간 자동 변환합니다.
- MAM 에이전트가 MQTT 토픽 `python/mqtt/jobs/<job_id>/events`로 이벤트를 발행하면, 웹 브라우저나 타 프로젝트의 NATS 구독자는 NATS Subject `python.mqtt.jobs.<job_id>.events` 또는 `python.mqtt.jobs.*.events`로 즉시 실시간 수신할 수 있습니다.
- **실용적 이점**: MAM 소스 코드를 단 1줄도 수정하지 않고도 React/Vue 웹 대시보드나 터미널 모니터링 툴을 즉시 부착할 수 있습니다.
- **주의 사항**: 토픽 레벨 내에 마침표(`.`)가 포함되면 NATS 계층에서 토큰이 분리될 수 있으나, MAM의 `job_id`는 8자리 hex, 워크스페이스 지문은 12자리 hex이므로 안전합니다.
-
-### 5.3 JetStream 이벤트 리플레이 (Event Replay)
- `python.mqtt.jobs.>` Subject를 구독하는 JetStream 스트림을 생성하면, 지난 작업의 이벤트 스트림 전체를 시점 지정(Time-based) 또는 시퀀스 지정(Sequence-based)으로 사후 리플레이할 수 있습니다.
- **주의 사항**: 이 기능은 옵트인(Opt-in)이며, MQTT QoS 1 처리를 위한 내부 시스템 스트림(`$MQTT_*`)과 별개로 관리됩니다. 디스크 용량 관리를 위해 `max_age`나 `max_bytes` 상한을 반드시 설정해야 합니다.
-
-### 5.4 내장 Key-Value (KV) 및 Object Store
- 홈랩 및 개인 프로젝트에서 Redis나 MinIO 같은 별도 인프라를 띄우지 않고도 `nats-server` 내장 KV 및 Object Store를 즉시 사용할 수 있습니다.
- **금지 사항 (Non-Goal)**: MAM의 로컬 레지스트리(`.mam/jobs/*.json`)를 JetStream KV로 대체해서는 안 됩니다 (`wait_for_job`의 fcntl 및 파일시스템 폴링 계약 유지).
-
-### 5.5 멀티테넌트 계정 분리 및 보안
- 단일 서버 내에서 `MAM` 전용 계정과 `HOME` 개인 계정을 분리하여 리소스 쿼터와 권한을 완벽히 격리할 수 있습니다.
- **권고 배치**: MAM과 이를 관측하는 대시보드는 동일한 계정(`MAM`)에 배치하고, 무관한 홈랩 서비스는 별도 계정(`HOME`)에 배치합니다.
-
---
-
-## 6. MAM 클라이언트 연동 설정 (`.mam.env`)
-
-개인 서버 브로커가 구동되면, MAM 저장소 루트의 [`.mam.env`](file:///.mam.env) 파일에 개인 서버 주소를 등록합니다.
-
-> [!NOTE]
-> MAM 코드(`mqtt_common.py`)는 `MQTT_*` 접두사의 환경변수를 읽습니다. 이전 비공식 문서의 `MAM_MQTT_*` 변수는 무효하므로 반드시 아래의 표준 변수명을 사용해야 합니다.
-
-```bash
-# ==============================================================================
-# MAM Private MQTT Broker Configuration (.mam.env)
-# ==============================================================================
-
-# 개인 서버 IP 또는 도메인
-MQTT_BROKER="192.168.1.100"      # 예: 10.0.0.5, mqtt.my-domain.com 등
-
-# MQTT 기본 포트 (평문 TCP: 1883, TLS 암호화: 8883)
-MQTT_PORT=1883
-
-# TLS 암호화 활성화 여부 (0: 평문 TCP, 1: TLS 암호화)
-MQTT_TLS=0
-
-# 인증 설정 (익명 브로커는 주석 처리 또는 빈 문자열 유지)
-# MQTT_USERNAME=my_agent_user
-# MQTT_PASSWORD=my_secure_password
-
-# TLS 인증서 경로 (MQTT_TLS=1 설정 시 사용)
-# MQTT_CA_CERTS=/path/to/ca.crt
-# MQTT_CERTFILE=/path/to/client.crt
-# MQTT_KEYFILE=/path/to/client.key
-```
-
-*참고: OS 환경변수에 동일한 이름이 이미 `export`되어 있는 경우 OS 환경변수가 `.mam.env` 파일 설정보다 우선합니다.*
-
---
-
-## 7. 연동 및 동작 검증 테스트 (4-Step Verification)
-
-개인 서버 브로커와의 연동 상태를 정확하게 검증하는 4단계 절차입니다.
-
-### Step 1. 브로커 리스너 및 JetStream 상태 확인
-```bash
-# MQTT 리스너 활성화 확인
-curl -s http://192.168.1.100:8222/varz | grep -i mqtt
-
-# JetStream 엔진 정상 구동 확인
-curl -s http://192.168.1.100:8222/jsz
-```
-
-### Step 2. 임시 잡 등록 및 연결 검증 이벤트 발행
-`publish_event.py`는 레지스트리에 등록된 잡에 대해서만 발행을 수행하므로, 임시 잡을 등록하고 발행한 후 완료 처리합니다.
-
-```bash
-# 1) 임시 잡 등록 (자동 채번된 JID 캡처)
-JID=$(.venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py \
-        --registry-dir .mam/jobs \
-        register \
-          --prompt "Private broker connectivity test" \
-          --agent-session "herdr:test")
-echo "registered test job: $JID"
-
-# 2) 이벤트 발행 (상세 로그 출력 및 rc=0 단언)
-.venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/publish_event.py \
-  --registry-dir .mam/jobs \
-  --job "$JID" \
-  --event progress \
-  --detail "Private broker connection verified" -v
-
-# 3) 테스트 잡 종결 처리 (미종결 시 --wait-any 유령 잡 잔존 방지)
-.venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py \
-  --registry-dir .mam/jobs status --job "$JID" --set completed
-```
-
-### Step 3. 접속 대상 브로커 IP 단언
-Step 2의 `-v` 출력 로그 또는 `.mam/delegate_job_logs/$JID/events.ndjson` 파일에서 실제 접속 호스트가 개인 브로커 IP로 나타나고 `broker.hivemq.com`이 포함되지 않았는지 확인합니다.
-
-### Step 4. 단위 회귀 테스트 검증
-```bash
-.venv/bin/python -m pytest tests/ -q
-```
-*참고: MAM의 기본 단위/컴포넌트 테스트 스위트는 모의(Mock) 객체를 사용하므로 브로커 연결 여부와 무관하게 100% 통과합니다. 실제 네트워크 연동 검증은 Step 1~3이 담당합니다.*
-
---
-
-## 8. 권장 실행 순서
-
-```
-[Phase 1: 내결함성 확보] ──> [Phase 2: 개인 브로커 가동] ──> [Phase 3: A-2 보안 완전 종결]
- Track 0 (B-14, B-15)         nats-server (nats.conf)         지문 토픽 및 인증 토큰 발급
- 로컬 디스크 폴백 패치         .mam.env 환경변수 연동         외부 간섭 100% 차단
-```
-
-1. **Phase 1 (Track 0 선행 패치)**: `publish_event.py`와 `job_subscriber.py`의 로컬 디스크 폴백(`B-14`, `B-15`)을 먼저 적용하여 브로커 다운 시에도 루프가 멈추지 않는 방탄 구조를 확립합니다.
-2. **Phase 2 (개인 브로커 가동)**: 개인 서버에 `nats-server -c nats.conf`를 구동하고 `.mam.env`에 `MQTT_BROKER`를 연결합니다.
-3. **Phase 3 (A-2 보안 완전 종결)**: 워크스페이스 지문 토픽(`mam/<sha256[:12]>/jobs/...`) 및 무조건 토큰 발급을 적용하여 공개 브로커 위험을 완전히 영구 폐기합니다.
@@ -127,6 +127,12 @@ $ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --list
 $ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --remove <orchestrator_uuid>
 ```

+### 7) 전용 NATS 메시징 브로커 설정 (.mam.env)
+MAM은 비동기 작업 위임(`multi-agent-mux-delegate-job`) 및 이벤트 스트림 중계를 위해 MQTT 3.1.1 및 JetStream 기반의 사설 NATS 브로커(`nats-docker`)를 표준으로 지원합니다.
+*   **환경 설정 생성**: `bash deploy/generate-env.sh` (또는 `cp .mam.env.example .mam.env`)를 실행하여 로컬 `.mam.env`를 생성합니다.
+*   **서브모듈 동기화**: `git submodule update --init --recursive` 명령어로 `nats-docker/` 배포 자산을 초기화합니다.
+*   **사설 서버 배포 가이드**: 자세한 도커 배포 및 Tailscale 연동 절차는 [`nats-docker/PRIVATE_SERVER.md`](../nats-docker/PRIVATE_SERVER.md) 및 [`MESSAGING.md`](../MESSAGING.md)를 참조하십시오.
+
 ---

 ## 🛡️ 협업 및 보안 가이드라인
@@ -68,6 +68,19 @@ To register these skills globally or for a specific workspace:
    }
    ```

+### 5. Private NATS Broker & Submodule Integration (`nats-docker`)
+For production deployments and private networks, MAM utilizes a dedicated NATS broker (`nats:2.12-alpine` with MQTT 3.1.1 and JetStream enabled). The container assets and deployment guides are managed in the `nats-docker` submodule:
+
+```bash
+# When cloning the repository, initialize submodules:
+git clone --recurse-submodules https://git.godopu.com/tmpl/multi-agent-mux.git
+
+# Or initialize submodules in an existing clone:
+git submodule update --init --recursive
+```
+
+Refer to [`nats-docker/PRIVATE_SERVER.md`](../nats-docker/PRIVATE_SERVER.md) and [`MESSAGING.md`](../MESSAGING.md) for detailed configuration, `.mam.env` generation, and security guidelines.
+
 ---

 ## 🤖 Gitea Actions CI/CD Setup
@@ -85,6 +85,8 @@ jobs:
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3
+        with:
+          submodules: recursive

      - name: Set up Python
        uses: actions/setup-python@v4
@@ -506,7 +506,7 @@ fi

 if [ ! -f "$MAM_ENV" ]; then
  echo "📝 Initializing $MAM_ENV with default orchestration configuration..."
-  MAM_CLIENT_PREFIX="mam-agent"
+  MAM_CLIENT_PREFIX="hermes"
  MAM_PORT="1883"
  
  cat <<EOF > "$MAM_ENV"
@@ -1,25 +1,26 @@
 # 🚀 MAM 메시징 백플레인 전환 실행 로드맵 (`implementation_plan.md`)

- **문서 버전**: v1.0.0 (`8c651798` / `28bb7340`)
+- **문서 버전**: v1.2.0
 - **작성/관리 주체**: Multi-Agent Orchestration Team (`claude`, `agy`, `cline`)
- **기준 커밋**: `a9934ad` (276/276 baseline tests passing)
- **문서 목적**: MAM의 메시징 인프라를 공개 HiveMQ 브로커에서 `nats-server` 전용 사설 브로커로 무중단 전환하기 위한 4개 트랙(Track 0~3)과 5단계 마일스톤(M0~M4)의 구체적 실행 지침 및 진행 상황 추적.
- **연계 문서**: [`NATS_REPORT.md`](NATS_REPORT.md), [`PRIVATE_SERVER.md`](PRIVATE_SERVER.md), [`IMPROVEMENTS.md`](IMPROVEMENTS.md)
+- **기준 커밋**: `916185c` (306/306 baseline tests passing)
+- **문서 목적**: MAM의 메시징 인프라를 공개 HiveMQ 브로커에서 `nats-server` 전용 사설 브로커로 무중단 전환하기 위한 5개 트랙(Track 0~3, Track 1R)과 6단계 마일스톤(M0~M4, M2b)의 구체적 실행 지침 및 진행 상황 추적.
+- **연계 문서**: [`NATS_REPORT.md`](nats-docker/NATS_REPORT.md), [`PRIVATE_SERVER.md`](nats-docker/PRIVATE_SERVER.md), [`IMPROVEMENTS.md`](IMPROVEMENTS.md)

 ---

-## 1. 개요 및 4개 트랙 구조
+## 1. 개요 및 5개 트랙 구조

 ```
-[M0: 문서 정합성] ──> [M1: 내결함성 확보] ──> [M2: 브로커 실증] ──> [M3: 보안 종결] ──> [M4: 동기화 완료]
- (E-1~E-4 교정,       (Track 0: B-14,B-15,     (Track 1: O-5      (Track 2: A-2,      (Track 3: 문서,
-  G-D1~G-D4 가드)      G-1~G-10 가드)           S-1~S-9 스파이크)  지문 토픽, G-11)    배포 스크립트)
+[M0: 문서 정합성] ──> [M1: 내결함성 확보] ──> [M2a: 로컬스파이크 / M2b: 원격배포] ──> [M3: 보안 종결] ──> [M4: 동기화 완료]
+ (E-1~E-4 교정,       (Track 0: B-14,B-15,     (Track 1: O-5 스파이크 /          (Track 2: A-2,      (Track 3: 문서,
+  G-D1~G-D4 가드)      G-1~G-10 가드)           Track 1R: 원격 자산·서브모듈)      지문 토픽, G-11)    배포 스크립트)
 ```

 | 트랙 | 대상 과제 | 핵심 목표 | 코드 변경 지점 |
 |---|---|---|---|
 | **Track 0** | `B-14`, `B-15` (P1) | 브로커 다운 시 65분 정지(Hang) 및 오판정 방지 (로컬 디스크 내결함성) | `publish_event.py`, `job_subscriber.py`, `multi-agent-mux-delegate-job` |
 | **Track 1** | `O-5` (P2) | `nats-server` MQTT 3.1.1 어댑터 호환성 및 Retained 메시지 실측 검증 | 격리 클론 (`$SCRATCH/nats-spike`) |
+| **Track 1R** | 원격 프로덕션 (P1) | VPS/홈랩 `nats-server` Docker 상시 가동, 서브모듈 분리 및 MAM 원격 백플레인 전환 | `nats-docker/PRIVATE_SERVER.md` §9, `nats-docker/docker/docker-compose.yaml`, `nats.conf`, `.mam.env` |
 | **Track 2** | `A-2`, `B-16` (P2) | 워크스페이스 지문 토픽 격리 및 `auth_token` 무조건 발급 강제 | `mqtt_common.py`, `registry.py`, `reconcile.sh` |
 | **Track 3** | 문서/설정 동기화 | 공식 가이드, 배포 스크립트, 환경변수 템플릿 일원화 | `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` |

@@ -30,15 +31,16 @@
 각 마일스톤은 완료 정의(DoD)와 엄격한 게이트(Gate)를 가지며, 게이트 조건을 충족하지 못하면 다음 마일스톤으로 진입할 수 없습니다.

 ```
-M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실증) ──> M3 (Track 2 보안) ──> M4 (Track 3 완결)
+M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2a (로컬 스파이크) ──> M2b (원격 배포) ──> M3 (Track 2 보안) ──> M4 (Track 3 완결)
 ```

 | 마일스톤 | 이름 | 완료 정의 (Definition of Done) | 통과 게이트 (Gate Condition) |
 |---|---|---|---|
 | **M0** | 문서 정합성 확보 | `PRIVATE_SERVER.md` E-1~E-4 교정, 다능성 절 추가, 본 로드맵 작성 | **G-D1 ~ G-D4 가드 테스트 통과** (276 -> 280) |
 | **M1** | 내결함성 확보 (Track 0) | `B-14`, `B-15` 코드 패치 완료 | **G-1 ~ G-10 가드 통과 + mutation 전건 FAIL 확인** (280 -> 290) |
-| **M2** | 브로커 실증 (Track 1) | 격리 클론에서 S-1 ~ S-9 스파이크 완수 | **S-3(Retained Terminal Event) 통과** (실패 시 mosquitto로 분기) |
-| **M3** | 보안 종결 (Track 2) | A-2 지문 토픽 전환, G-11 무조건 토큰 발급 | 지문 토픽 동작 확인 **후** legacy 구독 제거 (290 -> 291) |
+| **M2a** | 로컬 스파이크 (Track 1) | 격리 클론에서 S-1 ~ S-9 스파이크 완수 | **S-3(Retained Terminal Event) 통과** (실패 시 mosquitto로 분기) |
+| **M2b** | 원격 프로덕션 전환 (Track 1R) | D-1~D-5 교정 + §9 원격 배포 + 서브모듈 분리 + §9.5 전환 | **R-3(노출0) · R-5(retained) · R-6(신원) · R-9(계정격리) 동시 통과** (290 -> 297 -> 306) |
+| **M3** | 보안 종결 (Track 2) | A-2 지문 토픽 전환, G-11 무조건 토큰 발급 | 지문 토픽 동작 확인 **후** legacy 구독 제거 |
 | **M4** | 동기화 완료 (Track 3) | `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` 정합 | 전체 테스트 스위트 100% Green |

 ---
@@ -102,7 +104,31 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실

 ---

-## 5. Track 2: A-2 보안 결함 및 워크스페이스 격리 해소 (`A-2`, `B-16`)
+## 5. Track 1R: 원격 프로덕션 전환 로드맵 (M2b 상세)
+
+```
+[P0 교정]        D-1~D-5 문서 교정 + §5.2 경계 명문화 + 신규 가드 7종
+   ▼
+[P0.5 자산화]    docker/ 4대 자산 정본화 + D-22~D-30 회귀 가드 (297 -> 306)
+   ▼
+[P0.6 서브모듈]  nats-docker 서브모듈 분리 + 동적 경로 해석기 + CI checkout 동기화
+   ▼
+[P1 서버 준비]   VPS/홈랩 프로비저닝, Docker, Tailscale 가입
+   ▼
+[P2 배포]        nats.conf + compose 기동, healthcheck healthy 확인
+   ▼
+[P3 잠금]        바인드 주소 한정 + UFW + ss/nmap 로 노출 면적 0 단언 (R-3)
+   ▼
+[P4 전환]        드레인 → 잔여 스캔 → .mam.env 교체 (§9.5)
+   ▼
+[P5 검증]        R-1 ~ R-13. R-5(retained) / R-9(계정 경계) / R-13(MQTT-over-WS)
+   ▼
+[P6 상시화]      로그 로테이션, JetStream 볼륨 백업, healthcheck 알림
+```
+
+---
+
+## 6. Track 2: A-2 보안 결함 및 워크스페이스 격리 해소 (`A-2`, `B-16`)

 1. **`auth_token` 무조건 발급 (`F-3` / `G-11`)**:
   `registry.register_job()`에서 브로커 설정과 무관하게 항상 `secrets.token_urlsafe(32)` 기반 토큰을 발급하여 공개 브로커 환경에서도 HMAC 검증이 무력화되지 않도록 강제합니다.
@@ -113,34 +139,19 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실

 ---

-## 6. Track 3: 문서 및 배포 설정 동기화
+## 7. Track 3: 문서 및 배포 설정 동기화

 | 대상 파일 | 갱신 내용 |
 |---|---|
-| [`MESSAGING.md`](MESSAGING.md) | 브로커 표준을 `nats-server`로 갱신, F-1/C1 해소 기록, F-5 영속 세션 서술 정정 |
-| [`IMPROVEMENTS.md`](IMPROVEMENTS.md) | A-2 완료 전환, B-14/B-15/B-16/O-5 해결 상태 갱신 |
+| [`MESSAGING.md`](MESSAGING.md) | 브로커 표준을 `nats-server`로 갱신, F-1/C1 해소 기록, F-5 영속 세션 서술 정정, 10개 환경변수 및 해석 계층 문서화 |
+| [`IMPROVEMENTS.md`](IMPROVEMENTS.md) | B-14/B-15 완료 상태 반영, O-6 신설, B-17/B-18 신설 등록 |
 | [`VERSIONS.md`](VERSIONS.md) | `v2.0.0` 릴리스 노트에 메시징 백플레인 고도화 및 내결함성 패치 기록 |
-| [`PRIVATE_SERVER.md`](PRIVATE_SERVER.md) | 스파이크 결과 반영 및 최종 가이드 확정 |
+| [`PRIVATE_SERVER.md`](nats-docker/PRIVATE_SERVER.md) | 스파이크 결과 반영 및 최종 가이드 확정 |
 | [`deploy/install.sh`](deploy/install.sh) | `requirements.txt` 확인 (paho 유지) 및 개인 브로커 안내 추가 |
 | [`.mam.env`](.mam.env) | `MQTT_BROKER`, `MQTT_PORT`, `MQTT_TLS` 기본 템플릿 확정 |

 ---

-## 7. 의존성 그래프 및 롤백 전략
-
-```
-[M0: 문서/가드] ────────────┐
-  │                         │ (M0 A-1 환경변수 정렬 선행)
-  ▼                         ▼
-[M1: Track 0 내결함성] ──> [M2: Track 1 스파이크] ──> [M3: Track 2 보안] ──> [M4: 동기화]
-```
-
- **롤백 전략**:
-  - `nats-server` 스파이크(S-3) 실패 시: 클라이언트 코드 변경 없이 `.mam.env`의 브로커 주소만 `eclipse-mosquitto`로 전환합니다 (가역성 100%).
-  - Track 0 내결함성 패치는 브로커 제품과 무관하게 순수 이득이므로 롤백하지 않고 영구 유지합니다.
-
---
-
 ## 8. 진행 추적 체크리스트

 ### M0: 문서 정합성 확보
@@ -154,14 +165,31 @@ M0 (문서 정합성) ──> M1 (Track 0 내결함성) ──> M2 (Track 1 실
 - [x] Step 3: `multi-agent-mux-delegate-job` 인프라 `rc=3` 에러 분리 (`F-4` / G-9~G-10)
 - [x] M1 통합 검증 (브로커 다운 상태 위임 3초 완주)

-### M2: Track 1 `nats-server` 실증 (`O-5`)
+### M2a: Track 1 `nats-server` 로컬 실증 (`O-5`)
 - [ ] 격리 클론 생성 (`$SCRATCH/nats-spike`)
 - [ ] S-1 ~ S-9 스파이크 매트릭스 검증 수행
 - [ ] S-3 Retained 메시지 게이트 통과 확인

+### M2b: Track 1R 원격 프로덕션 전환
+- [x] D-1 `store_dir` 절대경로 교정 + 비인용 heredoc (`PRIVATE_SERVER.md` §4.1, §9.1)
+- [x] D-2 이미지 핀 `nats:2.12-alpine` + `/healthz` healthcheck
+- [x] D-3 8222/8080 바인드 주소 한정
+- [x] D-4 TLS 절의 IP 예시 제거 및 DNS/SAN 요건 명시
+- [x] D-5 `.mam.env.example` 정합 (`MQTT_KEEPALIVE` 추가)
+- [x] N-1 §5.2 에 retained=MQTT 전용 경계 명문화 + §9.1 `mam_observer` 추가
+- [x] 신규 가드 G-D5 ~ G-D9, G-R1, G-R2 구현 및 검증 (290 -> 297)
+- [x] P0.5: `docker/` 프로덕션 배포 자산 정본화 및 D-22 ~ D-30 회귀 가드 (297 -> 306)
+- [x] P0.6: `docker/` 자산의 `nats-docker` 서브모듈 분리 및 `PRIVATE_SERVER.md`/`NATS_REPORT.md` 이전 (`629a67f`, `12ba30b`, `916185c`)
+- [x] P0.6: 테스트 동적 경로 해석기(`_resolve_private_server_doc` / `_resolve_docker_dir`) 도입
+- [x] P0.6: CI checkout 에 `submodules: recursive` 적용 (`deploy/gitea-ci.yml`)
+- [ ] 서버 배포 및 R-3 노출 면적 0 단언
+- [x] §9.5 사설 브로커(`vm-ubuntu`)로 `.mam.env` 전환 완료 (사후 잔여 드레인 스캔 과제 기록)
+- [ ] R-1 ~ R-13 전건 통과 (R-5 / R-9 / R-13 최종 관문)
+
 ### M3: Track 2 보안 및 토픽 격리 (`A-2`, `B-16`)
 - [ ] G-11 무조건 `auth_token` 발급 적용
 - [ ] 워크스페이스 지문 토픽 발행 전환 및 레거시 구독 제거

 ### M4: Track 3 문서 및 배포 동기화
 - [ ] `MESSAGING.md`, `IMPROVEMENTS.md`, `VERSIONS.md`, `deploy/*` 최종 갱신
+
@@ -0,0 +1,2 @@
+pytest>=8.0
+PyYAML>=6.0
@@ -17,6 +17,7 @@ import sys
 import tempfile

 import pytest
+import yaml

 REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))

@@ -266,6 +267,20 @@ def test_d10_customization_survives_repeated_refresh(src_and_target):
            "user gets no signal that their edit is diverging" % n)


+def _resolve_private_server_doc() -> str:
+    for candidate in [
+        os.path.join(REPO_ROOT, "nats-docker", "PRIVATE_SERVER.md"),
+        os.path.join(REPO_ROOT, "nats-docker", "docs", "PRIVATE_SERVER.md"),
+        os.path.join(REPO_ROOT, "PRIVATE_SERVER.md"),
+    ]:
+        if os.path.exists(candidate):
+            return candidate
+    return os.path.join(REPO_ROOT, "nats-docker", "PRIVATE_SERVER.md")
+
+
+PRIVATE_SERVER_DOC_PATH = _resolve_private_server_doc()
+
+
 # --------------------------------------------------------------------------
 # D-11 — (G-D1) PRIVATE_SERVER.md must only document MQTT_* environment
 #        variables that broker_config_from_env() actually parses.
@@ -274,8 +289,8 @@ def test_d11_private_server_env_names_valid():
    sys.path.insert(0, os.path.join(REPO_ROOT, ".agents", "skills", "multi-agent-mux-delegate-job", "scripts"))
    import mqtt_common

-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
-    assert os.path.exists(doc_path), "PRIVATE_SERVER.md missing"
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    assert os.path.exists(doc_path), f"PRIVATE_SERVER.md missing at {doc_path}"
    with open(doc_path, "r", encoding="utf-8") as f:
        content = f.read()

@@ -283,16 +298,11 @@ def test_d11_private_server_env_names_valid():
    code_blocks = re.findall(r"```(?:bash|conf|yaml|)(.*?)```", content, re.DOTALL)
    assert code_blocks, "No code blocks found in PRIVATE_SERVER.md"

-    # Known recognized MQTT env vars from broker_config_from_env()
-    recognized = {
-        "MQTT_BROKER", "MQTT_PORT", "MQTT_TLS", "MQTT_USERNAME", "MQTT_PASSWORD",
-        "MQTT_CLIENT_ID_PREFIX", "MQTT_CA_CERTS", "MQTT_CERTFILE", "MQTT_KEYFILE",
-        "MQTT_KEEPALIVE", "MAM_MQTT_HOST"  # checked for exclusion
-    }
+    # Known recognized MQTT env vars from broker_config_from_env() and deployment
    valid_mqtt_vars = {
        "MQTT_BROKER", "MQTT_PORT", "MQTT_TLS", "MQTT_USERNAME", "MQTT_PASSWORD",
        "MQTT_CLIENT_ID_PREFIX", "MQTT_CA_CERTS", "MQTT_CERTFILE", "MQTT_KEYFILE",
-        "MQTT_KEEPALIVE"
+        "MQTT_KEEPALIVE", "MQTT_BIND"
    }

    for block in code_blocks:
@@ -306,7 +316,7 @@ def test_d11_private_server_env_names_valid():
 #        active configuration code blocks.
 # --------------------------------------------------------------------------
 def test_d12_private_server_no_mam_mqtt_in_code_fences():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
    with open(doc_path, "r", encoding="utf-8") as f:
        content = f.read()

@@ -322,7 +332,7 @@ def test_d12_private_server_no_mam_mqtt_in_code_fences():
 #        use valid config blocks (mqtt {) and not HTTP port flag (-m 1883).
 # --------------------------------------------------------------------------
 def test_d13_private_server_nats_config_valid():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
    with open(doc_path, "r", encoding="utf-8") as f:
        content = f.read()

@@ -338,7 +348,7 @@ def test_d13_private_server_nats_config_valid():
 #        CLI flags matching the actual scripts' argparse parsers.
 # --------------------------------------------------------------------------
 def test_d14_private_server_cli_args_valid():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
    with open(doc_path, "r", encoding="utf-8") as f:
        content = f.read()

@@ -352,3 +362,450 @@ def test_d14_private_server_cli_args_valid():
    )
    assert "status --job " in code_blocks, "PRIVATE_SERVER.md must include cleanup step with status --job"

+
+# --------------------------------------------------------------------------
+# D-15 — (G-D5) store_dir in code blocks must be absolute path (/ or $HOME)
+#        and heredocs writing it must be unquoted (<<EOF).
+# --------------------------------------------------------------------------
+def test_d15_private_server_store_dir_valid():
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    code_blocks = re.findall(r"```(?:bash|conf|yaml|)(.*?)```", content, re.DOTALL)
+    for i, block in enumerate(code_blocks):
+        for match in re.finditer(r'store_dir:\s*["\']?([^"\'\n]+)["\']?', block):
+            val = match.group(1).strip()
+            assert val.startswith("/") or val.startswith("$HOME"), (
+                f"Block #{i+1} store_dir '{val}' must start with '/' or '$HOME' (no literal ~)"
+            )
+        if "store_dir:" in block and "cat <<" in block:
+            assert "<<'EOF'" not in block, (
+                f"Block #{i+1} writes store_dir with quoted heredoc <<'EOF', which prevents $HOME expansion"
+            )
+
+
+# --------------------------------------------------------------------------
+# D-16 — (G-D6) nats image references in code fences must use pinned alpine
+# --------------------------------------------------------------------------
+def test_d16_private_server_nats_image_alpine_pinned():
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    code_blocks = re.findall(r"```(?:bash|conf|yaml|)(.*?)```", content, re.DOTALL)
+    for i, block in enumerate(code_blocks):
+        nats_refs = re.findall(r'\bnats:([a-zA-Z0-9_.-]+)', block)
+        for tag in nats_refs:
+            assert tag != "latest", f"Block #{i+1} contains unpinned 'nats:latest'"
+            assert "alpine" in tag, f"Block #{i+1} nats image '{tag}' must use alpine variant"
+
+
+# --------------------------------------------------------------------------
+# D-17 — (G-D7) Port 8222 in docker examples must be bound to 127.0.0.1
+# --------------------------------------------------------------------------
+def test_d17_private_server_monitoring_port_localhost_bound():
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    code_blocks = re.findall(r"```(?:bash|conf|yaml|)(.*?)```", content, re.DOTALL)
+    for i, block in enumerate(code_blocks):
+        for match in re.finditer(r'["\']?([0-9a-zA-Z._$:-]*8222:8222)["\']?', block):
+            mapping = match.group(1).strip()
+            assert "127.0.0.1:8222:8222" in mapping, (
+                f"Block #{i+1} port 8222 must be bound to 127.0.0.1, got '{mapping}'"
+            )
+
+
+# --------------------------------------------------------------------------
+# D-18 — (G-D8) TLS examples must not use IP literals for MQTT_BROKER
+# --------------------------------------------------------------------------
+def test_d18_private_server_tls_examples_use_domain_names():
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    code_blocks = re.findall(r"```(?:bash|conf|yaml|)(.*?)```", content, re.DOTALL)
+    for i, block in enumerate(code_blocks):
+        if "MQTT_TLS=1" in block or "port: 8883" in block:
+            for match in re.finditer(r'MQTT_BROKER=["\']?([0-9.]+)', block):
+                ip = match.group(1)
+                assert False, f"Block #{i+1} uses IP literal '{ip}' with TLS (must use DNS domain name for SAN verification)"
+
+
+# --------------------------------------------------------------------------
+# D-19 — (G-D9) Subject literals in config examples match DEFAULT_TOPIC_ROOT
+# --------------------------------------------------------------------------
+def test_d19_private_server_subject_literals_match_default_topic_root():
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    with open(doc_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    sys.path.insert(0, os.path.join(REPO_ROOT, ".agents", "skills", "multi-agent-mux-delegate-job", "scripts"))
+    import mqtt_common
+    expected_prefix = mqtt_common.DEFAULT_TOPIC_ROOT.replace("/", ".")
+    matches = re.findall(r'["\'](python\.mqtt\.jobs\.[>*\w.]+)["\']', content)
+    assert matches, "Expected subject literals matching DEFAULT_TOPIC_ROOT in PRIVATE_SERVER.md"
+    for sub in matches:
+        assert sub.startswith(expected_prefix), f"Subject '{sub}' does not start with expected prefix '{expected_prefix}'"
+
+
+# --------------------------------------------------------------------------
+# D-20 — (G-R1) run_loop.sh exports MAM_ENV_FILE
+# --------------------------------------------------------------------------
+def test_d20_run_loop_exports_mam_env_file():
+    run_loop_path = os.path.join(REPO_ROOT, ".agents", "skills", "multi-agent-mux-loop", "scripts", "run_loop.sh")
+    with open(run_loop_path, "r", encoding="utf-8") as f:
+        content = f.read()
+    assert 'export MAM_ENV_FILE=' in content, "run_loop.sh must export MAM_ENV_FILE"
+
+
+# --------------------------------------------------------------------------
+# D-21 — (G-R2) MQTT_KEEPALIVE documented and no un-commented retry vars
+# --------------------------------------------------------------------------
+def test_d21_env_template_mqtt_var_coverage():
+    template_path = os.path.join(REPO_ROOT, ".mam.env.example")
+    with open(template_path, "r", encoding="utf-8") as f:
+        template = f.read()
+    assert "MQTT_KEEPALIVE" in template, ".mam.env.example must document MQTT_KEEPALIVE"
+    for line in template.splitlines():
+        line = line.strip()
+        if not line.startswith("#"):
+            assert "MQTT_RETRY_INTERVAL" not in line
+            assert "MQTT_MAX_RETRIES" not in line
+
+
+# ==============================================================================
+# Track 1R / M2b — docker/ Canonical Deployment Assets Guards (D-22 ~ D-30)
+# ==============================================================================
+def _resolve_docker_dir() -> str:
+    for candidate in [
+        os.path.join(REPO_ROOT, "nats-docker", "docker"),
+        os.path.join(REPO_ROOT, "nats-docker"),
+        os.path.join(REPO_ROOT, "docker"),
+    ]:
+        if os.path.exists(os.path.join(candidate, "docker-compose.yaml")):
+            return candidate
+    return os.path.join(REPO_ROOT, "nats-docker", "docker")
+
+
+DOCKER_DIR = _resolve_docker_dir()
+COMPOSE_PATH = os.path.join(DOCKER_DIR, "docker-compose.yaml")
+NATS_CONF_PATH = os.path.join(DOCKER_DIR, "nats.conf")
+ENV_EXAMPLE_PATH = os.path.join(DOCKER_DIR, ".env.example")
+DOCKER_README_PATH = os.path.join(DOCKER_DIR, "README.md")
+
+SECRET_VARS = {"MAM_BROKER_PASS", "MAM_OBSERVER_PASS",
+               "HOME_BROKER_PASS", "SYS_BROKER_PASS"}
+
+
+def _load_compose():
+    """compose 파일을 dict 로. 파일이 비었거나 nats 서비스가 없으면 즉시 실패."""
+    import yaml
+    with open(COMPOSE_PATH, encoding="utf-8") as f:
+        doc = yaml.safe_load(f)
+    assert isinstance(doc, dict) and doc.get("services"), (
+        "docker/docker-compose.yaml is empty or has no services: — the docker/ "
+        "assets were never populated")
+    svc = doc["services"].get("nats")
+    assert svc, "compose file defines no 'nats' service"
+    return doc, svc
+
+
+def _active_conf_lines():
+    """nats.conf 에서 주석을 제외한 '활성' 라인만. 주석 템플릿을 오탐하지 않기 위함."""
+    with open(NATS_CONF_PATH, encoding="utf-8") as f:
+        lines = [ln.split("#", 1)[0].rstrip() for ln in f]
+    return [ln for ln in lines if ln.strip()]
+
+
+# --------------------------------------------------------------------------
+# D-22 — docker/ assets exist and are populated
+# --------------------------------------------------------------------------
+def test_d22_docker_assets_exist_and_are_populated():
+    for p in [COMPOSE_PATH, NATS_CONF_PATH, ENV_EXAMPLE_PATH, DOCKER_README_PATH]:
+        assert os.path.exists(p), f"Required asset {p} does not exist"
+        assert os.path.getsize(p) > 0, f"Required asset {p} is empty (0 bytes)"
+    _load_compose()
+
+
+# --------------------------------------------------------------------------
+# D-23 — compose image matches doc and is alpine
+# --------------------------------------------------------------------------
+def test_d23_compose_image_matches_doc_and_is_alpine():
+    _, svc = _load_compose()
+    compose_img = svc.get("image", "")
+    assert compose_img.startswith("nats:"), f"Expected nats image in compose, got {compose_img}"
+    compose_tag = compose_img.split(":", 1)[1]
+    assert compose_tag != "latest", "Compose image tag must not be 'latest'"
+    assert "alpine" in compose_tag, f"Compose image tag '{compose_tag}' must use alpine variant"
+
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    with open(doc_path, "r", encoding="utf-8") as f:
+        doc_content = f.read()
+    doc_tags = re.findall(r'\bnats:([a-zA-Z0-9_.-]+)', doc_content)
+    assert doc_tags, "No nats image tags found in PRIVATE_SERVER.md"
+    assert compose_tag in doc_tags, f"Compose image tag '{compose_tag}' not found in PRIVATE_SERVER.md"
+
+
+# --------------------------------------------------------------------------
+# D-24 — compose port exposure contract
+# --------------------------------------------------------------------------
+def test_d24_compose_port_exposure_contract():
+    _, svc = _load_compose()
+    ports = svc.get("ports", [])
+    assert ports, "No ports exposed in nats service"
+
+    ctr_ports = set()
+    for p in ports:
+        parts = str(p).rsplit(":", 2)
+        assert len(parts) == 3, f"Port mapping '{p}' must specify 3 parts (host:hostport:ctrport), bare mappings forbidden"
+        ctr_ports.add(int(parts[2]))
+
+    assert ctr_ports == {1883, 4222, 8222, 8080}, f"Expected container ports {1883, 4222, 8222, 8080}, got {ctr_ports}"
+
+    p8222 = [p for p in ports if str(p).endswith(":8222")]
+    assert len(p8222) == 1, "Port 8222 mapping must exist"
+    assert "127.0.0.1" in str(p8222[0]), f"Port 8222 must default or be fixed to loopback 127.0.0.1, got '{p8222[0]}'"
+
+
+# --------------------------------------------------------------------------
+# D-25 — secrets are fail closed
+# --------------------------------------------------------------------------
+def test_d25_secrets_are_fail_closed():
+    _, svc = _load_compose()
+    env = svc.get("environment", {})
+    if isinstance(env, list):
+        env_dict = {}
+        for item in env:
+            k, v = item.split("=", 1)
+            env_dict[k.strip()] = v.strip()
+        env = env_dict
+
+    with open(NATS_CONF_PATH, "r", encoding="utf-8") as f:
+        conf_text = f.read()
+
+    active_text = "\n".join(_active_conf_lines())
+    nats_vars = set(re.findall(r'\$([A-Z0-9_]+)', active_text))
+    assert nats_vars, "No $VAR references found in nats.conf"
+    assert nats_vars.issubset(set(env.keys())), f"nats.conf variables {nats_vars} not in compose environment {set(env.keys())}"
+
+    for k, v in env.items():
+        assert "${" in v and ":?" in v, f"Environment variable '{k}={v}' must use '${{VAR:?error}}' fail-closed syntax"
+
+    with open(ENV_EXAMPLE_PATH, "r", encoding="utf-8") as f:
+        example_text = f.read()
+
+    for svar in SECRET_VARS:
+        assert svar in example_text, f"Secret variable '{svar}' missing from .env.example"
+
+    for line in example_text.splitlines():
+        line = line.strip()
+        for svar in SECRET_VARS:
+            if line.startswith(f"{svar}="):
+                val = line.split("=", 1)[1].strip()
+                assert val == "", f"Secret variable '{svar}' in .env.example must have empty value, got '{val}'"
+
+    for match in re.finditer(r'password:\s*([^\s,}]+)', conf_text):
+        pw_val = match.group(1).strip()
+        assert pw_val.startswith("$"), f"nats.conf contains non-variable password value '{pw_val}'"
+
+
+# --------------------------------------------------------------------------
+# D-26 — nats_conf jetstream and mqtt contract
+# --------------------------------------------------------------------------
+def test_d26_nats_conf_jetstream_and_mqtt_contract():
+    _, svc = _load_compose()
+    volumes = svc.get("volumes", [])
+    target_data_vol = None
+    for vol in volumes:
+        parts = str(vol).split(":")
+        if len(parts) >= 2 and parts[1] == "/data":
+            target_data_vol = parts[1]
+    assert target_data_vol == "/data", "Compose volume must mount to /data"
+
+    with open(NATS_CONF_PATH, "r", encoding="utf-8") as f:
+        conf_text = f.read()
+
+    store_dir_match = re.search(r'store_dir:\s*["\']?([^"\'\s,}]+)["\']?', conf_text)
+    assert store_dir_match, "store_dir not found in nats.conf"
+    assert store_dir_match.group(1).strip() == "/data", f"store_dir must be '/data', got '{store_dir_match.group(1)}'"
+
+    for key in ["max_file", "max_mem"]:
+        m = re.search(rf'{key}:\s*([^\s,}}]+)', conf_text)
+        assert m, f"{key} not found in nats.conf"
+        assert re.match(r'^\d+[KMGT]$', m.group(1).strip()), f"{key} '{m.group(1)}' must match regex '^\\d+[KMGT]$'"
+
+    assert "mqtt {" in conf_text, "mqtt { block missing in nats.conf"
+    assert "port: 1883" in conf_text or "port:1883" in conf_text, "mqtt port 1883 missing in nats.conf"
+    assert "MAM:" in conf_text and "jetstream: enabled" in conf_text, "Account MAM must have 'jetstream: enabled'"
+
+
+# --------------------------------------------------------------------------
+# D-27 — observer permissions match topic root
+# --------------------------------------------------------------------------
+def test_d27_observer_permissions_match_topic_root():
+    sys.path.insert(0, os.path.join(REPO_ROOT, ".agents", "skills", "multi-agent-mux-delegate-job", "scripts"))
+    import mqtt_common
+    expected_prefix = mqtt_common.DEFAULT_TOPIC_ROOT.replace("/", ".")
+
+    with open(NATS_CONF_PATH, "r", encoding="utf-8") as f:
+        conf_text = f.read()
+
+    subjects = re.findall(r'["\']([a-zA-Z0-9_.-]+(?:\.>|\.\*)?)["\']', conf_text)
+    job_subjects = [s for s in subjects if "jobs" in s]
+    assert job_subjects, "No job subjects found in nats.conf"
+    for s in job_subjects:
+        assert s.startswith(expected_prefix), f"Subject '{s}' in nats.conf does not match prefix '{expected_prefix}'"
+
+    assert "mam_observer" in conf_text, "mam_observer user missing in nats.conf"
+    assert "deny:" in conf_text, "Publish deny permission missing for mam_observer in nats.conf"
+
+
+# --------------------------------------------------------------------------
+# D-28 — healthcheck contract and image coupling
+# --------------------------------------------------------------------------
+def test_d28_healthcheck_contract_and_image_coupling():
+    _, svc = _load_compose()
+    hc = svc.get("healthcheck")
+    assert hc, "healthcheck block missing from nats service"
+
+    test_cmd = hc.get("test", [])
+    test_str = " ".join(test_cmd) if isinstance(test_cmd, list) else str(test_cmd)
+    assert "wget" in test_str, f"Healthcheck test '{test_str}' must use wget"
+    assert "/healthz" in test_str, f"Healthcheck test '{test_str}' must target /healthz"
+    assert "127.0.0.1:8222" in test_str, f"Healthcheck test '{test_str}' must use 127.0.0.1:8222"
+
+    img = svc.get("image", "")
+    assert "alpine" in img, f"Image '{img}' must be alpine variant because healthcheck uses alpine wget"
+
+
+# --------------------------------------------------------------------------
+# D-29 — env secrets never tracked
+# --------------------------------------------------------------------------
+def test_d29_env_secrets_never_tracked():
+    is_submodule = os.path.exists(os.path.join(REPO_ROOT, ".gitmodules")) and "nats-docker" in DOCKER_DIR
+    target_repo = os.path.join(REPO_ROOT, "nats-docker") if is_submodule else REPO_ROOT
+    rel_env = os.path.relpath(os.path.join(DOCKER_DIR, ".env"), target_repo)
+    rel_ex = os.path.relpath(ENV_EXAMPLE_PATH, target_repo)
+
+    res_env = subprocess.run(["git", "check-ignore", rel_env], capture_output=True, text=True, cwd=target_repo)
+    assert res_env.returncode == 0, f"{rel_env} must be ignored by .gitignore"
+
+    res_ex = subprocess.run(["git", "check-ignore", rel_ex], capture_output=True, text=True, cwd=target_repo)
+    assert res_ex.returncode != 0, f"{rel_ex} must NOT be ignored by .gitignore"
+
+    res_ls = subprocess.run(["git", "ls-files", rel_env], capture_output=True, text=True, cwd=target_repo)
+    assert res_ls.stdout.strip() == "", f"{rel_env} must never be tracked in git"
+
+
+# --------------------------------------------------------------------------
+# D-30 — websocket origin policy is startable
+# --------------------------------------------------------------------------
+def test_d30_websocket_origin_policy_is_startable():
+    active_lines = _active_conf_lines()
+    active_text = "\n".join(active_lines)
+
+    assert "websocket {" in active_text, "websocket { block must exist in active nats.conf"
+    assert "no_tls: true" in active_text or "no_tls:true" in active_text, (
+        "Active nats.conf must specify 'no_tls: true' in websocket block (omission causes startup TLS error)"
+    )
+
+    for line in active_lines:
+        if "allowed_origins" in line:
+            assert '"*"' not in line and "'*'" not in line, (
+                f"allowed_origins must not contain '*' (NATS requires absolute URLs with http/https schemes, got '{line}')"
+            )
+
+    with open(NATS_CONF_PATH, "r", encoding="utf-8") as f:
+        full_conf = f.read()
+    assert "/mqtt" in full_conf, "nats.conf must document /mqtt WebSocket MQTT path (N-7)"
+
+
+# --------------------------------------------------------------------------
+# D-31 — Gitea CI checkout enables submodules for test jobs
+# --------------------------------------------------------------------------
+def test_d31_gitea_ci_submodules_in_test_job():
+    gitmodules_path = os.path.join(REPO_ROOT, ".gitmodules")
+    if not os.path.exists(gitmodules_path):
+        return  # Auto-disable when no submodules are configured
+
+    ci_path = os.path.join(REPO_ROOT, "deploy", "gitea-ci.yml")
+    assert os.path.exists(ci_path), f"Gitea CI workflow missing at {ci_path}"
+
+    with open(ci_path, "r", encoding="utf-8") as f:
+        ci_data = yaml.safe_load(f)
+
+    jobs = ci_data.get("jobs", {})
+    assert jobs, f"No jobs defined in {ci_path}"
+
+    test_jobs_found = 0
+    for job_name, job_data in jobs.items():
+        if not isinstance(job_data, dict):
+            continue
+        steps = job_data.get("steps", [])
+        
+        # Determine if this job runs pytest or test suites
+        is_test_job = False
+        for step in steps:
+            if not isinstance(step, dict):
+                continue
+            run_cmd = step.get("run", "")
+            if "pytest" in run_cmd or "tests/" in run_cmd:
+                is_test_job = True
+                break
+
+        if is_test_job:
+            test_jobs_found += 1
+            checkout_steps = [
+                s for s in steps
+                if isinstance(s, dict) and "actions/checkout" in str(s.get("uses", ""))
+            ]
+            assert checkout_steps, f"Test job '{job_name}' has no actions/checkout step"
+            for s in checkout_steps:
+                with_opts = s.get("with", {}) or {}
+                submodules_val = with_opts.get("submodules")
+                assert submodules_val, (
+                    f"Job '{job_name}' checkout step must enable submodules (e.g. submodules: recursive) "
+                    f"to prevent test_deploy_freshness failures in CI, got: {submodules_val}"
+                )
+
+    assert test_jobs_found > 0, (
+        "Anti-void assertion: expected at least 1 test execution job running pytest in deploy/gitea-ci.yml"
+    )
+
+
+# --------------------------------------------------------------------------
+# D-32 — MESSAGING.md documents all supported MQTT environment variables
+# --------------------------------------------------------------------------
+def test_d32_messaging_doc_covers_all_mqtt_env_vars():
+    messaging_path = os.path.join(REPO_ROOT, "MESSAGING.md")
+    assert os.path.exists(messaging_path), f"MESSAGING.md missing at {messaging_path}"
+
+    with open(messaging_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    doc_vars = set(re.findall(r'\b(MQTT_[A-Z0-9_]+)\b', content))
+    assert doc_vars, "No MQTT_* variables found in MESSAGING.md"
+
+    expected_vars = {
+        "MQTT_BROKER",
+        "MQTT_PORT",
+        "MQTT_TLS",
+        "MQTT_USERNAME",
+        "MQTT_PASSWORD",
+        "MQTT_CA_CERTS",
+        "MQTT_CERTFILE",
+        "MQTT_KEYFILE",
+        "MQTT_CLIENT_ID_PREFIX",
+        "MQTT_KEEPALIVE",
+    }
+
+    missing_vars = expected_vars - doc_vars
+    assert not missing_vars, (
+        f"MESSAGING.md is missing documentation for supported MQTT variables: {missing_vars}"
+    )
+
+
+
Author	SHA1	Message	Date
Godopu	f133e52863	docs(deploy): synchronize deploy/ assets with nats-docker submodule and hermes prefix defaults	2026-08-23 16:40:22 +09:00
Godopu	adecff2194	docs: synchronize MESSAGING.md, IMPROVEMENTS.md, implementation_plan.md and add D-31/D-32 freshness guards	2026-08-23 16:22:10 +09:00
Godopu	916185c751	docs: archive Reviewer cline PASS report and update submodule doc links	2026-08-23 15:36:32 +09:00
Godopu	12ba30bde1	docs: move PRIVATE_SERVER.md and NATS_REPORT.md to nats-docker submodule	2026-08-23 15:11:04 +09:00
Godopu	629a67f09d	feat(deploy): convert docker/ deployment assets to nats-docker submodule	2026-08-23 15:06:47 +09:00
Godopu	ed96a054e1	docs(reports): archive Reviewer cline PASS verification report for refactor branch commits	2026-08-23 14:54:23 +09:00
Godopu	b09d4209d8	feat(deploy): create production Docker assets in docker/ (compose, nats.conf, env template, README) with D-22~D-30 freshness guards	2026-08-23 11:18:17 +09:00
Godopu	3523b9b1ea	docs(broker): establish remote Docker deployment plan for nats-server with networking/security guides and add D-15~D-21 freshness guards	2026-08-22 23:47:29 +09:00