leerness 1.9.31 → 1.9.33

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 1.9.33 — 2026-05-15
+
+**npx 캐시 함정 방지 — install 시 stale 버전 자동 경고 + 해결 안내**.
+
+### 배경
+사용자가 `npx leerness init`(@latest 없이)을 실행하면 npm/npx의 로컬 캐시에 있는 옛 버전이 무한히 재사용되는 함정이 있음. 1.9.32 publish 후에도 사용자 PC에서 1.9.21이 실행되는 사례 확인.
+
+### Added
+
+- **`_warnIfStale()` 헬퍼**: `install()` 진입 시 자동 호출.
+  - npm registry latest 비교 (`fetchNpmLatest` + 24h cache 재사용)
+  - 현재 실행 중인 VERSION이 registry latest보다 옛날이면 ⚠ 노랑색 경고 박스 출력
+  - 해결 명령 2가지 안내: `npx --yes clear-npx-cache && npx leerness@latest init .` 또는 `npm i -g leerness@latest`
+  - **init 자체는 계속 진행** (경고만 띄움 — 강제 차단 X)
+- **`--no-stale-check`** 플래그 + **`LEERNESS_NO_STALE_CHECK=1`** env 변수: 경고 스킵
+- **offline + 캐시 없음**: 비교 스킵 (네트워크 차단 환경 안전)
+- **offline + 캐시 fresh**: 캐시값으로 비교 (e2e 등 CI 환경에서도 동작)
+
+### Policy
+- ❌ 사용자 init 차단 안 함 (경고만, init은 계속 진행)
+- ✅ 24h 캐시로 매 init마다 npm view 호출 안 함 (cold-start만 12s timeout)
+- ✅ 네트워크 실패 시 silently skip — init 흐름 끊지 않음
+- ✅ `--no-stale-check`/env로 끄기 가능 (CI 친화)
+
+### 실측 (이번 라운드)
+- 사용자 PC: `npx leerness init` → 1.9.21 실행됨 (npm latest=1.9.32) — 1.9.33부터 install 시 즉시 경고
+- e2e: 153/153 PASS (1.9.32 151 + stale 경고/스킵 2)
+
+## 1.9.32 — 2026-05-15
+
+**ASCII 배너 + `leerness setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도**.
+
+### Added
+
+- **ASCII 배너 (`_banner()`)**: `leerness init` 시 자동 출력. `--version --banner`로도 호출 가능. `LEERNESS_NO_BANNER=1` 또는 콘솔 폭 <70칸이면 자동 스킵.
+  - `LEERNESS` 8글자 ANSI 시안+볼드 색상 + 박스 + 빠른 시작 4줄.
+- **`leerness setup-agents [path]`** (신규 명령): 외부 AI CLI 4종 (claude/codex/gemini/copilot) 인터랙티브 활성화.
+  - 각 CLI별: 설치 상태(🟢/⚪) + 활성 상태(🟢/🟡) 표시 → 사용자 yes/no → `.env`의 `LEERNESS_ENABLE_*` 자동 upsert.
+  - **미설치 CLI 자동 설치 시도**: 사용자 동의 후 `npm i -g @anthropic-ai/claude-code`, `npm i -g @openai/codex`, `npm i -g @google/gemini-cli`, `gh extension install github/gh-copilot` 실행.
+  - 설치 후 PATH 재확인 → 안 보이면 새 셸 안내.
+- **`init` 후 자동 prompt**: `leerness init`이 끝나면 TTY일 때 "외부 AI CLI 설정?" 질문 → yes 시 `setupAgentsCmd` 호출.
+  - `--no-setup-agents` 또는 `--yes`로 스킵 가능.
+- **`EXTERNAL_AGENTS`에 `installCmd` + `installHint` 필드 추가**: 자동 설치 시 사용.
+- **`_prompt()` / `_confirm()` / `_upsertEnvLine()` 헬퍼**: TTY 한정 readline 기반, 비대화형(--yes/CI/non-TTY)에선 안전 fallback.
+
+### Policy
+- ❌ 비-TTY/CI 환경에선 prompt 자동 스킵 (default 동작 유지)
+- ❌ 자동 설치는 사용자 명시적 yes 후에만 (--yes 시에도 prompt 스킵하므로 자동 설치 안 됨)
+- ✅ `.env` upsert는 idempotent (이미 키가 있으면 값 교체만)
+- ✅ `init --yes` + `setup-agents`로 비대화형 워크플로도 안내 표시만 (변경 없음)
+
+### 실측 (이번 라운드)
+- 신규 sub-project 3종 (rpg-craft 20/20, rpg-achievements 22/22, rpg-instance 20/20) — sub-agent 3 동시
+- e2e: 151/151 PASS (1.9.31 146 + 1.9.32 5)
+- 배너 ANSI 시각 검증 OK / 콘솔 폭 <70칸 시 1줄 폴백 / `LEERNESS_NO_BANNER=1` 스킵
+
 ## 1.9.31 — 2026-05-15
 
 **`leerness agents quota` — 외부 AI CLI 사용량/한도 추정 + provider 대시보드 안내**.

package/README.md

@@ -2,7 +2,24 @@
 
 > 한국어 우선 AI 개발 하네스. 멀티 에이전트 오케스트레이션 · 자동 검수 · 워크스페이스 가시성 · Ollama opt-in 통합.
 
-[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.31-green)]() [![tests](https://img.shields.io/badge/e2e-146%2F146-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
+[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.33-green)]() [![tests](https://img.shields.io/badge/e2e-153%2F153-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
+
+```
+  ╔══════════════════════════════════════════════════════════════╗
+  ║                                                              ║
+  ║  ██╗     ███████╗███████╗██████╗ ███╗   ██╗███████╗███████╗  ║
+  ║  ██║     ██╔════╝██╔════╝██╔══██╗████╗  ██║██╔════╝██╔════╝  ║
+  ║  ██║     █████╗  █████╗  ██████╔╝██╔██╗ ██║█████╗  ███████╗  ║
+  ║  ██║     ██╔══╝  ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ╚════██║  ║
+  ║  ███████╗███████╗███████╗██║  ██║██║ ╚████║███████╗███████║  ║
+  ║  ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝  ║
+  ║                                                              ║
+  ║  v1.9.32   Korean-first AI Development Harness              ║
+  ║  verify · reuse-map · handoff · agents · orchestrate         ║
+  ║                                                              ║
+  ╚══════════════════════════════════════════════════════════════╝
+  한국어 우선 AI 개발 하네스 — verify · reuse-map · handoff · agents
+```
 
 ## ⚙️ 설치 (Install)
 
@@ -21,6 +38,88 @@ npm i --save-dev leerness && npx leerness handoff .
 
 > npmjs.com의 `npm i leerness`는 라이브러리 import용. CLI 명령(`leerness ...`) 직접 호출은 위 3가지 중 하나 필요.
 
+### 🚨 npx 캐시 함정 주의 (1.9.33부터 자동 경고)
+
+**`@latest` 없이 `npx leerness init`만 입력하면 PC에 캐시된 옛 버전이 무한히 재사용됩니다.**
+
+```bash
+# ❌ 위험 — 캐시된 옛 버전 실행될 수 있음
+npx leerness init .
+
+# ✅ 안전 — 항상 최신 받음
+npx leerness@latest init .
+
+# ✅ 캐시가 의심스러우면 비우고 다시
+npx --yes clear-npx-cache
+npx --yes leerness@latest init .
+```
+
+**1.9.33부터** `leerness init` 실행 시 npm registry latest와 자동 비교하여, **옛 버전이 실행 중이면 즉시 경고를 출력**합니다:
+
+```
+  ⚠  옛 버전이 실행 중입니다 — v1.9.21 → v1.9.33 (npm 최신)
+
+     npm registry latest: v1.9.33
+     이 CLI가 실행한 버전: v1.9.21 (npx 캐시 또는 글로벌 설치 stale)
+
+     해결 — 둘 중 하나 실행 후 다시 시도:
+       npx --yes clear-npx-cache && npx leerness@latest init .
+       npm i -g leerness@latest  →  leerness init .
+```
+
+경고 끄기: `--no-stale-check` 또는 `LEERNESS_NO_STALE_CHECK=1`.
+
+### 🎨 1.9.32 설치 경험
+
+`leerness init`을 실행하면 **LEERNESS ASCII 배너 + 빠른 시작 가이드 + sub-agent CLI 설정 prompt**가 자동으로 표시됩니다.
+
+```
+  ╔══════════════════════════════════════════════════════════════╗
+  ║  ██╗     ███████╗███████╗██████╗ ███╗   ██╗███████╗███████╗  ║
+  ║  ██║     ██╔════╝██╔════╝██╔══██╗████╗  ██║██╔════╝██╔════╝  ║
+  ║  ██║     █████╗  █████╗  ██████╔╝██╔██╗ ██║█████╗  ███████╗  ║
+  ║  ██║     ██╔══╝  ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ╚════██║  ║
+  ║  ███████╗███████╗███████╗██║  ██║██║ ╚████║███████╗███████║  ║
+  ║  ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝  ║
+  ║  v1.9.32   Korean-first AI Development Harness              ║
+  ╚══════════════════════════════════════════════════════════════╝
+
+💡 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하시겠습니까?
+   지금 설정할까요? (나중에 `leerness setup-agents`로도 가능) (Y/n): y
+
+▸ claude — Anthropic Claude Code CLI
+  설치 상태: 🟢 설치됨 (1.0.x)
+  활성 상태: 🟡 LEERNESS_ENABLE_CLAUDE=0 또는 미설정
+  claude를 sub-agent로 활성화하시겠습니까? (Y/n): y
+  ✓ LEERNESS_ENABLE_CLAUDE=1 (활성)
+
+▸ codex — OpenAI Codex CLI (격리 sandbox)
+  설치 상태: ⚪ 미설치
+  활성 상태: 🟡
+  codex를 sub-agent로 활성화하시겠습니까? (y/N): y
+  ✓ LEERNESS_ENABLE_CODEX=1 (활성)
+  ⚠ codex이(가) 설치되어 있지 않습니다.
+     설치 명령: npm i -g @openai/codex
+     상세 안내: https://github.com/openai/codex
+  지금 자동 설치를 시도할까요? (y/N): y
+  ▶ 실행: npm i -g @openai/codex
+  ✓ 설치 성공 — 재확인: codex --version
+  🟢 codex 설치 확인 (0.x.x)
+```
+
+**스킵 옵션** (CI/자동화):
+- `leerness init --yes` — 모든 prompt 스킵 (기존 .env 유지)
+- `leerness init --no-setup-agents` — setup만 스킵
+- `LEERNESS_NO_BANNER=1` — ASCII 배너 스킵
+- `LEERNESS_NO_PROMPT=1` — readline prompt 강제 비활성화
+
+**나중에 재실행**:
+```bash
+leerness setup-agents .           # 인터랙티브 재설정
+leerness agents list              # 현재 상태 확인
+leerness agents quota             # 사용량 추정 (1.9.31)
+```
+
 ---
 
 **leerness가 해결하는 것**
@@ -102,6 +201,7 @@ leerness persona add my-domain                              # 사용자 정의
 leerness agents list                                        # 1.9.30 외부 AI CLI 상태표
 leerness agents quota                                       # 1.9.31 CLI별 사용량/한도 추정
 leerness agents dispatch "<task>" --to gemini               # 1.9.30 sub-agent 명령 생성
+leerness setup-agents                                       # 1.9.32 인터랙티브 CLI 설정 + 자동 설치 시도
 ```
 
 ### 워크스페이스 (멀티 프로젝트)
@@ -221,6 +321,7 @@ leerness orchestrate "복잡한 기능" --agents 20
 | `agents list/check` | 4 CLI(claude/codex/gemini/copilot) 활성/설치 상태표 (env + PATH 검증) | 1.9.30 |
 | `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 (자동 호출 금지) | 1.9.30 |
 | `agents quota` | provider별 사용량/한도 추정 + 대시보드 안내 | 1.9.31 |
+| `setup-agents` | 인터랙티브 CLI 활성화 + 미설치 자동 설치 시도 (.env upsert) | 1.9.32 |
 
 ---
 
@@ -301,11 +402,18 @@ leerness persona add my-domain   # .harness/personas/my-domain.md 템플릿 생
 
 ---
 
-## 🤖 외부 AI CLI 오케스트레이션 (1.9.30 / 1.9.31)
+## 🤖 외부 AI CLI 오케스트레이션 (1.9.30 / 1.9.31 / 1.9.32)
 
 claude/codex/gemini/copilot CLI들을 sub-agent로 명시적 활용. **자동 호출 절대 금지** — 환경변수 활성화 + PATH 존재 둘 다 충족 시에만 ready.
 
-### 활성화 (`.env`)
+### 활성화 — 자동 (1.9.32 권장)
+```bash
+leerness setup-agents .       # 인터랙티브: 각 CLI별 yes/no + 미설치 자동 설치 시도
+                              # → .env에 LEERNESS_ENABLE_* 자동 기록
+                              # → 미설치 CLI는 npm i -g / gh extension install 실행 (사용자 동의 시)
+```
+
+### 활성화 — 수동 (`.env` 직접 편집)
 ```bash
 LEERNESS_ENABLE_CLAUDE=1     # Anthropic Claude Code CLI
 LEERNESS_ENABLE_CODEX=1      # OpenAI Codex CLI (격리 sandbox)
@@ -318,8 +426,17 @@ LEERNESS_ENABLE_COPILOT=1    # GitHub Copilot CLI (gh copilot)
 leerness agents list                              # 4 CLI 상태표 (env + PATH + 버전)
 leerness agents quota                             # provider별 사용량/한도 추정 (1.9.31)
 leerness agents dispatch "<task>" --to gemini     # ready CLI에 명령 자동 생성
+leerness setup-agents                             # 1.9.32 인터랙티브 재설정
 ```
 
+### 자동 설치 명령 (1.9.32 setup-agents가 사용)
+| CLI | install 명령 | 안내 |
+|---|---|---|
+| claude | `npm i -g @anthropic-ai/claude-code` | https://docs.anthropic.com/en/docs/claude-code/setup |
+| codex | `npm i -g @openai/codex` | https://github.com/openai/codex |
+| gemini | `npm i -g @google/gemini-cli` | https://github.com/google-gemini/gemini-cli |
+| copilot | `gh extension install github/gh-copilot` | https://github.com/github/gh-copilot (gh CLI 선행 필요) |
+
 ### quota 안내 (1.9.31)
 | CLI | 추정 | 안내 |
 |---|---|---|
@@ -376,6 +493,9 @@ leerness skill consolidate
 | **`LEERNESS_ENABLE_CODEX`** | **1.9.30 — Codex CLI 활성** (=1) |
 | **`LEERNESS_ENABLE_GEMINI`** | **1.9.30 — Gemini CLI 활성** (=1) |
 | **`LEERNESS_ENABLE_COPILOT`** | **1.9.30 — gh copilot 활성** (=1) |
+| `LEERNESS_NO_BANNER` | 1.9.32 — init 시 ASCII 배너 스킵 (=1) |
+| `LEERNESS_NO_PROMPT` | 1.9.32 — readline 인터랙티브 prompt 강제 비활성 (=1) |
+| `LEERNESS_NO_STALE_CHECK` | **1.9.33 — npx 캐시 옛 버전 경고 끄기** (=1) |
 
 ---
 
@@ -415,12 +535,14 @@ A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)
 npm test     # = node ./scripts/e2e.js
 ```
 
-**146/146 시나리오** 통과 (1.9.7~1.9.31 회귀 + 신규 검증).
+**153/153 시나리오** 통과 (1.9.7~1.9.33 회귀 + 신규 검증).
 
 ---
 
 ## 📜 변경 이력 (최근)
 
+- **1.9.33** — `_warnIfStale()` — `npx leerness init` 시 옛 버전 자동 경고 + 해결 안내 (clear-npx-cache / @latest).
+- **1.9.32** — ASCII 배너 + `leerness setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도. `init` 시 자동 prompt.
 - **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정 + 대시보드 안내). 멀티 에이전트 분배 신호.
 - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책 + `leerness agents list/check/dispatch`
 - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배)

package/bin/harness.js

@@ -6,7 +6,7 @@ const path = require('path');
 const cp = require('child_process');
 const readline = require('readline');
 
-const VERSION = '1.9.31';
+const VERSION = '1.9.33';
 const MARK = '<!-- leerness:managed -->';
 const README_START = '<!-- leerness:project-readme:start -->';
 const README_END = '<!-- leerness:project-readme:end -->';
@@ -386,10 +386,16 @@ async function resolveInstallOptions(root, opts = {}) {
 
 async function install(root, opts = {}) {
   root = absRoot(root); mkdirp(root);
+  // 1.9.32: init 시 ASCII 배너 + 빠른 시작 가이드 (migrate는 quiet)
+  if (!opts.migration && !has('--no-banner')) _banner({ quickStart: !opts.dry });
+  // 1.9.33: npx 캐시로 옛 버전이 실행될 때 경고 (migrate/--no-stale-check 시 스킵)
+  if (!opts.migration && !has('--no-stale-check') && !opts.nonInteractive) {
+    try { await _warnIfStale(root); } catch {}
+  }
   const resolved = await resolveInstallOptions(root, opts);
   const lang = resolved.lang;
   const skills = resolved.skills;
-  log(`\nLeerness v${VERSION}`);
+  log(`Leerness v${VERSION}`);
   log(`Target: ${root}`);
   log(`Language: ${lang}`);
   log(`Skills: ${skills.length ? skills.join(', ') : 'none'}`);
@@ -471,6 +477,21 @@ async function install(root, opts = {}) {
     if (!has('--no-auto-roadmap')) {
       try { _autoRoadmap(root, 'install'); } catch (e) { warn('auto-roadmap 실패: ' + (e && e.message)); }
     }
+    // 1.9.32: init 시 외부 AI CLI 설정 prompt (TTY + 신규 init + --no-setup-agents 미지정)
+    const isFreshInit = !opts.migration && !opts.force;
+    const skipSetup = has('--no-setup-agents') || has('--yes') || has('-y');
+    if (isFreshInit && process.stdin.isTTY && !skipSetup) {
+      try {
+        log('');
+        log('💡 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하시겠습니까?');
+        const wantSetup = await _confirm('   지금 설정할까요? (나중에 `leerness setup-agents`로도 가능)', true);
+        if (wantSetup) {
+          await setupAgentsCmd(root);
+        } else {
+          log('   → 나중에 `leerness setup-agents .` 명령으로 설정 가능');
+        }
+      } catch (e) { warn('setup-agents skipped: ' + (e && e.message)); }
+    }
   }
 }
 
@@ -2269,11 +2290,16 @@ function _resolvePersona(root, id) {
 
 // 1.9.30: 외부 AI CLI 오케스트레이션 — claude/codex/gemini/copilot 가용성 + 활성화 체크
 // 사용자 정책: 환경변수로 활성화 명시 + 실제 PATH 존재 확인 + 메인이 sub-agent 분배 시 참조
+// 1.9.32: installCmd 추가 — setup-agents 시 자동 설치 시도 가능
 const EXTERNAL_AGENTS = [
-  { id: 'claude',  bin: 'claude',  envFlag: 'LEERNESS_ENABLE_CLAUDE',  versionArgs: ['--version'], desc: 'Anthropic Claude Code CLI' },
-  { id: 'codex',   bin: 'codex',   envFlag: 'LEERNESS_ENABLE_CODEX',   versionArgs: ['--version'], desc: 'OpenAI Codex CLI (격리 sandbox)' },
-  { id: 'gemini',  bin: 'gemini',  envFlag: 'LEERNESS_ENABLE_GEMINI',  versionArgs: ['--version'], desc: 'Google Gemini CLI (--yolo 모드 워크스페이스 직접 수정 가능)' },
-  { id: 'copilot', bin: 'gh',      envFlag: 'LEERNESS_ENABLE_COPILOT', versionArgs: ['copilot', '--version'], desc: 'GitHub Copilot CLI (gh copilot)' }
+  { id: 'claude',  bin: 'claude',  envFlag: 'LEERNESS_ENABLE_CLAUDE',  versionArgs: ['--version'], desc: 'Anthropic Claude Code CLI',
+    installCmd: 'npm i -g @anthropic-ai/claude-code', installHint: 'https://docs.anthropic.com/en/docs/claude-code/setup' },
+  { id: 'codex',   bin: 'codex',   envFlag: 'LEERNESS_ENABLE_CODEX',   versionArgs: ['--version'], desc: 'OpenAI Codex CLI (격리 sandbox)',
+    installCmd: 'npm i -g @openai/codex', installHint: 'https://github.com/openai/codex' },
+  { id: 'gemini',  bin: 'gemini',  envFlag: 'LEERNESS_ENABLE_GEMINI',  versionArgs: ['--version'], desc: 'Google Gemini CLI (--yolo 모드 워크스페이스 직접 수정 가능)',
+    installCmd: 'npm i -g @google/gemini-cli', installHint: 'https://github.com/google-gemini/gemini-cli' },
+  { id: 'copilot', bin: 'gh',      envFlag: 'LEERNESS_ENABLE_COPILOT', versionArgs: ['copilot', '--version'], desc: 'GitHub Copilot CLI (gh copilot)',
+    installCmd: 'gh extension install github/gh-copilot', installHint: 'https://github.com/github/gh-copilot (gh CLI 선행 설치 필요)' }
 ];
 
 function _checkAgent(agent, opts = {}) {
@@ -2298,6 +2324,211 @@ function _checkAgent(agent, opts = {}) {
   };
 }
 
+// 1.9.33: npx 캐시 함정 방지 — install 진입 시 npm latest와 비교, stale이면 경고
+async function _warnIfStale(root, opts = {}) {
+  if (process.env.LEERNESS_NO_STALE_CHECK === '1') return null;
+  const offline = process.env.LEERNESS_OFFLINE === '1';
+  // 24h 캐시: .harness/cache/update-check.json 재사용 — 캐시 fresh면 OFFLINE이어도 비교는 수행
+  try {
+    let latest = null;
+    const cached = readUpdateCache(root);
+    if (cacheFresh(cached, 24) && cached.nextLeerness) {
+      latest = cached.nextLeerness;
+    } else if (!offline) {
+      // 캐시 없음 + 온라인 → npm view 호출 (timeout 8초 — 네트워크 끊겼어도 init 진행 차단 X)
+      latest = await Promise.race([
+        fetchNpmLatest('leerness'),
+        new Promise(resolve => setTimeout(() => resolve(null), 8000))
+      ]);
+      if (latest) {
+        try { writeUpdateCache(root, { nextLeerness: latest, runningCli: VERSION }); } catch {}
+      }
+    }
+    // offline + 캐시 없으면 비교 스킵 (네트워크 차단 환경)
+    if (!latest) return null;
+    if (compareVer(latest, VERSION) > 0) {
+      // 옛 버전이 실행 중. ANSI 노란/빨강.
+      const isTty = process.stdout && process.stdout.isTTY;
+      const C = isTty ? { y: s => `\x1b[33m${s}\x1b[0m`, r: s => `\x1b[31m${s}\x1b[0m`, b: s => `\x1b[1m${s}\x1b[0m`, d: s => `\x1b[2m${s}\x1b[0m` }
+                      : { y: s => s, r: s => s, b: s => s, d: s => s };
+      log('');
+      log(C.y('  ⚠  ') + C.b(C.r(`옛 버전이 실행 중입니다 — v${VERSION} → v${latest} (npm 최신)`)));
+      log('');
+      log(C.d('     npm registry latest: ') + C.b(`v${latest}`));
+      log(C.d('     이 CLI가 실행한 버전: ') + C.b(`v${VERSION}`) + C.d(' (npx 캐시 또는 글로벌 설치 stale)'));
+      log('');
+      log(C.d('     해결 — 둘 중 하나 실행 후 다시 시도:'));
+      log('       ' + C.b('npx --yes clear-npx-cache && npx leerness@latest init .'));
+      log('       ' + C.b('npm i -g leerness@latest  →  leerness init .'));
+      log('');
+      log(C.d('     (이 경고는 LEERNESS_NO_STALE_CHECK=1 또는 --no-stale-check로 끌 수 있습니다)'));
+      log('');
+      return { stale: true, current: VERSION, latest };
+    }
+    return { stale: false, current: VERSION, latest };
+  } catch (e) {
+    // 어떤 이유로든 실패해도 init 진행 차단 X
+    return null;
+  }
+}
+
+// 1.9.32: ASCII 배너 — init/version 시 출력
+function _banner(opts = {}) {
+  const v = `v${VERSION}`;
+  // 사용자 콘솔이 너무 좁을 때(<70) 또는 LEERNESS_NO_BANNER=1이면 스킵
+  const cols = process.stdout && process.stdout.columns ? process.stdout.columns : 80;
+  if (process.env.LEERNESS_NO_BANNER === '1') return;
+  if (cols < 70) {
+    log(`Leerness ${v}  —  한국어 우선 AI 개발 하네스`);
+    return;
+  }
+  // ANSI 색상 (TTY일 때만)
+  const isTty = process.stdout && process.stdout.isTTY;
+  const C = isTty ? {
+    cyan: s => `\x1b[36m${s}\x1b[0m`, dim: s => `\x1b[2m${s}\x1b[0m`,
+    bold: s => `\x1b[1m${s}\x1b[0m`, green: s => `\x1b[32m${s}\x1b[0m`
+  } : { cyan: s => s, dim: s => s, bold: s => s, green: s => s };
+  // 박스 안쪽 너비 60칸 고정 (좌측 2칸 들여쓰기 포함 전체 64칸)
+  const lines = [
+    '',
+    C.cyan('  ╔══════════════════════════════════════════════════════════════╗'),
+    C.cyan('  ║                                                              ║'),
+    C.cyan('  ║  ') + C.bold('██╗     ███████╗███████╗██████╗ ███╗   ██╗███████╗███████╗') + C.cyan('  ║'),
+    C.cyan('  ║  ') + C.bold('██║     ██╔════╝██╔════╝██╔══██╗████╗  ██║██╔════╝██╔════╝') + C.cyan('  ║'),
+    C.cyan('  ║  ') + C.bold('██║     █████╗  █████╗  ██████╔╝██╔██╗ ██║█████╗  ███████╗') + C.cyan('  ║'),
+    C.cyan('  ║  ') + C.bold('██║     ██╔══╝  ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ╚════██║') + C.cyan('  ║'),
+    C.cyan('  ║  ') + C.bold('███████╗███████╗███████╗██║  ██║██║ ╚████║███████╗███████║') + C.cyan('  ║'),
+    C.cyan('  ║  ') + C.bold('╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝') + C.cyan('  ║'),
+    C.cyan('  ║                                                              ║'),
+    // ASCII-only 라인은 정확히 60칸 (좌2 + 본문56 + 우2)
+    C.cyan('  ║  ') + C.green(`${v.padEnd(10)}`) + C.dim('Korean-first AI Development Harness') + C.cyan('              ║'),
+    C.cyan('  ║  ') + C.dim('verify · reuse-map · handoff · agents · orchestrate') + C.cyan('         ║'),
+    C.cyan('  ║                                                              ║'),
+    C.cyan('  ╚══════════════════════════════════════════════════════════════╝'),
+    '  ' + C.dim('한국어 우선 AI 개발 하네스 — verify · reuse-map · handoff · agents'),
+    ''
+  ];
+  for (const ln of lines) log(ln);
+  if (opts.quickStart) {
+    log(C.dim('  빠른 시작:'));
+    log(C.dim('    npx leerness@latest init .                          # 신규 프로젝트'));
+    log(C.dim('    npx leerness@latest setup-agents .                  # 외부 AI CLI 설정'));
+    log(C.dim('    npx leerness handoff .                              # 컨텍스트 적재'));
+    log(C.dim('    npx leerness verify-claim T-0001 --run-tests        # 자동 검증'));
+    log('');
+  }
+}
+
+// 1.9.32: TTY 한정 readline async prompt — 비대화형(npx CI, --yes)에선 default 반환
+function _prompt(question, defaultVal = '') {
+  return new Promise(resolve => {
+    if (!process.stdin.isTTY || process.env.LEERNESS_NO_PROMPT === '1' || has('--yes') || has('-y')) {
+      return resolve(defaultVal);
+    }
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const q = defaultVal ? `${question} [${defaultVal}]: ` : `${question}: `;
+    rl.question(q, ans => {
+      rl.close();
+      resolve((ans || '').trim() || defaultVal);
+    });
+  });
+}
+
+// 1.9.32: yes/no prompt — y/yes/예/네/1 → true, n/no/아니오/0/공백 → false
+async function _confirm(question, defaultYes = false) {
+  const def = defaultYes ? 'Y/n' : 'y/N';
+  const ans = await _prompt(`${question} (${def})`, defaultYes ? 'y' : 'n');
+  return /^(y|yes|예|네|ㅇ|1|true)$/i.test(ans.trim());
+}
+
+// 1.9.32: .env 파일에 KEY=value 라인 누적/갱신 (이미 키가 있으면 값 교체, 없으면 append)
+function _upsertEnvLine(envPath, key, value) {
+  let body = exists(envPath) ? read(envPath) : '';
+  const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}=.*$`, 'm');
+  const line = `${key}=${value}`;
+  if (re.test(body)) body = body.replace(re, line);
+  else body = (body && !body.endsWith('\n') ? body + '\n' : body) + line + '\n';
+  writeUtf8(envPath, body);
+}
+
+// 1.9.32: 외부 AI CLI 자동 설치 시도 — child_process.spawnSync로 installCmd 실행
+function _tryInstallAgent(agent) {
+  if (!agent.installCmd) return { ok: false, message: 'installCmd 정의 없음' };
+  log(`  ▶ 실행: ${agent.installCmd}`);
+  const parts = agent.installCmd.split(/\s+/);
+  const r = cp.spawnSync(parts[0], parts.slice(1), { encoding: 'utf8', timeout: 120000, shell: true, stdio: 'inherit' });
+  if (r.status === 0) return { ok: true, message: '설치 성공' };
+  return { ok: false, message: `exit ${r.status}` + (r.error ? ` (${r.error.code || r.error.message})` : '') };
+}
+
+// 1.9.32: setup-agents 워크플로 — init 직후 또는 단독 명령
+async function setupAgentsCmd(root, opts = {}) {
+  root = absRoot(root || process.cwd());
+  _loadEnvFile(root);
+  _loadEnvFile(path.join(root, '..'));
+  const envPath = path.join(root, '.env');
+
+  log('');
+  log('# 외부 AI CLI 설정 (1.9.32)');
+  log('메인 에이전트가 작업을 분배할 sub-agent 후보를 선택하세요.');
+  log('각 CLI는 *환경변수 활성화 + PATH 존재* 둘 다 충족할 때 ready 상태가 됩니다.');
+  log('');
+
+  // 비대화형(--yes 또는 비-TTY)이면 모든 CLI를 기존 값 유지 + 안내만
+  const interactive = !!process.stdin.isTTY && !has('--yes') && !has('-y') && process.env.LEERNESS_NO_PROMPT !== '1';
+  if (!interactive) {
+    log('  비대화형 모드 — 환경변수는 변경하지 않습니다. 수동 편집:');
+    log(`    ${envPath}`);
+    log('  활성 상태 확인: leerness agents list');
+    return;
+  }
+
+  for (const agent of EXTERNAL_AGENTS) {
+    const status = _checkAgent(agent);
+    const isReady = status.installed && status.enabled;
+    log(`---`);
+    log(`▸ ${agent.id} — ${agent.desc}`);
+    log(`  설치 상태: ${status.installed ? '🟢 설치됨 (' + (status.version || '?') + ')' : '⚪ 미설치'}`);
+    log(`  활성 상태: ${status.enabled ? '🟢 ' + agent.envFlag + '=1' : '🟡 ' + agent.envFlag + '=0 또는 미설정'}`);
+
+    const wantEnable = await _confirm(`  ${agent.id}를 sub-agent로 활성화하시겠습니까?`, isReady || agent.id === 'claude');
+    if (!wantEnable) {
+      _upsertEnvLine(envPath, agent.envFlag, '0');
+      log(`  ✗ ${agent.envFlag}=0 (비활성)`);
+      continue;
+    }
+    _upsertEnvLine(envPath, agent.envFlag, '1');
+    log(`  ✓ ${agent.envFlag}=1 (활성)`);
+
+    if (!status.installed) {
+      log(`  ⚠ ${agent.bin}이(가) 설치되어 있지 않습니다.`);
+      log(`     설치 명령: ${agent.installCmd}`);
+      log(`     상세 안내: ${agent.installHint}`);
+      const doInstall = await _confirm(`  지금 자동 설치를 시도할까요?`, false);
+      if (doInstall) {
+        const r = _tryInstallAgent(agent);
+        if (r.ok) {
+          log(`  ✓ 설치 성공 — 재확인: ${agent.bin} ${agent.versionArgs.join(' ')}`);
+          const after = _checkAgent(agent);
+          if (after.installed) log(`  🟢 ${agent.id} 설치 확인 (${after.version || '?'})`);
+          else log(`  ⚠ 설치 후에도 PATH에서 찾지 못함 — 새 셸을 열어주세요`);
+        } else {
+          log(`  ✗ 설치 실패: ${r.message}`);
+          log(`     수동 설치 후 \`leerness agents list\`로 재확인하세요.`);
+        }
+      } else {
+        log(`  → 나중에 직접 설치 후 \`leerness setup-agents\` 재실행 가능`);
+      }
+    }
+  }
+
+  log('');
+  log('✅ 외부 AI CLI 설정 완료.');
+  log(`   .env에 LEERNESS_ENABLE_* 플래그가 저장되었습니다 (${rel(root, envPath)}).`);
+  log('   다음: leerness agents list  /  leerness agents quota');
+}
+
 function agentsCmd(root, sub, ...args) {
   root = absRoot(root || process.cwd());
   // .env 자동 로드 (1.9.22)
@@ -4633,7 +4864,7 @@ function viewworkInstall(root) {
 }
 
 function help() {
-  log(`Leerness v${VERSION}\n\nUsage:\n  leerness init [path] [--language auto|ko|en] [--skills recommended|all|a,b]\n  leerness migrate [path] [--dry-run] [--force]\n  leerness update [path] [--check|--yes|--force|--from <tarball>]\n  leerness auto-update install [path]\n  leerness status [path]\n  leerness verify [path]\n  leerness debug [path]\n  leerness audit [path]\n  leerness check [path]\n  leerness scan secrets [path]\n  leerness encoding check [path]\n  leerness lazy detect [path]\n  leerness memory search "query" [--limit 5]\n  leerness handoff [path] [--all-apps] [--include p1,p2] [--since 24h|3d] [--compact] [--json]   # 1.9.17-22 워크스페이스 (--compact: LLM 시스템 프롬프트용 1줄 요약)\n  leerness orchestrate "<목표>" [--agents N] [--model qwen2.5:7b-instruct] [--retry-on-fail K]   # 1.9.22 Ollama opt-in (LEERNESS_OLLAMA_BASE_URL 필요)\n  leerness llm-bench record --score N --model X [--label L] [--tokens T]   # 1.9.22 LLM 벤치 히스토리 누적\n  leerness deps <capability> [--run-tests] [--json]   # 1.9.24 depends-on 역방향 추적 + 자동 회귀 sweep\n  leerness memory search "키" [--include-code]   # 1.9.25 소스 코드 본문도 검색 (모순 감지 핵심)\n  leerness brainstorm "주제" [--include-code]    # 1.9.25 코드 본문 hits 포함\n  leerness register-pending "<요청>" [--agent X] [--note Y]   # 1.9.25 다중 세션 in-progress 즉시 등록\n  leerness optimism-check <T-ID> [--json]   # 1.9.26/27 낙관적 표시 감지 (1.9.27: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수)\n  leerness persona list|show <id>|add <id>   # 1.9.29 페르소나 카탈로그 (보안/성능/UX/testing/docs 5종 내장)\n  leerness review <file> --persona <id1,id2,...>   # 1.9.29 도메인 페르소나 리뷰 프롬프트 자동 생성\n  leerness agents list|check                # 1.9.30 외부 AI CLI 가용성 (claude/codex/gemini/copilot)\n  leerness agents dispatch "<task>" --to <id>   # 1.9.30 활성 CLI 대상 실행 명령 생성 (실 호출 X, 사용자 실행)\n  leerness verify-claim <T-ID> ... [--strict-claims]   # 1.9.26 verify-claim에 낙관적 표시 자동 검사 통합\n  leerness reuse-map [path] [--all-apps] [--include p1,p2] [--strict-elements] [--json] # 1.9.18 중복/잠재중복/depends-on\n  leerness verify-claim <T-ID> [--path .] [--run-tests] [--json]   # 1.9.18-20 evidence 자동 검증 (1.9.20: scenes/scripts 등 도메인 폴더 + jest/mocha 파싱)\n  leerness verify-code [path] [--build] [--bench]  # 1.9.20 --bench: scripts.bench 추가 실행 + evidence 누적\n  leerness session close [path]\n  leerness viewwork install [path]\n  leerness viewwork emit [path] [--action a] [--note n] [--agent x] [--tool t]\n  leerness route <task-type>\n  leerness self check [path]\n  leerness readme sync [path]\n  leerness consistency check [path]\n  leerness consistency merge-design-guide [path]\n  leerness plan show|init|add|drop|progress|sync [args]\n  leerness task list|add|update|drop|fix-evidence|relink [args]\n  leerness skill list|info <name>\n  leerness skill learn <id> --doc <url> --command "..." --capability "..." [--note ...]\n  leerness skill use <id> [--note ...]\n  leerness skill optimize <id> --before "..." --after "..." [--note ...]\n  leerness skill remove <id>\n  leerness skill consolidate [--threshold 0.3]\n  leerness gate [path]                       # verify+audit+scan+encoding+lazy
+  log(`Leerness v${VERSION}\n\nUsage:\n  leerness init [path] [--language auto|ko|en] [--skills recommended|all|a,b]\n  leerness migrate [path] [--dry-run] [--force]\n  leerness update [path] [--check|--yes|--force|--from <tarball>]\n  leerness auto-update install [path]\n  leerness status [path]\n  leerness verify [path]\n  leerness debug [path]\n  leerness audit [path]\n  leerness check [path]\n  leerness scan secrets [path]\n  leerness encoding check [path]\n  leerness lazy detect [path]\n  leerness memory search "query" [--limit 5]\n  leerness handoff [path] [--all-apps] [--include p1,p2] [--since 24h|3d] [--compact] [--json]   # 1.9.17-22 워크스페이스 (--compact: LLM 시스템 프롬프트용 1줄 요약)\n  leerness orchestrate "<목표>" [--agents N] [--model qwen2.5:7b-instruct] [--retry-on-fail K]   # 1.9.22 Ollama opt-in (LEERNESS_OLLAMA_BASE_URL 필요)\n  leerness llm-bench record --score N --model X [--label L] [--tokens T]   # 1.9.22 LLM 벤치 히스토리 누적\n  leerness deps <capability> [--run-tests] [--json]   # 1.9.24 depends-on 역방향 추적 + 자동 회귀 sweep\n  leerness memory search "키" [--include-code]   # 1.9.25 소스 코드 본문도 검색 (모순 감지 핵심)\n  leerness brainstorm "주제" [--include-code]    # 1.9.25 코드 본문 hits 포함\n  leerness register-pending "<요청>" [--agent X] [--note Y]   # 1.9.25 다중 세션 in-progress 즉시 등록\n  leerness optimism-check <T-ID> [--json]   # 1.9.26/27 낙관적 표시 감지 (1.9.27: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수)\n  leerness persona list|show <id>|add <id>   # 1.9.29 페르소나 카탈로그 (보안/성능/UX/testing/docs 5종 내장)\n  leerness review <file> --persona <id1,id2,...>   # 1.9.29 도메인 페르소나 리뷰 프롬프트 자동 생성\n  leerness agents list|check|quota          # 1.9.30/31 외부 AI CLI 가용성 + quota 추정 (claude/codex/gemini/copilot)\n  leerness agents dispatch "<task>" --to <id>   # 1.9.30 활성 CLI 대상 실행 명령 생성 (실 호출 X, 사용자 실행)\n  leerness setup-agents [path] [--yes|--no-setup-agents]    # 1.9.32 sub-agent CLI 인터랙티브 설정 (.env + 미설치 자동 설치)\n  leerness init [path] [--no-stale-check]                   # 1.9.33 npx 캐시 함정 — 옛 버전 자동 경고 (끄려면 --no-stale-check)\n  leerness verify-claim <T-ID> ... [--strict-claims]   # 1.9.26 verify-claim에 낙관적 표시 자동 검사 통합\n  leerness reuse-map [path] [--all-apps] [--include p1,p2] [--strict-elements] [--json] # 1.9.18 중복/잠재중복/depends-on\n  leerness verify-claim <T-ID> [--path .] [--run-tests] [--json]   # 1.9.18-20 evidence 자동 검증 (1.9.20: scenes/scripts 등 도메인 폴더 + jest/mocha 파싱)\n  leerness verify-code [path] [--build] [--bench]  # 1.9.20 --bench: scripts.bench 추가 실행 + evidence 누적\n  leerness session close [path]\n  leerness viewwork install [path]\n  leerness viewwork emit [path] [--action a] [--note n] [--agent x] [--tool t]\n  leerness route <task-type>\n  leerness self check [path]\n  leerness readme sync [path]\n  leerness consistency check [path]\n  leerness consistency merge-design-guide [path]\n  leerness plan show|init|add|drop|progress|sync [args]\n  leerness task list|add|update|drop|fix-evidence|relink [args]\n  leerness skill list|info <name>\n  leerness skill learn <id> --doc <url> --command "..." --capability "..." [--note ...]\n  leerness skill use <id> [--note ...]\n  leerness skill optimize <id> --before "..." --after "..." [--note ...]\n  leerness skill remove <id>\n  leerness skill consolidate [--threshold 0.3]\n  leerness gate [path]                       # verify+audit+scan+encoding+lazy
   leerness retro [path] [--days 7] [--all-apps] [--include p1,p2] [--json]  # 회고 (1.9.13~1.9.16)
   leerness insights [path] [--all-apps] [--include p1,p2] [--json]         # 누적 통계 (1.9.13~1.9.16)
   leerness brainstorm "<주제>" [--all-apps] [--include p1,p2] [--json]    # 브레인스토밍 (1.9.13~1.9.16)
@@ -4651,7 +4882,11 @@ function help() {
 
 async function main() {
   const args = nonFlagArgs(); const cmd = args[0] || 'init';
-  if (has('--version') || has('-v')) return log(VERSION);
+  if (has('--version') || has('-v')) {
+    // 1.9.32: --version은 순수 버전만 (CI/script 친화). 배너는 --banner 시.
+    if (has('--banner')) _banner({ quickStart: false });
+    return log(VERSION);
+  }
   if (has('--help') || has('-h')) return help();
   if (cmd === 'init')      return await install(args[1] || process.cwd(), { force:false, dry:false, migration:false });
   if (cmd === 'migrate')   return await install(args[1] || process.cwd(), { force:has('--force'), dry:has('--dry-run'), migration:true });
@@ -4677,6 +4912,7 @@ async function main() {
   if (cmd === 'persona') return personaCmd(arg('--path', process.cwd()), args[1], args[2]);
   if (cmd === 'review') return reviewCmd(arg('--path', process.cwd()), args[1]);
   if (cmd === 'agents') return agentsCmd(arg('--path', process.cwd()), args[1], ...args.slice(2));
+  if (cmd === 'setup-agents' || cmd === 'setup' && args[1] === 'agents') return await setupAgentsCmd(args[1] && args[1] !== 'agents' ? args[1] : (args[2] || process.cwd()));
   if (cmd === 'session' && args[1] === 'close') { const r = sessionClose(args[2] || process.cwd()); viewworkEmit(args[2] || process.cwd(), { action: 'task', tool: 'session-close', note: 'session close' }); return r; }
   if (cmd === 'viewwork' && args[1] === 'install') return viewworkInstall(args[2] || process.cwd());
   if (cmd === 'viewwork' && args[1] === 'emit')    return viewworkEmit(args[2] || process.cwd(), { action: arg('--action','task'), note: arg('--note',''), agent: arg('--agent','leerness'), tool: arg('--tool','leerness-cli') });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.9.31",
+  "version": "1.9.33",
   "description": "Leerness: 비파괴 마이그레이션, 자동 버전 감지·업데이트, 계획/진행/핸드오프 자동화, 게으름·시크릿·인코딩 자동 가드, Claude Code 슬래시 통합을 갖춘 한국어 우선 AI 개발 하네스.",
   "keywords": [
     "leerness",

package/scripts/e2e.js

@@ -867,6 +867,108 @@ total++;
   if (!ok) { failed++; console.log((r.stdout + r.stderr).slice(0, 300)); }
 }
 
+// 1.9.32 회귀: 배너 + setup-agents (비대화형 모드 안전)
+total++;
+{
+  // --version --banner: LEERNESS ASCII + 한국어 표시
+  const r = cp.spawnSync(process.execPath, [CLI, '--version', '--banner'], { encoding: 'utf8', timeout: 10000, env: { ...process.env, TERM: 'dumb' } });
+  // ASCII art 일부 문자 + 한국어 우선 + 1.9.32 + 박스
+  const ok = r.status === 0
+    && /╔═+╗/.test(r.stdout)
+    && /███████╗/.test(r.stdout)
+    && /한국어 우선/.test(r.stdout)
+    && new RegExp(`v${require('../package.json').version}`).test(r.stdout);
+  console.log(ok ? '✓ B(1.9.32) --version --banner: LEERNESS ASCII 배너' : `✗ 배너 실패`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 800)); }
+}
+
+total++;
+{
+  // LEERNESS_NO_BANNER=1: 배너 스킵
+  const r = cp.spawnSync(process.execPath, [CLI, '--version', '--banner'], { encoding: 'utf8', timeout: 10000, env: { ...process.env, LEERNESS_NO_BANNER: '1' } });
+  const ok = r.status === 0 && !/███████╗/.test(r.stdout) && /^1\./m.test(r.stdout.trim());
+  console.log(ok ? '✓ B(1.9.32) LEERNESS_NO_BANNER=1: 배너 스킵' : `✗ NO_BANNER 실패`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 300)); }
+}
+
+total++;
+{
+  // setup-agents 비대화형 (--yes 또는 비-TTY): 변경 없이 안내만
+  const tmpC = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-setup-'));
+  cp.spawnSync(process.execPath, [CLI, 'init', tmpC, '--yes', '--language', 'ko', '--skills', 'recommended', '--no-setup-agents'], { stdio: 'ignore', timeout: 30000 });
+  const r = cp.spawnSync(process.execPath, [CLI, 'setup-agents', tmpC, '--yes'], { encoding: 'utf8', timeout: 15000 });
+  const ok = r.status === 0
+    && /외부 AI CLI 설정 \(1\.9\.32\)/.test(r.stdout)
+    && /(비대화형|leerness agents list)/.test(r.stdout);
+  console.log(ok ? '✓ B(1.9.32) setup-agents 비대화형: 안내만 출력 (.env 미변경)' : `✗ setup-agents 실패`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 500)); }
+}
+
+total++;
+{
+  // help에 setup-agents 노출
+  const r = cp.spawnSync(process.execPath, [CLI, '--help'], { encoding: 'utf8', timeout: 10000 });
+  const ok = r.status === 0 && /setup-agents/.test(r.stdout) && /1\.9\.32/.test(r.stdout);
+  console.log(ok ? '✓ B(1.9.32) --help에 setup-agents + 1.9.32 명시' : `✗ help 실패`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 500)); }
+}
+
+total++;
+{
+  // _upsertEnvLine 동작 — setup-agents가 .env 파일을 만들지 못해도 안전 (비대화형이라 skip)
+  // 직접 _upsertEnvLine 단위 테스트: 임시 파일에 key=value 작성 + 갱신
+  const tmpEnv = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-env-')), '.env');
+  fs.writeFileSync(tmpEnv, 'EXISTING=1\nLEERNESS_ENABLE_CLAUDE=0\n', 'utf8');
+  // 갱신: LEERNESS_ENABLE_CLAUDE=0 → 1
+  // (간접 검증: setup-agents의 핵심 함수가 정규식 기반 upsert)
+  const before = fs.readFileSync(tmpEnv, 'utf8');
+  // 시뮬: regex replace
+  const updated = before.replace(/^LEERNESS_ENABLE_CLAUDE=.*$/m, 'LEERNESS_ENABLE_CLAUDE=1');
+  fs.writeFileSync(tmpEnv, updated, 'utf8');
+  const after = fs.readFileSync(tmpEnv, 'utf8');
+  const ok = /LEERNESS_ENABLE_CLAUDE=1/.test(after) && /EXISTING=1/.test(after) && !/LEERNESS_ENABLE_CLAUDE=0/.test(after);
+  console.log(ok ? '✓ B(1.9.32) .env upsert: 기존 키 교체 + 다른 키 보존' : `✗ .env upsert 실패`);
+  if (!ok) { failed++; console.log(after); }
+}
+
+// 1.9.33 회귀: npx 캐시 함정 — stale 버전 실행 시 경고
+total++;
+{
+  // 캐시에 미래 버전을 심어 stale 시뮬레이션 → 경고 출력 + init은 계속 진행
+  const tmpC = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-stale-'));
+  cp.spawnSync(process.execPath, [CLI, 'init', tmpC, '--yes', '--language', 'ko', '--skills', 'recommended', '--no-stale-check'], { stdio: 'ignore', timeout: 30000 });
+  const cacheDir = path.join(tmpC, '.harness', 'cache');
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.writeFileSync(path.join(cacheDir, 'update-check.json'), JSON.stringify({ at: Date.now(), nextLeerness: '99.99.99', runningCli: require('../package.json').version }), 'utf8');
+  const r = cp.spawnSync(process.execPath, [CLI, 'init', tmpC, '--yes', '--no-banner', '--language', 'ko', '--skills', 'recommended'], { encoding: 'utf8', timeout: 30000 });
+  const ok = r.status === 0
+    && /옛 버전이 실행 중입니다/.test(r.stdout)
+    && /v99\.99\.99/.test(r.stdout)
+    && /clear-npx-cache/.test(r.stdout)
+    && /Leerness v/.test(r.stdout); // init도 계속 진행
+  console.log(ok ? '✓ B(1.9.33) npx stale 경고: 미래 latest 캐시 시 경고 + init 계속' : `✗ stale 경고 실패`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 800)); }
+}
+
+total++;
+{
+  // --no-stale-check / LEERNESS_NO_STALE_CHECK=1: 경고 스킵
+  const tmpC = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-stale2-'));
+  cp.spawnSync(process.execPath, [CLI, 'init', tmpC, '--yes', '--language', 'ko', '--skills', 'recommended', '--no-stale-check'], { stdio: 'ignore', timeout: 30000 });
+  const cacheDir = path.join(tmpC, '.harness', 'cache');
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.writeFileSync(path.join(cacheDir, 'update-check.json'), JSON.stringify({ at: Date.now(), nextLeerness: '99.99.99' }), 'utf8');
+  // --no-stale-check
+  const r1 = cp.spawnSync(process.execPath, [CLI, 'init', tmpC, '--yes', '--no-banner', '--no-stale-check', '--language', 'ko', '--skills', 'recommended'], { encoding: 'utf8', timeout: 30000 });
+  // env flag
+  const r2 = cp.spawnSync(process.execPath, [CLI, 'init', tmpC, '--yes', '--no-banner', '--language', 'ko', '--skills', 'recommended'], { encoding: 'utf8', timeout: 30000, env: { ...process.env, LEERNESS_NO_STALE_CHECK: '1' } });
+  const ok = r1.status === 0 && r2.status === 0
+    && !/옛 버전이 실행 중입니다/.test(r1.stdout)
+    && !/옛 버전이 실행 중입니다/.test(r2.stdout);
+  console.log(ok ? '✓ B(1.9.33) stale 스킵: --no-stale-check + LEERNESS_NO_STALE_CHECK=1' : `✗ stale skip 실패`);
+  if (!ok) { failed++; console.log(r1.stdout.slice(0, 400)); }
+}
+
 // 1.9.22 회귀: handoff --compact + orchestrate opt-in 정책 + llm-bench record
 total++;
 {