@kaydash9999/banker-plugins 0.4.0 → 0.6.0

package/skills/setup-python/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: setup-python
+description: "(banker) Python 3.11+ 런타임 + pipx·uv 설치(OS별 PEP668·RHEL8 3.6 회피). 라이브러리(pptx·pymupdf)는 docs-setup 담당, 본 스킬은 런타임만. 'setup-python'/'Python 설치'/'pipx·uv 설치' 또는 /banker:setup 시 사용."
+---
+
+# setup-python: Python 3.11+ 런타임 + pipx·uv 설치
+
+Claude Code·Codex 양쪽의 python 기반 도구가 딛고 서는 **인터프리터 런타임**과 `pipx`·`uv`를 설치한다.
+**경계**: 이 스킬은 런타임 자체만 다룬다. python-pptx·pymupdf 같은 문서 라이브러리는 `docs-setup`이 이 런타임 위에서 담당(별도 venv). 멱등(이미 3.11+ 있으면 skip). 답변은 한글(명령·경로는 영문).
+
+## 런타임 배선
+- **Claude Code**: `docs-setup`(python-pptx·pymupdf) 및 `serena`·`mcp-server-git`·`mcp-server-fetch` 등 `uvx` 기반 MCP가 이 위에서 동작. 전부 python 3.8+ 요구.
+- **Codex/OMX**: `basedpyright`·`ruff`(pipx 격리 설치), `lsp-mcp`(`pipx install --editable`)가 python 3.8+ 요구.
+- 즉 이 스킬이 먼저 실행되어야 `docs-setup`이나 LSP 설치 스킬이 "어떤 python을 쓸지" 고민 없이 최신 버전을 찾을 수 있다.
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+[ -f /etc/os-release ] && . /etc/os-release && echo "distro=$ID ${VERSION_ID}"
+for v in 3.13 3.12 3.11; do command -v python$v >/dev/null && echo "python$v=$(python$v --version 2>&1)"; done
+command -v python3 >/dev/null && echo "python3(default)=$(python3 --version 2>&1)" || echo "python3=미설치"
+command -v pipx >/dev/null && echo "pipx=$(pipx --version)" || echo "pipx=미설치"
+command -v uv   >/dev/null && echo "uv=$(uv --version)"     || echo "uv=미설치"
+```
+```powershell
+$PSVersionTable.PSVersion
+py -0p 2>$null                                                          # 설치된 버전 목록
+if (Get-Command pipx -ErrorAction SilentlyContinue) { pipx --version } else { "pipx: 미설치" }
+if (Get-Command uv   -ErrorAction SilentlyContinue) { uv --version }   else { "uv: 미설치" }
+```
+
+## 1. Rocky Linux 8
+```bash
+sudo dnf -y module install python311/common
+python3.11 --version
+```
+- ⚠️ **RHEL8 기본 `python3`는 3.6.** `pymupdf`/`playwright` 등은 3.8+ 휠만 배포하므로 3.6/3.7에선 설치 자체가 실패한다(sdist 빌드 시도 → 헤더 부재로 재실패).
+- 시스템 기본 `python3`를 3.11로 바꾸는 것은 **선택**이며 위험을 감수할 때만:
+  ```bash
+  # sudo alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 30
+  # sudo alternatives --set python3 /usr/bin/python3.11
+  ```
+  실행하지 않아도 무방하다. `docs-setup` 등 소비 스킬은 `python3.11`처럼 버전 명시 커맨드를 직접 탐지해 쓰므로 시스템 기본을 바꿀 필요가 없다.
+
+## 2. Ubuntu 20.04~24.04
+```bash
+. /etc/os-release
+if [ "${VERSION_ID}" = "20.04" ] || [ "${VERSION_ID}" = "22.04" ]; then
+  sudo add-apt-repository -y ppa:deadsnakes/ppa
+  sudo apt update
+  sudo apt install -y python3.11 python3.11-venv python3.11-dev
+else
+  echo "24.04+: 기본 python3(3.12)가 이미 3.11+ 충족. 별도 설치 불요"
+fi
+python3.11 --version 2>/dev/null || python3 --version
+```
+
+## 3. Debian 12 (bookworm)
+```bash
+python3 --version   # 기본 3.11.2(이미 충족)·별도 설치 불요(검증만)
+```
+
+## 4. macOS (Apple Silicon / Intel)
+```zsh
+brew install python@3.11
+```
+- **keg-only라 PATH 자동 미등록.** `brew --prefix python@3.11`로 실제 경로를 확인해 아래 공통 rc 블록에 추가해야 `python3.11` 커맨드가 잡힌다.
+
+## 5. Windows 10/11
+```powershell
+winget install --id Python.Python.3.11 -e
+py -3.11 --version
+```
+> ⚠️ **MS Store 실행 별칭**: PATH에 winget 설치본보다 `WindowsApps` 스텁이 먼저 걸리면 `python`/`python3`가 스토어로 튄다 → 설정 > 앱 > 고급 앱 설정 > 앱 실행 별칭에서 `python.exe`/`python3.exe` 끄기.
+
+## pipx·uv 공통 설치 (런타임 확보 후)
+```bash
+PY=$(command -v python3.11 || command -v python3.12 || command -v python3)
+# pipx: Debian/Ubuntu 는 apt 가 1순위. 신선 Debian12·deadsnakes python3.11·Ubuntu24.04 는 인터프리터에
+#   pip 가 미번들이라 `$PY -m pip` 가 "No module named pip" 로 실패하고 --break-system-packages 로도 안 된다.
+[ -f /etc/os-release ] && . /etc/os-release
+case "${ID:-}${ID_LIKE:-}" in
+  *debian*|*ubuntu*) sudo apt-get install -y pipx ;;                                  # python3-pip 동반, PEP668 무충돌
+  *)                 "$PY" -m pip install --user pipx \
+                       || "$PY" -m pip install --user pipx --break-system-packages ;; # RHEL8/macOS: 인터프리터에 pip 번들
+esac
+command -v pipx >/dev/null && pipx ensurepath || "$PY" -m pipx ensurepath
+# macOS 대안: brew install pipx && pipx ensurepath
+
+curl -LsSf https://astral.sh/uv/install.sh | sh     # macOS/Linux 공통, 항상 최신 fetch(버전 고정 불필요)
+
+RC_FILE="$HOME/.bashrc"   # macOS는 $HOME/.zshrc
+grep -q '### BANKER_PYTHON_BEGIN ###' "$RC_FILE" || cat >> "$RC_FILE" <<'EOF'
+
+### BANKER_PYTHON_BEGIN ###
+export PATH="$HOME/.local/bin:$PATH"
+### BANKER_PYTHON_END ###
+EOF
+source "$RC_FILE"
+```
+```powershell
+python -m pip install --user pipx
+python -m pipx ensurepath
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+## 검증 (보고 의무)
+```bash
+python3.11 --version 2>/dev/null || python3 --version
+pipx --version
+uv --version
+```
+4-field 보고: 변경(설치한 python 버전·pipx/uv·rc 마커) / Evidence(위 출력) / 검증(`--version` 전부 OK) / Unknown(PEP668·권한 문제로 일부 미설치 등, 가짜 성공 금지).
+
+## 함정
+- **PEP668 externally-managed-environment**(Ubuntu 24.04·Debian 12): 직접 `pip install`이 거부됨 → apt `pipx` 패키지 또는 `--break-system-packages`.
+- **macOS PATH 자동 미등록**: `python@3.11`은 keg-only → `brew --prefix`로 경로 확인 후 수동 추가하지 않으면 "command not found".
+- **Windows MS Store 스텁**: 앱 실행 별칭을 꺼두지 않으면 `python`이 스토어 설치 페이지로 리다이렉트.
+- **RHEL8 python3.6 잔존**: 시스템 기본을 바꾸지 않아도 소비 스킬들이 버전 명시 커맨드로 우회하므로 문제 없음.
+- **pipx vs uv 역할 혼동**: pipx=CLI 도구 격리 설치(`basedpyright`·`ruff` 등), uv=venv/패키지 고속 관리. 상호 대체가 아니라 병행 사용.
+
+ARGUMENTS: [--version <x.y>] (없으면 3.11 자동 설치)

package/skills/setup-sandbox/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: setup-sandbox
+description: "(banker) 에이전트 샌드박스 공통 기반(Linux bubblewrap+socat+sysctl userns, macOS Seatbelt, Windows AppContainer)을 OS 감지 후 설치(+rust/cargo·git safe.directory 폴드인). 'setup-sandbox'/'샌드박스 설치'/'bubblewrap 설치' 또는 /banker:setup 시 사용."
+---
+
+# setup-sandbox: 에이전트 샌드박스 설치
+
+Claude Code 의 sandboxed Bash 도구(`~/.claude/settings.json` 의 `sandbox` 설정)와 Codex/OMX 의 bwrap 기반 샌드박스는 **리눅스에서
+동일한 하부 조건**(bubblewrap·socat·unprivileged user namespace)에 의존한다. 이 스킬이 그 공통 기반을
+OS별로 설치·검증하고, 두 런타임 각각의 설정 계층(Claude=`settings.json`, Codex=`config.toml`)을 배선한다.
+부수적으로 자주 같이 필요한 **rust/cargo**, **git safe.directory**(`$team`/worktree dubious-ownership
+회피)도 폴드인한다. 설치는 **멱등**(이미 있으면 skip·검증만). 답변은 한글(기술 토큰 영문).
+
+## 런타임 배선
+- **Claude Code**: Bash 도구 샌드박스를 `~/.claude/settings.json` 의 `sandbox` 객체로 제어한다(정확한 키
+  구성은 현재 Claude Code settings 문서로 확인). **네이티브 Windows 미지원**(WSL2 안에서 실행해야 함).
+- **Codex/OMX**: `~/.codex/config.toml` 의 `sandbox_mode`/`[sandbox_workspace_write]`(Python
+  replace-or-append + TOML 검증). Windows 는 네이티브 AppContainer 로 이미 지원.
+- 리눅스 bwrap+socat 설치는 **1회로 두 런타임 모두** 혜택 - Claude·Codex 각자 따로 설치할 필요 없다.
+
+## 0. 감지 (먼저, 추정 금지)
+```bash
+echo "OS=$(uname -s)"
+[ -f /etc/os-release ] && . /etc/os-release && echo "distro=$ID ${VERSION_ID}"
+for t in bwrap socat cargo; do command -v $t >/dev/null && echo "$t=yes" || echo "$t=no"; done
+sysctl user.max_user_namespaces 2>/dev/null
+sysctl kernel.unprivileged_userns_clone 2>/dev/null
+sysctl kernel.apparmor_restrict_unprivileged_userns 2>/dev/null
+git config --global --get-all safe.directory 2>/dev/null
+[ -f ~/.codex/config.toml ] && grep -n 'sandbox_mode\|network_access' ~/.codex/config.toml
+[ -f ~/.claude/settings.json ] && grep -A3 '"sandbox"' ~/.claude/settings.json
+```
+
+## 1. Linux - bubblewrap + socat + userns sysctl
+### Rocky Linux 8 / RHEL8
+```bash
+sudo dnf -y install epel-release      # socat 등은 EPEL 필요(bubblewrap 은 보통 AppStream 에 존재)
+sudo dnf -y install bubblewrap socat
+echo 'user.max_user_namespaces=15000' | sudo tee /etc/sysctl.d/99-userns.conf
+sudo sysctl -p /etc/sysctl.d/99-userns.conf
+```
+### Ubuntu 22.04/24.04
+```bash
+sudo apt-get install -y bubblewrap socat
+echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
+sudo sysctl -p /etc/sysctl.d/99-userns.conf
+```
+24.04+ 는 AppArmor 가 bwrap 의 userns 생성을 추가로 막을 수 있다 - 먼저 확인:
+```bash
+sysctl kernel.apparmor_restrict_unprivileged_userns   # 1 이면 아래 필요, 0/키없음이면 스킵
+```
+1 이면 **범위를 좁힌 공식 방법**(권장 - bwrap 에만 허용):
+```bash
+sudo tee /etc/apparmor.d/bwrap >/dev/null <<'EOF'
+abi <abi/4.0>,
+include <tunables/global>
+
+profile bwrap /usr/bin/bwrap flags=(unconfined) {
+  userns,
+  include if exists <local/bwrap>
+}
+EOF
+sudo systemctl reload apparmor
+```
+또는 **더 넓게(구식 가이드 방식)**: `kernel.apparmor_restrict_unprivileged_userns=0` 을 같은 sysctl 파일에
+추가 - 시스템 전역으로 완화되므로 가능하면 위 프로필 방식을 우선한다.
+
+### Debian 12
+```bash
+sudo apt-get install -y bubblewrap socat
+echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-userns.conf
+sudo sysctl -p /etc/sysctl.d/99-userns.conf
+```
+
+## 2. macOS - Seatbelt(설치 불필요)
+Claude Code·Codex 모두 macOS 내장 `sandbox-exec`(Seatbelt)를 그대로 쓴다. 확인만 한다:
+```bash
+command -v sandbox-exec >/dev/null && echo "Seatbelt 내장 OK"
+```
+
+## 3. Windows - 런타임별 격리 방식이 다르다(둘 다 설치 불필요, 개념 차이만 주의)
+- **Codex**: 네이티브 AppContainer(restricted token) 로 이미 격리 지원.
+- **Claude Code**: 샌드박스가 **네이티브 Windows 를 지원하지 않는다** - WSL2 안에서 실행해야 한다(공식
+  정책). WSL2 안에서는 위 리눅스 절차(bwrap+socat)를 그대로 적용한다. WSL2 안에서도 `cmd.exe`·
+  `powershell.exe`·`/mnt/c/` 하위 바이너리는 호출 불가(호스트로 넘어가는 유닉스 소켓을 샌드박스가 차단) -
+  꼭 필요하면 `excludedCommands` 에 등록해 샌드박스 밖에서 실행한다.
+
+## 4. 폴드인 - rust/cargo
+```bash
+command -v cargo >/dev/null || curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+source "$HOME/.cargo/env" 2>/dev/null
+cargo --version
+```
+
+## 5. 폴드인 - git safe.directory ($team/worktree)
+공유 워크트리·컨테이너 등 소유자가 다른 repo 에서 git 이 "dubious ownership" 로 명령을 거부하는 문제를
+미리 막는다(OMC/OMX `$team` 병렬 워커가 특히 걸린다):
+```bash
+git config --global --add safe.directory '*'
+git config --global --get-all safe.directory
+```
+`'*'` 는 범위가 넓다 - 통제된 팀/컨테이너 환경을 전제한다(불특정 다중 사용자 공유 서버라면 특정 경로만
+등록하는 편을 고려).
+
+## 6. Claude Code 배선
+Claude Code 의 Bash 도구 샌드박스는 `~/.claude/settings.json` 의 `sandbox` 객체로 설정한다(대화형 슬래시
+커맨드가 아니라 설정·CLI 플래그 기반). 위 §1 에서 설치한 bubblewrap/socat 이 그 하부 조건이다:
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "failIfUnavailable": false
+  }
+}
+```
+- `enabled`/`failIfUnavailable` 은 확인된 키다. `sandbox` 객체는 이 외에도 `network`·`excludedCommands`·
+  `autoAllowBashIfSandboxed` 등 하위 키를 가진다 - **정확한 스키마·기본값은 반드시 현재 Claude Code
+  settings 문서(`code.claude.com/docs`)로 확인**한 뒤 적용한다(버전에 따라 키가 바뀔 수 있어 추정 금지).
+- `failIfUnavailable: true` 로 두면 의존성 누락 시 자동 폴백 없이 바로 실패한다 - 관리형 배포에만 권장.
+
+## 7. Codex 배선
+`tomllib` 는 Python **3.11+** 표준 라이브러리다 - RHEL8/Rocky8 등은 기본 `python3` 가 3.6 인 경우가
+흔하므로(예: `docs-setup` 이 다루는 것과 같은 함정) 먼저 3.11+ 인터프리터를 고른다:
+```bash
+PY="$(command -v python3.12 || command -v python3.11 || command -v python3)"
+"$PY" -c "import tomllib" 2>/dev/null || echo "⚠ tomllib 없음 - Python 3.11+ 설치 후 재시도(setup-python 참고)"
+```
+그 `$PY` 로 패치한다. `sandbox_mode` 치환은 **첫 `[` 테이블 헤더 이전(root 영역)만** 대상으로 삼아
+`[profiles.*]` 하위의 같은 이름 override(예: 프로필별 `read-only` 강제)를 절대 건드리지 않는다(멱등):
+```bash
+"$PY" <<'EOF'
+import re
+from pathlib import Path
+import tomllib
+
+CFG = Path.home() / ".codex" / "config.toml"
+CFG.parent.mkdir(parents=True, exist_ok=True)
+text = CFG.read_text(encoding="utf-8") if CFG.exists() else ""
+if text:
+    tomllib.loads(text)  # 사전 검증
+
+# root 영역 = 첫 '[' 테이블 헤더 이전까지만 - [profiles.*] 하위 동명 키는 손대지 않는다
+m = re.search(r'(?m)^\[', text)
+cut = m.start() if m else len(text)
+head, tail = text[:cut], text[cut:]
+
+if re.search(r'(?m)^sandbox_mode\s*=', head):
+    head = re.sub(r'(?m)^sandbox_mode\s*=.*$', 'sandbox_mode = "workspace-write"', head, count=1)
+else:
+    head = 'sandbox_mode = "workspace-write"\n' + head
+
+text = head + tail
+if "[sandbox_workspace_write]" not in text:
+    text += '\n[sandbox_workspace_write]\nnetwork_access = true\n'
+
+tomllib.loads(text)  # 패치 후 재검증
+CFG.write_text(text, encoding="utf-8")
+print("✓ sandbox_mode=workspace-write, network_access=true")
+EOF
+```
+
+## 검증 (보고 의무)
+```bash
+bwrap --version 2>/dev/null || echo "bwrap 없음"
+command -v socat >/dev/null && echo "socat OK" || echo "socat 없음(Claude sandbox 네트워크 프록시 실패 가능)"
+# 존재만이 아니라 실제 userns 동작까지 확인
+bwrap --unshare-user --ro-bind / / true && echo "✓ bwrap userns 동작" || echo "✗ 실패 - sysctl 재확인"
+cargo --version 2>/dev/null || echo "cargo 없음"
+git config --global --get-all safe.directory
+
+grep -n 'sandbox_mode\|network_access' ~/.codex/config.toml
+PY="$(command -v python3.12 || command -v python3.11 || command -v python3)"   # tomllib=3.11+
+"$PY" -c "import tomllib; tomllib.loads(open('$HOME/.codex/config.toml', encoding='utf-8').read()); print('✓ TOML 유효')"
+timeout 30 codex sandbox -- echo sandbox-ok    # Codex 자체 샌드박스 러너로 실제 실행 확인
+
+python3 -m json.tool ~/.claude/settings.json >/dev/null && echo "settings.json 유효"
+# Claude Code sandbox 설정은 settings.json 로 확인(위 json.tool). 실제 동작은 세션에서 Bash 도구 실행으로 관찰
+```
+4-field 보고: 변경(설치 패키지·sysctl 파일·config.toml/settings.json 변경분) / Evidence(위 출력) /
+검증(bwrap 실제 동작·`codex sandbox` 성공) / Unknown(root 권한 없어 sysctl 미적용, Claude settings.json
+`sandbox` 스키마는 문서 재확인 필요 등).
+
+## 함정
+- **sysctl 은 root 필요**: sudo 불가 환경이면 현재 값 보고 후 관리자에게 요청한다(가짜 성공 금지).
+- **EL8 커널이 오래됨**(4.18): 기본 `user.max_user_namespaces` 가 낮거나 0 인 경우가 흔하다 - 감지 없이
+  이미 충분하다고 가정하지 않는다.
+- **Ubuntu 24.04+ AppArmor**: bwrap 프로필(좁음) 또는 sysctl 전역 해제(넓음) 중 하나가 필요하다 - 프로필
+  방식을 우선한다.
+- **Windows 비대칭**: Codex 는 네이티브 AppContainer 로 되지만 **Claude Code 샌드박스는 WSL2 없이 안
+  된다** - 둘을 같은 것으로 안내하지 않는다.
+- **socat 누락**: bwrap 만 있고 socat 이 없으면 Claude 샌드박스의 네트워크 프록시 릴레이가 동작하지
+  않을 수 있다(socat 이 그 릴레이를 담당).
+- **tomllib 는 Python 3.11+ 전용**: RHEL8/Rocky8 기본 `python3`(3.6)로 그대로 돌리면
+  `ModuleNotFoundError` - 위 `$PY` 선택 스니펫을 반드시 거친다.
+- **config.toml 패치 범위**: `sandbox_mode` 치환은 첫 `[` 헤더 이전(root)만 대상이라 `[profiles.*]`
+  하위 override 는 건드리지 않는다 - 그래도 패치 후 `grep -n sandbox_mode ~/.codex/config.toml` 로
+  한 번 눈으로 확인하는 습관을 권장한다.
+- **git safe.directory `'*'` 범위**: 통제된 팀/컨테이너 환경을 전제한다 - 불특정 다중 사용자 공유 서버엔
+  과하다.
+- **rustup 은 셸 rc 를 건드린다**: 새 셸을 열거나 `source ~/.cargo/env` 해야 `cargo` 가 바로 잡힌다.
+
+ARGUMENTS: [--skip-cargo] [--skip-git-safe] (없으면 OS 감지 기반 bwrap/socat+sysctl 설치부터 Codex config 패치까지 전부 수행)

package/skills/setup-tmux/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: setup-tmux
+description: "(banker) OMC team·worktree 세션과 Codex OMX $team·HUD 가 요구하는 tmux(Windows는 psmux)를 OS 감지 후 설치·소스빌드(Rocky8 3.6a). 'setup-tmux'/'tmux 설치'/'psmux 설치' 또는 /banker:setup 시 사용."
+---
+
+# setup-tmux: tmux(Windows는 psmux) 설치
+
+Claude Code 의 OMC `team`/worktree 병렬 세션과 Codex 의 OMX `$team`/HUD 는 전부 tmux(Windows 는
+psmux) 세션 **안에서 실행되는 것을 전제**한다. 이 스킬은 OS 를 감지해 알맞은 경로로 tmux 를
+설치·검증한다. 설치는 **멱등**(이미 충족하면 skip·검증만). 답변은 한글(기술 토큰 영문).
+
+## 런타임 배선
+- **Claude Code**: OMC 의 `team`/worktree 세션(패널 분할·병렬 워커)은 tmux 안에서 실행된다.
+- **Codex**: OMX 의 `$team`/HUD 는 tmux(또는 psmux) 세션 **안에서 실행이 필수**다. 세션 밖에서
+  실행하면 `outside-tmux` surface 로 표시되고 `$team`/HUD 가 동작하지 않는다 - 에러가 두드러지지
+  않아 조용히 실패한 것처럼 보일 수 있다.
+- **공통**: worker 의 작업 디렉터리가 dubious-ownership 으로 잡히면 worktree 생성 자체가 막힌다 →
+  `git config --global --add safe.directory '*'` 를 함께 설정한다(§2).
+
+## 0. 감지 (먼저 - 추정 금지)
+```bash
+command -v tmux >/dev/null && tmux -V || echo "tmux: 미설치"
+[ -f /etc/os-release ] && . /etc/os-release && echo "distro=$ID ${VERSION_ID}"
+type -a tmux 2>/dev/null   # Rocky8: PATH 상 여러 tmux 가 있을 수 있음 - 순서 확인
+```
+Windows(PowerShell):
+```powershell
+Get-Command tmux -ErrorAction SilentlyContinue
+```
+
+## 1. OS별 설치
+
+### Rocky Linux 8 / RHEL8 - 소스빌드 필수
+시스템 기본 `tmux` 는 2.7 이며 OMX `--madmax` 모드에서 **hang** 한다(실측). EPEL 도 3.x 를 제공하지
+않는다 → **3.6a 를 소스에서 빌드**한다.
+```bash
+# 이미 3.6a+ 면 재빌드 불필요(멱등)
+/usr/local/bin/tmux -V 2>/dev/null | grep -qE '3\.[6-9]|[4-9]\.' && echo "이미 충족 - skip" || {
+  sudo dnf install -y libevent-devel ncurses-devel gcc make byacc
+  cd /tmp
+  curl -fLO https://github.com/tmux/tmux/releases/download/3.6a/tmux-3.6a.tar.gz
+  tar xzf tmux-3.6a.tar.gz && cd tmux-3.6a
+  ./configure && make && sudo make install     # /usr/local/bin/tmux 로 설치됨
+}
+```
+> **`/usr/bin/tmux`(2.7)를 지우지 않는다** - PATH 상 `/usr/local/bin` 이 먼저 오는지만 확인해
+> 우회한다(`type -a tmux` 첫 줄이 `/usr/local/bin/tmux` 인지 확인).
+> ⚠️ 3.6a 는 이 시점의 버전 고정값이다. 최신 안정판은 https://github.com/tmux/tmux/releases 에서
+> 재확인 후 필요하면 `TMUX_VER` 를 바꿔 교체한다.
+
+### Ubuntu / Debian - apt 기본으로 충분
+```bash
+sudo apt-get update && sudo apt-get install -y tmux
+tmux -V
+```
+Ubuntu 22.04(3.2a)·24.04(3.4)·Debian 12(3.3a) 모두 OMX 요구 버전을 충족한다 - 소스빌드 불필요.
+
+### macOS
+```bash
+brew install tmux
+```
+
+### Windows - psmux
+Windows 에는 tmux 가 없어 호환 레이어인 psmux 를 쓴다.
+```powershell
+winget install --id marlocarlo.psmux -e
+tmux -V      # psmux 가 tmux 커맨드 alias 를 자동 등록
+```
+- psmux 는 tmux 명령을 상당 부분 흉내내지만 **100% 호환은 아니다** - 이상 동작 시 psmux 자체
+  버전과 재현 여부를 먼저 의심한다.
+- `$team`/HUD 를 쓰려면 psmux 세션 **안에서** `omx` 를 실행해야 한다: `tmux new-session -s codex`
+  로 세션을 연 뒤 그 안에서 `omx --madmax --xhigh`.
+
+## 2. 공통 - dubious-ownership 가드
+```bash
+git config --global --add safe.directory '*'
+```
+worker 가 `/tmp` 등 소유권이 모호한 경로에서 실행되면 이 설정 없이는 worktree 생성이 막힌다.
+
+## 검증 (보고 의무)
+```bash
+tmux -V                                             # 존재 확인 (>=3.2; Rocky8 은 3.6a)
+type -a tmux 2>/dev/null | head -1                   # Rocky8: 첫 줄이 /usr/local/bin/tmux 여야 함
+tmux new-session -d -s _t && tmux kill-session -t _t && echo "tmux 실동작 OK"
+git config --global --get safe.directory
+```
+Windows: `tmux -V`(psmux 버전) + `Get-Command tmux`.
+
+4-field 보고: 변경(설치 방법·버전·safe.directory 여부) / Evidence(위 출력) / 검증(new-session→
+kill-session 성공) / Unknown(sudo 권한 없어 소스빌드 불가 등).
+
+## 함정
+- **Rocky8 빌드 의존성 누락**: `libevent-devel`/`ncurses-devel`/`byacc` 없이 `./configure` 하면
+  실패 → 위 dnf 목록을 먼저 설치.
+- **PATH 우선순위**: `/usr/local/bin/tmux`(3.6a)가 `/usr/bin/tmux`(2.7)보다 먼저 잡히지 않으면
+  여전히 구버전이 실행된다 → `type -a tmux` 로 순서 확인, 필요하면 `~/.bashrc` PATH 앞쪽에 추가.
+- **psmux 비호환**: 일부 tmux 전용 스크립트·키바인딩이 psmux 에서 다르게 동작할 수 있다 - 완전한
+  대체품이 아니라는 전제로 접근.
+- **세션 밖 실행**: tmux/psmux 세션 밖에서 `omx --madmax`/`$team`/HUD 를 실행하면 `outside-tmux`
+  로 표시되고 기능이 동작하지 않는다 - 실패가 눈에 띄지 않을 수 있으므로 항상 세션 안에서
+  실행했는지 먼저 확인한다.
+- **dubious-ownership 누락**: `safe.directory` 미설정 시 worker 가 조용히 worktree 를 못 만들고
+  idle 상태로만 보일 수 있다.
+
+ARGUMENTS: 없음 (OS 자동감지 후 설치 - Rocky8 은 소스빌드, 그 외는 패키지매니저)