leerness 1.9.31 → 1.9.32

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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.32-green)]() [![tests](https://img.shields.io/badge/e2e-151%2F151-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,57 @@ npm i --save-dev leerness && npx leerness handoff .
 
 > npmjs.com의 `npm i leerness`는 라이브러리 import용. CLI 명령(`leerness ...`) 직접 호출은 위 3가지 중 하나 필요.
 
+### 🎨 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 +170,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 +290,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 +371,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 +395,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 | 추정 | 안내 |
 |---|---|---|
@@ -415,12 +501,13 @@ A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)
 npm test     # = node ./scripts/e2e.js
 ```
 
-**146/146 시나리오** 통과 (1.9.7~1.9.31 회귀 + 신규 검증).
+**151/151 시나리오** 통과 (1.9.7~1.9.32 회귀 + 신규 검증).
 
 ---
 
 ## 📜 변경 이력 (최근)
 
+- **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.32';
 const MARK = '<!-- leerness:managed -->';
 const README_START = '<!-- leerness:project-readme:start -->';
 const README_END = '<!-- leerness:project-readme:end -->';
@@ -386,10 +386,12 @@ 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 });
   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 +473,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 +2286,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 +2320,163 @@ function _checkAgent(agent, opts = {}) {
   };
 }
 
+// 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 +4812,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 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 +4830,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 +4860,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.32",
   "description": "Leerness: 비파괴 마이그레이션, 자동 버전 감지·업데이트, 계획/진행/핸드오프 자동화, 게으름·시크릿·인코딩 자동 가드, Claude Code 슬래시 통합을 갖춘 한국어 우선 AI 개발 하네스.",
   "keywords": [
     "leerness",

package/scripts/e2e.js

@@ -867,6 +867,70 @@ 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.22 회귀: handoff --compact + orchestrate opt-in 정책 + llm-bench record
 total++;
 {