leerness 1.9.29 → 1.9.31

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 1.9.31 — 2026-05-15
+
+**`leerness agents quota` — 외부 AI CLI 사용량/한도 추정 + provider 대시보드 안내**.
+
+### Added
+
+- **`leerness agents quota`** (1.9.31): 활성 CLI별 quota/rate-limit 정보 표시.
+  - **claude**: 비대화형 quota API 없음 → `/status` 슬래시 또는 https://console.anthropic.com/settings/usage 안내.
+  - **codex**: `codex --help`에서 `usage`/`quota` 키워드 감지 시 시도 가능 표시, 미감지 시 https://platform.openai.com/account/usage 안내.
+  - **gemini**: 무료 티어 `60 req/min, 1000 req/day` 명시.
+  - **copilot (gh)**: `gh auth status`로 인증 확인 → 구독자 무제한 또는 `gh auth login` 필요 안내.
+  - `--json` 출력 지원 (`{ quota: [{id, bin, status, quota, hint, raw}, ...] }`).
+- **`agents` 사용법 메시지에 `quota` 추가**: `list|check|quota|dispatch`.
+- **`agents dispatch` 안내문에 quota 명령 cross-link** (1.9.31+).
+
+### Policy
+- ❌ leerness는 사용량을 직접 추적하지 않음 (provider 대시보드 참조)
+- ✅ sub-agent 분배 시 quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
+- ✅ rate-limit/plan 차이는 provider별 다름 — leerness는 hint만 제공
+
+### 실측 (이번 라운드 사용 사례)
+- agents quota 신규 명령 검증 후 sub-agent ×3 동시 분배
+- e2e: 146/146 통과 (1.9.30 144 + quota 2)
+
+## 1.9.30 — 2026-05-15
+
+**외부 AI CLI 오케스트레이션 — 환경변수 활성화 정책 + `leerness agents list/check/dispatch`**.
+
+claude/codex/gemini/copilot CLI들을 sub-agent로 명시적 활용 가능. 사용자 동의(환경변수) + PATH 존재 둘 다 충족 시에만 ready.
+
+### Added
+
+- **`.env.example`에 4개 활성화 플래그 추가**:
+  - `LEERNESS_ENABLE_CLAUDE=1` (Anthropic Claude Code, 기본 활성)
+  - `LEERNESS_ENABLE_CODEX=0` (OpenAI Codex CLI, 격리 sandbox)
+  - `LEERNESS_ENABLE_GEMINI=0` (Google Gemini CLI, `--yolo` 모드는 워크스페이스 직접 수정 가능)
+  - `LEERNESS_ENABLE_COPILOT=0` (GitHub Copilot CLI = `gh copilot`)
+- **`leerness agents list`**: 4 CLI별 (env=1 여부) + (PATH 존재 여부) + 버전 + 상태 (ready/disabled/not-installed) 표 출력. `--json` 지원.
+- **`leerness agents check`**: alias of list (재확인 강조).
+- **`leerness agents dispatch "<task>" --to <id>`**: 활성 ready CLI에 대상 명령 자동 생성 (`claude "..."`, `codex exec "..."`, `gemini -p "..." --yolo`, `gh copilot suggest "..."`).
+  - **leerness는 자동 호출 안 함** — 사용자/메인 에이전트가 명시적 실행.
+  - 비활성/미설치 시 안내 후 `exit 1`.
+
+### Policy
+- ❌ 환경변수 미설정 또는 PATH 없으면 dispatch 거부
+- ✅ 환경변수 + PATH 둘 다 충족 시에만 ready
+- ✅ leerness는 외부 CLI 자동 호출 금지 (1.9.22 Ollama opt-in과 동일 원칙)
+
+### 실측 (이번 라운드 사용 사례)
+- Claude sub-agent ×2 (PvP 매치메이킹 + 길드 시스템) → 각각 26/26, 23/23 통과
+- Gemini CLI 외부 호출 (yolo 모드) → rpg-stats 통계 대시보드 자동 생성 (13/13, HTML 5.5KB)
+- → 3 도메인 동시 진행, 메인 에이전트가 외부 CLI를 sub-agent처럼 활용
+
 ## 1.9.29 — 2026-05-15
 
 **페르소나 시스템 — 5종 내장 + `leerness review --persona` (도메인 깊이 3-4배)**.

package/README.md

@@ -2,7 +2,7 @@
 
 > 한국어 우선 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.29-green)]() [![tests](https://img.shields.io/badge/e2e-139%2F139-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.31-green)]() [![tests](https://img.shields.io/badge/e2e-146%2F146-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
 
 ## ⚙️ 설치 (Install)
 
@@ -31,6 +31,8 @@ npm i --save-dev leerness && npx leerness handoff .
 - LLM 컨텍스트 비용 → `--compact` 모드로 4KB → 500자
 - AI가 "API 호출 완료"라 보고했지만 코드에 호출 흔적이 없는 낙관적 표시 → `optimism-check`로 자동 감지 (1.9.26/27)
 - 코드 리뷰가 표면적이라 도메인 깊이 부족 → `leerness review <file> --persona security,performance,ux`로 도메인 페르소나 자동 부여 (1.9.29)
+- 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하고 싶지만 자동 호출은 위험 → 환경변수 활성화 + `leerness agents list/dispatch`로 명시적 분배 (1.9.30)
+- 어떤 CLI에 quota 여유가 남았는지 한눈에 보고 싶을 때 → `leerness agents quota`로 provider별 사용량/한도 추정 (1.9.31)
 
 ---
 
@@ -97,6 +99,9 @@ leerness review <file> --persona security,performance,ux   # 1.9.29 도메인
 leerness persona list                                       # 5종 내장 + 사용자 정의
 leerness persona show security                              # 페르소나 본문
 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 명령 생성
 ```
 
 ### 워크스페이스 (멀티 프로젝트)
@@ -213,6 +218,9 @@ leerness orchestrate "복잡한 기능" --agents 20
 | `handoff --compact` | LLM 시스템 프롬프트용 압축 출력 | 1.9.22 |
 | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 (security/performance/ux/testing/docs) | 1.9.29 |
 | `persona list/show/add` | 페르소나 카탈로그 관리 (.harness/personas/) | 1.9.29 |
+| `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 |
 
 ---
 
@@ -293,6 +301,47 @@ leerness persona add my-domain   # .harness/personas/my-domain.md 템플릿 생
 
 ---
 
+## 🤖 외부 AI CLI 오케스트레이션 (1.9.30 / 1.9.31)
+
+claude/codex/gemini/copilot CLI들을 sub-agent로 명시적 활용. **자동 호출 절대 금지** — 환경변수 활성화 + PATH 존재 둘 다 충족 시에만 ready.
+
+### 활성화 (`.env`)
+```bash
+LEERNESS_ENABLE_CLAUDE=1     # Anthropic Claude Code CLI
+LEERNESS_ENABLE_CODEX=1      # OpenAI Codex CLI (격리 sandbox)
+LEERNESS_ENABLE_GEMINI=1     # Google Gemini CLI (--yolo 모드는 워크스페이스 직접 수정 가능)
+LEERNESS_ENABLE_COPILOT=1    # GitHub Copilot CLI (gh copilot)
+```
+
+### 사용
+```bash
+leerness agents list                              # 4 CLI 상태표 (env + PATH + 버전)
+leerness agents quota                             # provider별 사용량/한도 추정 (1.9.31)
+leerness agents dispatch "<task>" --to gemini     # ready CLI에 명령 자동 생성
+```
+
+### quota 안내 (1.9.31)
+| CLI | 추정 | 안내 |
+|---|---|---|
+| claude | `unknown` | 대화 내 `/status` 슬래시 또는 https://console.anthropic.com/settings/usage |
+| codex | `cli-supported` 또는 `unknown` | `codex usage`/`codex quota` 시도 또는 https://platform.openai.com/account/usage |
+| gemini | `rate-limited` | 무료 60 req/min, 1000 req/day · https://ai.google.dev/gemini-api/docs/rate-limits |
+| copilot | `subscription` 또는 `not-authed` | 월 구독자 무제한 · `gh auth login` 필요 시 안내 |
+
+### 실측 (이번 라운드)
+- Sub B (rpg-craft, Claude 페르소나) → 20/20 pass, 1,567 라인
+- Sub C (rpg-achievements, Claude 페르소나) → 22/22 pass, 1,375 라인
+- Sub D (rpg-instance, Claude 페르소나, cross-project require 시연) → 20/20 pass, 1,016 라인
+- → **3 도메인 동시 진행**, 메인 에이전트가 sub-agent들에 페르소나 + 영역 분배 + 충돌 방지 컨벤션 명시.
+
+### 정책
+- ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인 에이전트가 명시적 실행)
+- ✅ `agents dispatch`는 명령 텍스트만 출력 — 복사해서 실행
+- ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
+- ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 — 격리 sandbox 아님 (codex와 차이)
+
+---
+
 ## 🤝 Claude Code 통합
 
 설치 시 자동 등록: `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md` · `.claude/skills/leerness.md` (스킬 정의) · `.claude/settings.local.json` (SessionStart hook `update --check`) · `.cursor/rules/leerness.mdc` (Cursor) · `.github/copilot-instructions.md` (Copilot)
@@ -323,6 +372,10 @@ leerness skill consolidate
 | `LEERNESS_GITHUB_TOKEN` | gh release용 (있을 때) |
 | **`LEERNESS_OLLAMA_BASE_URL`** | **1.9.22 — orchestrate opt-in 활성화** |
 | `LEERNESS_OLLAMA_MODEL` | 기본 모델 (orchestrate `--model`로 override) |
+| **`LEERNESS_ENABLE_CLAUDE`** | **1.9.30 — `agents list/dispatch` Claude Code CLI 활성** (=1) |
+| **`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) |
 
 ---
 
@@ -362,12 +415,14 @@ A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)
 npm test     # = node ./scripts/e2e.js
 ```
 
-**139/139 시나리오** 통과 (1.9.7~1.9.29 회귀 + 신규 검증).
+**146/146 시나리오** 통과 (1.9.7~1.9.31 회귀 + 신규 검증).
 
 ---
 
 ## 📜 변경 이력 (최근)
 
+- **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배)
 - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15
 - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수

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.29';
+const VERSION = '1.9.31';
 const MARK = '<!-- leerness:managed -->';
 const README_START = '<!-- leerness:project-readme:start -->';
 const README_END = '<!-- leerness:project-readme:end -->';
@@ -439,7 +439,12 @@ async function install(root, opts = {}) {
       '# 1.9.22 — orchestrate opt-in. URL이 설정되면 leerness가 Ollama를 사용 가능. 미설정 시 LLM 호출 자동 시작 금지.',
       'LEERNESS_OLLAMA_BASE_URL=',
       '# 선택. 기본 모델 (orchestrate --model 로 override 가능).',
-      'LEERNESS_OLLAMA_MODEL='
+      'LEERNESS_OLLAMA_MODEL=',
+      '# 1.9.30 — 외부 AI CLI 활성화 플래그. 1=활성, 0/미설정=비활성. 메인 에이전트가 sub-agent 분배 시 활성 CLI들에 작업 위임 가능.',
+      'LEERNESS_ENABLE_CLAUDE=1',
+      'LEERNESS_ENABLE_CODEX=0',
+      'LEERNESS_ENABLE_GEMINI=0',
+      'LEERNESS_ENABLE_COPILOT=0'
     ]);
     mergeLinesFile(path.join(root, '.gitattributes'), [
       '* text=auto eol=lf','*.bat text eol=crlf','*.ps1 text eol=crlf'
@@ -2262,6 +2267,182 @@ function _resolvePersona(root, id) {
   return null;
 }
 
+// 1.9.30: 외부 AI CLI 오케스트레이션 — claude/codex/gemini/copilot 가용성 + 활성화 체크
+// 사용자 정책: 환경변수로 활성화 명시 + 실제 PATH 존재 확인 + 메인이 sub-agent 분배 시 참조
+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)' }
+];
+
+function _checkAgent(agent, opts = {}) {
+  const enabled = process.env[agent.envFlag] === '1';
+  // PATH 존재 확인 (which / where)
+  let installed = false, version = null, error = null;
+  try {
+    const r = cp.spawnSync(agent.bin, agent.versionArgs, { encoding: 'utf8', timeout: 5000, shell: true });
+    if (r.status === 0 || (r.stdout && r.stdout.trim())) {
+      installed = true;
+      version = (r.stdout || r.stderr || '').trim().split('\n')[0].slice(0, 80);
+    } else if (r.error) {
+      error = r.error.code || r.error.message;
+    } else {
+      error = `exit ${r.status}`;
+    }
+  } catch (e) { error = e.message; }
+  return {
+    id: agent.id, bin: agent.bin, desc: agent.desc, envFlag: agent.envFlag,
+    enabled, installed, version, error,
+    status: enabled && installed ? 'ready' : !installed ? 'not-installed' : !enabled ? 'disabled' : 'unknown'
+  };
+}
+
+function agentsCmd(root, sub, ...args) {
+  root = absRoot(root || process.cwd());
+  // .env 자동 로드 (1.9.22)
+  _loadEnvFile(root);
+  _loadEnvFile(path.join(root, '..'));
+
+  if (!sub || sub === 'list') {
+    const checks = EXTERNAL_AGENTS.map(a => _checkAgent(a));
+    if (has('--json')) { log(JSON.stringify({ agents: checks }, null, 2)); return; }
+    log(`# 외부 AI CLI 오케스트레이션 (1.9.30)`);
+    log('');
+    log(`| Agent | env (${'env=1 활성'}) | 설치 | 버전 | 상태 |`);
+    log(`|---|---|---|---|---|`);
+    for (const c of checks) {
+      const envMark = c.enabled ? '✓' : '✗';
+      const instMark = c.installed ? '✓' : '✗';
+      const statusEmoji = c.status === 'ready' ? '🟢 ready' : c.status === 'not-installed' ? '⚪ 미설치' : c.status === 'disabled' ? '🟡 비활성' : '❓';
+      log(`| ${c.id} | ${envMark} ${c.envFlag} | ${instMark} | ${c.version || '-'} | ${statusEmoji} |`);
+    }
+    const ready = checks.filter(c => c.status === 'ready');
+    log('');
+    log(`## 활성 (${ready.length}/${checks.length}): ${ready.map(c => c.id).join(', ') || '(없음)'}`);
+    if (!ready.length) {
+      log('');
+      log(`💡 활성화 방법:`);
+      log(`  1) CLI 설치 (예: \`npm i -g @openai/codex-cli\`, \`npm i -g @google/gemini-cli\`)`);
+      log(`  2) .env 또는 환경변수: LEERNESS_ENABLE_CODEX=1, LEERNESS_ENABLE_GEMINI=1`);
+      log(`  3) \`leerness agents check\`로 재확인`);
+    } else {
+      log('');
+      log(`💡 메인 에이전트가 sub-agent 분배 시 위 ${ready.length}개 CLI 활용 가능:`);
+      log(`   \`leerness agents dispatch "<task>" --to <id>\` 로 프롬프트 전달`);
+    }
+    return;
+  }
+
+  if (sub === 'check') {
+    // list의 alias, 단 명시적 재확인 (JSON 출력 기본)
+    const checks = EXTERNAL_AGENTS.map(a => _checkAgent(a));
+    if (has('--json')) { log(JSON.stringify({ agents: checks, ready: checks.filter(c => c.status === 'ready').map(c => c.id) }, null, 2)); return; }
+    return agentsCmd(root, 'list'); // 비-JSON은 list와 동일
+  }
+
+  if (sub === 'dispatch') {
+    const task = args.filter(x => !x.startsWith('-')).join(' ').trim() || arg('--task', null);
+    const target = arg('--to', null);
+    if (!task) { fail('dispatch "<task>" 또는 --task 필요'); return process.exit(1); }
+    if (!target) { fail('--to <agent_id> 필요 (claude/codex/gemini/copilot)'); return process.exit(1); }
+    const agentDef = EXTERNAL_AGENTS.find(a => a.id === target);
+    if (!agentDef) { fail(`알 수 없는 agent: ${target}`); return process.exit(1); }
+    const status = _checkAgent(agentDef);
+    if (status.status !== 'ready') {
+      fail(`${target} 비활성 (${status.status}). 환경변수 ${agentDef.envFlag}=1 + CLI 설치 필요.`);
+      return process.exit(1);
+    }
+    // 실제 호출은 안 함 — 프롬프트만 생성 (사용자가 명시적으로 실행)
+    log(`# leerness agents dispatch (1.9.30)`);
+    log(`대상: ${target} (${agentDef.bin})`);
+    log(`상태: 🟢 ready, 버전 ${status.version || '?'}`);
+    log('');
+    log(`## 실행 명령 (사용자가 복사해서 실행)`);
+    log('');
+    if (target === 'claude') {
+      log(`claude "${task.replace(/"/g, '\\"')}"`);
+    } else if (target === 'codex') {
+      log(`codex exec "${task.replace(/"/g, '\\"')}"`);
+    } else if (target === 'gemini') {
+      log(`gemini -p "${task.replace(/"/g, '\\"')}" --yolo   # ⚠ yolo는 워크스페이스 직접 수정 가능`);
+    } else if (target === 'copilot') {
+      log(`gh copilot suggest "${task.replace(/"/g, '\\"')}"`);
+    }
+    log('');
+    log(`## 정책 (1.9.30)`);
+    log(`  - leerness는 외부 CLI를 자동 호출하지 않음 (사용자 명시적 실행)`);
+    log(`  - 메인 에이전트(Claude)가 위 명령을 보고 sub-agent로 spawn 가능`);
+    log(`  - quota 체크: \`leerness agents quota\` (1.9.31+)`);
+    return;
+  }
+
+  if (sub === 'quota') {
+    // 1.9.31: 각 CLI 사용량/쿼터 추정 + provider 대시보드 링크
+    const results = [];
+    for (const agent of EXTERNAL_AGENTS) {
+      const base = _checkAgent(agent);
+      const out = { id: agent.id, bin: agent.bin, status: base.status, quota: null, hint: null, raw: null };
+      if (base.status !== 'ready') {
+        out.hint = base.status === 'not-installed' ? `${agent.bin} CLI 미설치` : base.status === 'disabled' ? `${agent.envFlag}=1 필요` : '알 수 없음';
+        results.push(out); continue;
+      }
+      // CLI별 quota 탐지 시도
+      try {
+        if (agent.id === 'claude') {
+          // claude는 /status 슬래시 (대화형)만 지원. 비대화형 추정 불가.
+          out.quota = 'unknown';
+          out.hint = '대화 내 `/status` 슬래시 또는 https://console.anthropic.com/settings/usage 확인';
+        } else if (agent.id === 'codex') {
+          // codex CLI: codex --help에 usage 명령 있는지 확인
+          const r = cp.spawnSync(agent.bin, ['--help'], { encoding: 'utf8', timeout: 4000, shell: true });
+          const help = (r.stdout || r.stderr || '').toLowerCase();
+          if (help.includes('usage') || help.includes('quota')) {
+            out.quota = 'cli-supported';
+            out.hint = '`codex usage` 또는 `codex quota` 시도 가능';
+          } else {
+            out.quota = 'unknown';
+            out.hint = 'https://platform.openai.com/account/usage 확인';
+          }
+          out.raw = help.slice(0, 200);
+        } else if (agent.id === 'gemini') {
+          // gemini CLI: 무료 티어는 분당 60req 제한, CLI 자체에선 노출 안 됨
+          out.quota = 'rate-limited';
+          out.hint = '무료 티어: 60 req/min, 1000 req/day · 유료는 https://ai.google.dev/gemini-api/docs/rate-limits';
+        } else if (agent.id === 'copilot') {
+          // gh copilot은 GitHub Copilot 구독 (월 단위 quota 없음, individual/business 플랜)
+          const r = cp.spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 4000, shell: true });
+          const authed = r.status === 0;
+          out.quota = authed ? 'subscription' : 'not-authed';
+          out.hint = authed ? 'Copilot 구독자 무제한 (월 플랜) · https://github.com/settings/copilot' : '`gh auth login` 필요';
+        }
+      } catch (e) {
+        out.quota = 'error';
+        out.hint = e.message;
+      }
+      results.push(out);
+    }
+    if (has('--json')) { log(JSON.stringify({ quota: results }, null, 2)); return; }
+    log(`# 외부 AI CLI quota 추정 (1.9.31)`);
+    log('');
+    log(`| Agent | 상태 | quota | 안내 |`);
+    log(`|---|---|---|---|`);
+    for (const q of results) {
+      const statusEmoji = q.status === 'ready' ? '🟢' : q.status === 'not-installed' ? '⚪' : q.status === 'disabled' ? '🟡' : '❓';
+      log(`| ${q.id} | ${statusEmoji} ${q.status} | ${q.quota || '-'} | ${q.hint || '-'} |`);
+    }
+    log('');
+    log(`## 주의`);
+    log(`  - leerness는 CLI 사용량을 직접 추적하지 않음 (provider 대시보드 참조)`);
+    log(`  - rate-limit/quota는 plan/티어에 따라 달라짐`);
+    log(`  - sub-agent 분배 시 quota 여유 큰 CLI 우선 활용 권장`);
+    return;
+  }
+
+  fail('사용법: leerness agents list|check|quota|dispatch "<task>" --to <id>');
+  return process.exit(1);
+}
+
 function personaCmd(root, sub, idOrName, ...rest) {
   root = absRoot(root || process.cwd());
   if (!sub || sub === 'list') {
@@ -4452,7 +4633,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 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                # 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
   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)
@@ -4495,6 +4676,7 @@ async function main() {
   if (cmd === 'optimism-check') return optimismCheckCmd(arg('--path', process.cwd()), args[1]);
   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 === '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.29",
+  "version": "1.9.31",
   "description": "Leerness: 비파괴 마이그레이션, 자동 버전 감지·업데이트, 계획/진행/핸드오프 자동화, 게으름·시크릿·인코딩 자동 가드, Claude Code 슬래시 통합을 갖춘 한국어 우선 AI 개발 하네스.",
   "keywords": [
     "leerness",

package/scripts/e2e.js

@@ -794,6 +794,79 @@ total++;
   if (!ok) { failed++; console.log(r.stdout.slice(0, 400)); }
 }
 
+// 1.9.30 회귀: 외부 CLI 오케스트레이션 (agents list/check/dispatch)
+total++;
+{
+  // agents list — claude가 환경변수 + PATH 둘 다 충족 시 ready
+  const env1 = { ...process.env, LEERNESS_ENABLE_CLAUDE: '1', LEERNESS_ENABLE_CODEX: '0', LEERNESS_ENABLE_GEMINI: '0', LEERNESS_ENABLE_COPILOT: '0' };
+  const r1 = cp.spawnSync(process.execPath, [CLI, 'agents', 'list'], { encoding: 'utf8', timeout: 15000, env: env1 });
+  const okList = r1.status === 0
+    && /외부 AI CLI 오케스트레이션 \(1\.9\.30\)/.test(r1.stdout)
+    && /\| claude \|/.test(r1.stdout)
+    && /\| codex \|/.test(r1.stdout)
+    && /\| gemini \|/.test(r1.stdout)
+    && /\| copilot \|/.test(r1.stdout);
+  // env 모두 0 → 비활성
+  const env2 = { ...process.env, LEERNESS_ENABLE_CLAUDE: '0', LEERNESS_ENABLE_CODEX: '0', LEERNESS_ENABLE_GEMINI: '0', LEERNESS_ENABLE_COPILOT: '0' };
+  const r2 = cp.spawnSync(process.execPath, [CLI, 'agents', 'list', '--json'], { encoding: 'utf8', timeout: 15000, env: env2 });
+  let parsed = null;
+  try { parsed = JSON.parse(r2.stdout); } catch {}
+  const okJson = parsed && Array.isArray(parsed.agents) && parsed.agents.length === 4 && parsed.agents.every(a => a.status !== 'ready');
+  const ok = okList && okJson;
+  console.log(ok ? '✓ B(1.9.30) agents list: 4 CLI 정의 + env 0 시 모두 비활성' : `✗ agents list 실패 (list=${okList} json=${okJson})`);
+  if (!ok) { failed++; console.log(r1.stdout.slice(0, 500)); }
+}
+
+total++;
+{
+  // agents dispatch — 활성 미충족 시 거부
+  const env = { ...process.env, LEERNESS_ENABLE_CODEX: '0' };
+  const r = cp.spawnSync(process.execPath, [CLI, 'agents', 'dispatch', 'test task', '--to', 'codex'], { encoding: 'utf8', timeout: 10000, env });
+  const okBlocked = r.status !== 0 && /비활성|disabled|not-installed/i.test(r.stdout);
+  // --to 누락 거부
+  const r2 = cp.spawnSync(process.execPath, [CLI, 'agents', 'dispatch', 'test'], { encoding: 'utf8', timeout: 10000 });
+  const okNoTarget = r2.status !== 0 && /--to.*필요/.test(r2.stdout + r2.stderr);
+  // 알 수 없는 agent 거부
+  const r3 = cp.spawnSync(process.execPath, [CLI, 'agents', 'dispatch', 'test', '--to', 'jedi'], { encoding: 'utf8', timeout: 10000 });
+  const okBadAgent = r3.status !== 0 && /알 수 없는 agent/.test(r3.stdout + r3.stderr);
+  const ok = okBlocked && okNoTarget && okBadAgent;
+  console.log(ok ? '✓ B(1.9.30) agents dispatch: env=0/--to 누락/잘못된 agent 모두 거부' : `✗ dispatch 실패 (block=${okBlocked} noT=${okNoTarget} bad=${okBadAgent})`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 400)); }
+}
+
+// 1.9.31 회귀: agents quota (각 CLI 사용량/quota 조회)
+total++;
+{
+  // agents quota — env=0 시 모두 disabled/not-installed, 안내 메시지 포함
+  const env = { ...process.env, LEERNESS_ENABLE_CLAUDE: '0', LEERNESS_ENABLE_CODEX: '0', LEERNESS_ENABLE_GEMINI: '0', LEERNESS_ENABLE_COPILOT: '0' };
+  const r = cp.spawnSync(process.execPath, [CLI, 'agents', 'quota'], { encoding: 'utf8', timeout: 15000, env });
+  const okText = r.status === 0
+    && /외부 AI CLI quota 추정 \(1\.9\.31\)/.test(r.stdout)
+    && /\| claude \|/.test(r.stdout)
+    && /\| codex \|/.test(r.stdout)
+    && /\| gemini \|/.test(r.stdout)
+    && /\| copilot \|/.test(r.stdout)
+    && /provider 대시보드 참조/.test(r.stdout);
+  // JSON 출력
+  const r2 = cp.spawnSync(process.execPath, [CLI, 'agents', 'quota', '--json'], { encoding: 'utf8', timeout: 15000, env });
+  let parsed = null;
+  try { parsed = JSON.parse(r2.stdout); } catch {}
+  const okJson = parsed && Array.isArray(parsed.quota) && parsed.quota.length === 4
+    && parsed.quota.every(q => typeof q.id === 'string' && typeof q.status === 'string' && (q.hint === null || typeof q.hint === 'string'));
+  const ok = okText && okJson;
+  console.log(ok ? '✓ B(1.9.31) agents quota: 4 CLI 사용량/안내 + JSON 출력' : `✗ quota 실패 (text=${okText} json=${okJson})`);
+  if (!ok) { failed++; console.log(r.stdout.slice(0, 500)); }
+}
+
+total++;
+{
+  // 사용법 메시지에 quota 포함
+  const r = cp.spawnSync(process.execPath, [CLI, 'agents', 'foo'], { encoding: 'utf8', timeout: 10000 });
+  const ok = r.status !== 0 && /list\|check\|quota\|dispatch/.test(r.stdout + r.stderr);
+  console.log(ok ? '✓ B(1.9.31) agents 사용법에 quota 명시' : `✗ usage 메시지 실패`);
+  if (!ok) { failed++; console.log((r.stdout + r.stderr).slice(0, 300)); }
+}
+
 // 1.9.22 회귀: handoff --compact + orchestrate opt-in 정책 + llm-bench record
 total++;
 {