leerness 1.9.245 → 1.9.247

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## 1.9.247 — 2026-05-26 — UR-0016 2단계 + UR-0015 2단계
+
+**🔁 REPL multi-provider auto-fallback + 📚 api-skill audit 통합.**
+
+### 1. UR-0016 2단계 — REPL multi-provider auto-fallback
+사용자 보고 (1.9.246 스크린샷): `codex CLI 응답 실패 (exit=null)` → 멀티 provider auto-fallback 검토.
+
+**구현:**
+- `state.autoFallback` 필드 추가 (default OFF — opt-in)
+- 활성화: `:fallback on` (REPL slash) 또는 `LEERNESS_REPL_AUTO_FALLBACK=1` env
+- transient 실패 (`exit=null|timeout`) 감지 시 next ready agent 로 자동 전환 + 재시도 1회
+- 응답 헤더: `↪ auto-fallback (1.9.247): codex 실패 → claude 자동 전환 + 재시도 중...`
+- 성공 시 `✓ fallback 성공 [claude/...]`, 실패 시 친절한 진단 + 수동 :provider 안내
+
+### 2. UR-0015 2단계 — api-skill audit 통합
+사용자 명시 (UR-0015): *"AI가 정리해둔 파일이 참조되는지 확인"*
+
+**구현:**
+- `audit` 명령에 새 finding 추가: `api_skill_missing`
+- 현재 in-progress task 의 request/nextAction/evidence 에 API 키워드 (`API|endpoint|REST|GraphQL|OAuth|webhook|http[s]?://`) 감지
+- 매칭되는 api-skill 0건 → `warn` + `leerness api-skill add <url> --direction "..."` 안내
+- 매칭 1+건 → `✓ API skill 매칭 OK (현재 task → N건)` 로그
+- non-API task 는 영향 없음
+
+### 3. 누적 회귀 (1.9.207~246) — 모두 유지
+- REPL UX status bar (1.9.246) · api-skill cache (1.9.245) · _lastCycleLines HOTFIX (1.9.244)
+- CJK 분류 (1.9.243) · env encoding --apply (1.9.242) · 모두 유지
+- handoff JSON 11 필드 · MCP 70 도구 · agents dispatch 거부 회귀 (1.9.246 flake 방지) 검증
+
+### 4. stress-v192 — **20/20 PASS · 100%**
+- 1.9.247 (8): VERSION + autoFallback state + :fallback slash + 재시도 로직 + audit api_skill_missing + 실제 동작 (3 시나리오)
+- 성능 (1): cold start avg 588ms
+- 누적 회귀 (11): 1.9.207~246 + 보안 + e2e flake 방지
+
+### 5. 자동 release (109 main-push streak · 70 npm publish streak · R203)
+
+🔁 **사용자 실 환경 대응 보강** — 1.9.246 보고된 codex CLI exit=null 케이스 자동 회복 + 후속 API task UR-0015 자동 참조 확인.
+
+---
+
+## 1.9.246 — 2026-05-26 — UR-0016 REPL UX/UI 개선
+
+**🎯 사용자 명시 (UR-0016): REPL agent 채팅 입력칸 옆 컨텍스트 게이지 + 서브 에이전트 가시화 + 정상 완료 초록색 강조.**
+
+### 사용자 명시 (UR-0016)
+> *"REPL agent 모드의 기능과 UX UI를 개선해줘: 서브 에이전트 활성화 여부, 채팅입력칸 근처에는 컨텍스트 창 게이지 등 표시, 정상완료된 작업은 초록색 등으로 표시. 별도의 신규 프로젝트를 생성하여 직접 REPL agent 모드를 구동하여 유저가 사용하기 쉽게 개선해줘."*
+
+dogfood 검증: `C:\Users\leehy\AppData\Local\Temp\dogfood-1.9.246` 신규 프로젝트에서 `leerness init` + REPL 진입 흐름 직접 검증.
+
+### 1. 컨텍스트 창 게이지 (채팅 입력칸 직전 자동 표시)
+모든 prompt 호출 직전에 status bar 한 줄 자동 출력:
+```
+💬 ctx 12msg ~3.4k/200k ████░░░░░░░░░░ 1.7%  ·  agents: *claude ✓codex ·gemini ·copilot  ·  ▶stream
+```
+- `ctx Nmsg` — 누적 대화 메시지 수
+- `~XXk/YYk` — 추정 토큰 / provider별 컨텍스트 윈도우 (claude 200k, claude-4-7 1M, gpt-5 200k, gpt-4.1 1M, gemini 1M, copilot 64k, ollama 8k)
+- `████░░░░░░░░░░ %` — 14문자 progress bar (50% 이상 cyan, 80% 이상 yellow 경고)
+- 토큰 추정 휴리스틱: `chars / 3.5` (CJK/영문 평균치)
+
+### 2. 서브 에이전트 활성화 가시화 (한 줄 5종 표시)
+- `*claude` — 현재 활성 provider (bold + green)
+- `✓codex` — 설치+인증 완료 ready (green)
+- `·gemini` — 미설치 또는 비활성 (dim)
+- 5종 모두 한 줄에 표시 → 사용자가 즉시 다른 provider 가용성 인지 → Tab 키로 전환
+
+### 3. 정상 완료 작업 초록색 강조 (사용자 명시)
+- assistant 응답 헤더에 `✓` 마커 + `C.green()` 적용
+- stream 모드: `✓ [assistant: claude/sonnet-4-7, role=actor, 1234ms · 567자]` (green)
+- non-stream: `✓ assistant (claude, role=actor, 1234ms)` (green bold)
+- 기존 `[assistant: ...]` (dim) → `✓ [assistant: ...]` (green)
+
+### 4. dogfood 신규 프로젝트 직접 구동 검증
+- 임시 디렉토리에 빈 프로젝트 생성 → `leerness init` 정상 동작 확인
+- `leerness agent --interactive` 진입 흐름 검증 (provider 없음 시 안내 출력)
+- `--version` 등 핵심 명령 동작 확인
+
+### 5. promptWithStatus wrapper 도입
+- `rl.prompt()` 7회 호출처 모두 `promptWithStatus()` 로 통일
+- line handler / cycle / 초기 진입 등 일관된 status bar 노출
+- wrapper 내부 1건만 실제 `rl.prompt()` 호출 (DRY)
+
+### 6. 누적 회귀 (1.9.207~245) — 모두 유지
+- api-skill cache (1.9.245) + CJK 분류 (1.9.243) + env encoding --apply (1.9.242) + 모두 유지
+- handoff JSON 11 필드 · MCP 70 도구 · CJK + py-check + 비정상종료 모두 유지
+
+### 7. stress-v191 — **23/23 PASS · 100%**
+- 1.9.246 (11): VERSION + 4 helper + promptWithStatus + 컨텍스트 bar + sub-agent 가시화 + 초록색 ✓ + dogfood init + 통일성
+- 성능 (1): cold start avg 378ms
+- 누적 회귀 (11): 1.9.207~245
+
+### 8. 자동 release (108 라운드 main-push streak · 69 라운드 npm publish streak · R202)
+
+🎯 **REPL UX 사용자 요구 100% 반영** — 컨텍스트 + 에이전트 + 초록색 강조 통합 status bar.
+
+---
+
 ## 1.9.245 — 2026-05-26 — UR-0015 API skill cache
 
 **📚 사용자 명시 (UR-0015): API 문서/관련링크 자동 정리 + AI 자동 참조 시스템.**

package/README.md

@@ -2,7 +2,7 @@
 
 > **AI 코딩 에이전트의 거짓 완료·중복·망각·충돌을 막아주는 검수·기억·협업 CLI 하네스.**
 
-[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.245-green)]() [![tests](https://img.shields.io/badge/e2e-217%2F217-success)]() [![stress](https://img.shields.io/badge/stress--v190-26%2F26-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-70-brightgreen)]() [![cli](https://img.shields.io/badge/CLI_commands-57-brightgreen)]() [![json-fields](https://img.shields.io/badge/JSON_통합-11_필드-blueviolet)]() [![rounds](https://img.shields.io/badge/autonomous_R-201-blueviolet)]() [![main-push](https://img.shields.io/badge/🎉_main--push_streak-107_rounds-success)]() [![npm-streak](https://img.shields.io/badge/🎉_npm--publish-68_streak-success)]() [![api-skill](https://img.shields.io/badge/📚_API_skill_cache-UR--0015-blueviolet)]() [![perf](https://img.shields.io/badge/cold_start-331ms-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.247-green)]() [![tests](https://img.shields.io/badge/e2e-217%2F217-success)]() [![stress](https://img.shields.io/badge/stress--v192-20%2F20-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-70-brightgreen)]() [![cli](https://img.shields.io/badge/CLI_commands-57-brightgreen)]() [![json-fields](https://img.shields.io/badge/JSON_통합-11_필드-blueviolet)]() [![rounds](https://img.shields.io/badge/autonomous_R-203-blueviolet)]() [![main-push](https://img.shields.io/badge/🎉_main--push_streak-109_rounds-success)]() [![npm-streak](https://img.shields.io/badge/🎉_npm--publish-70_streak-success)]() [![fallback](https://img.shields.io/badge/🔁_REPL_fallback-multi--provider-blueviolet)]() [![perf](https://img.shields.io/badge/cold_start-588ms-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
 
 ```
   ╔══════════════════════════════════════════════════════════════╗
@@ -12,9 +12,9 @@
   ║  ██║     ██╔══╝  ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ╚════██║  ║
   ║  ███████╗███████╗███████╗██║  ██║██║ ╚████║███████╗███████║  ║
   ║  ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝  ║
-  ║  v1.9.245  AI Agent Reliability Harness + Sandbox            ║
+  ║  v1.9.247  AI Agent Reliability Harness + Sandbox            ║
   ║  verify · remember · orchestrate · audit · sandbox · drift   ║
-  ║  📚 API skill cache (UR-0015) — 공식 문서 자동 정리 + AI 참조  ║
+  ║  🔁 REPL multi-provider fallback + 📚 api-skill audit         ║
   ╚══════════════════════════════════════════════════════════════╝
 ```
 

package/bin/harness.js

@@ -7,7 +7,7 @@ const cp = require('child_process');
 const os = require('os');  // 1.9.178: _publishToNpm 에서 os.tmpdir() 사용 (전역 import)
 const readline = require('readline');
 
-const VERSION = '1.9.245';
+const VERSION = '1.9.247';
 
 // 1.9.184: DEP0190 (child_process shell: true) deprecation warning 억제 (사용자 명시).
 //   leerness 는 cross-platform PATH resolution 을 위해 shell: true 를 의도적으로 사용 (claude.cmd / ollama.cmd 등 Windows .cmd 처리).
@@ -6491,6 +6491,35 @@ function audit(root, opts = {}) {
       }
     } catch {}
   }
+  // 1.9.247 (UR-0015 2단계): api-skill 참조 audit — API 관련 task 인데 .harness/api-skills/ 미참조 시 경고
+  //   사용자 명시 (UR-0015): "AI가 정리해둔 파일이 참조되는지 확인"
+  //   현재 in-progress task 의 request/nextAction 에 API 키워드 (URL, "API", "endpoint", "REST", "GraphQL", "OAuth", "webhook") 있는데
+  //   _matchAPISkills() 결과가 0 이면 → 경고 + leerness api-skill add <url> 안내
+  try {
+    const rows = readProgressRows(root);
+    const ip = rows.find(r => r.status === 'in-progress');
+    if (ip) {
+      const taskText = (ip.request || '') + ' ' + (ip.nextAction || '') + ' ' + (ip.evidence || '');
+      const apiKeywords = /\bAPI\b|endpoint|REST|GraphQL|OAuth|webhook|https?:\/\/[^\s]+/i;
+      if (apiKeywords.test(taskText)) {
+        const matched = _matchAPISkills(root, taskText);
+        const allSkills = _listAPISkills(root);
+        if (matched.length === 0) {
+          warnings++;
+          warn(`API 관련 task 감지 (현재: "${(ip.request || '').slice(0, 60)}") — .harness/api-skills/ 매칭 0건 (저장 ${allSkills.length})`);
+          warn(`  → leerness api-skill add <url> --direction "구현 방향" 으로 정리 권장 (1.9.245 UR-0015 / 1.9.247 audit)`);
+          _finding('api_skill_missing', 'warn', 'API 관련 task 인데 .harness/api-skills/ 매칭 없음', {
+            taskRequest: (ip.request || '').slice(0, 100),
+            apiSkillsTotal: allSkills.length,
+            matched: 0,
+            hint: 'leerness api-skill add <url> --direction "..."'
+          });
+        } else {
+          ok(`API skill 매칭 OK (현재 task → ${matched.length}건 매칭 in .harness/api-skills/, 1.9.247 UR-0015 2단계)`);
+        }
+      }
+    }
+  } catch {}
   // 1.9.63: --strict — warnings ≥ threshold 시 failures로 승격 (CI 친화)
   if (has('--strict')) {
     const threshold = parseInt(arg('--threshold', '1'), 10);
@@ -16679,7 +16708,9 @@ async function _agentRepl(root, opts) {
     startedAt: new Date().toISOString(),
     sessionId: 'sess-' + new Date().toISOString().replace(/[:.]/g, '-'),
     // 1.9.170: 실시간 스트리밍 모드 (사용자 명시 — 추론중/diff/thinking 실시간 표시)
-    streamMode: opts.stream !== false  // default ON (env 로 끄려면 LEERNESS_REPL_STREAM=0)
+    streamMode: opts.stream !== false,  // default ON (env 로 끄려면 LEERNESS_REPL_STREAM=0)
+    // 1.9.247 (UR-0016 2단계): multi-provider auto-fallback — default OFF (opt-in)
+    autoFallback: opts.autoFallback === true || process.env.LEERNESS_REPL_AUTO_FALLBACK === '1'
   };
   if (process.env.LEERNESS_REPL_STREAM === '0') state.streamMode = false;
   const sessionPath = () => path.join(absRoot(root), '.harness', 'agent-sessions', `${state.sessionId}.jsonl`);
@@ -16802,6 +16833,74 @@ async function _agentRepl(root, opts) {
     const modelTag = modelShort ? C.dim(' · ') + C.mag(modelShort) : '';
     return C.cy(`agent[${state.provider}${modelTag}${C.cy('/' + state.role)}${state.streamMode ? C.cy('/▶') : ''}${C.cy(']>')} `);
   };
+  // 1.9.246: REPL UX/UI 개선 (사용자 명시 UR-0016) — 컨텍스트 게이지 + 서브 에이전트 가시화 + 정상 작업 강조
+  //   3종 통합 status bar를 채팅 입력칸 직전에 표시.
+  const _maxContextTokens = (provider, model) => {
+    // provider/model 별 컨텍스트 윈도우 (대략값, 사용자 정보 제공용)
+    const m = (model || '').toLowerCase();
+    if (provider === 'claude') {
+      if (m.includes('opus-4-7') || m.includes('sonnet-4-7') || m.includes('4-7')) return 1000000; // 1M extended
+      if (m.includes('opus') || m.includes('sonnet') || m.includes('haiku')) return 200000;
+      return 200000;
+    }
+    if (provider === 'codex' || provider === 'openai') {
+      if (m.includes('gpt-5') || m.includes('5.5')) return 200000;
+      if (m.includes('gpt-4-1') || m.includes('4.1')) return 1000000;
+      if (m.includes('gpt-4')) return 128000;
+      return 128000;
+    }
+    if (provider === 'gemini') return 1000000;       // 2M까지 가능하지만 보수적으로 1M
+    if (provider === 'copilot') return 64000;
+    if (provider === 'ollama') return 8000;          // 모델별 다르나 default 8k
+    return 100000;
+  };
+  const _estimateTokens = (history) => {
+    // 단순 휴리스틱: 영문 4chars=1tok, CJK 2chars=1tok 평균치 → 3.5chars/tok
+    let totalChars = 0;
+    for (const m of (history || [])) totalChars += (m.content || '').length;
+    return Math.round(totalChars / 3.5);
+  };
+  const _renderStatusBar = () => {
+    if (!isTty) return;
+    try {
+      // (1) 컨텍스트 게이지
+      const msgs = (state.history || []).length;
+      const tokens = _estimateTokens(state.history);
+      const maxTok = _maxContextTokens(state.provider, state.model);
+      const ratio = Math.min(1, tokens / maxTok);
+      const pct = Math.round(ratio * 100);
+      const barWidth = 14;
+      const filled = Math.round(ratio * barWidth);
+      const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+      const barColor = pct >= 80 ? C.yel : (pct >= 50 ? C.cy : C.green);
+      const tokStr = tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : `${tokens}`;
+      const maxStr = maxTok >= 1000 ? `${Math.round(maxTok / 1000)}k` : `${maxTok}`;
+      // (2) 서브 에이전트 활성화 — EXTERNAL_AGENTS 5종 + ollama
+      let ready = [];
+      try {
+        ready = EXTERNAL_AGENTS
+          .map(a => ({ id: a.id, st: _checkAgent(a).status }))
+          .filter(x => x.st === 'ready');
+      } catch {}
+      const allAgents = ['claude', 'codex', 'gemini', 'copilot'];
+      const subBar = allAgents.map(id => {
+        if (id === state.provider) return C.bold(C.green(`*${id}`));
+        const isReady = ready.find(r => r.id === id);
+        return isReady ? C.green(`✓${id}`) : C.dim(`·${id}`);
+      }).join(' ');
+      // (3) 한 줄 출력
+      const line = '  ' + C.dim('💬 ctx ') + C.bold(`${msgs}msg`) + C.dim(` ~${tokStr}/${maxStr} `) + barColor(bar) + C.dim(` ${pct}%`)
+                 + C.dim('  ·  agents: ') + subBar
+                 + C.dim('  ·  ') + (state.streamMode ? C.green('▶stream') : C.dim('□stream'));
+      process.stdout.write(line + '\n');
+    } catch {}
+  };
+  // 1.9.246: rl.prompt() wrapper — status bar 자동 표시 (사용자 명시 UR-0016)
+  const promptWithStatus = (forceRedraw) => {
+    _renderStatusBar();
+    if (forceRedraw === true) rl.prompt(true);
+    else rl.prompt();
+  };
   rl.setPrompt(prompt());
 
   // 1.9.244 HOTFIX: _lastCycleLines 를 outer 스코프로 hoist
@@ -16963,7 +17062,8 @@ async function _agentRepl(root, opts) {
     log(C.dim('  💡 메시지는 직접 입력 · "/" 또는 ":" 접두사로 명령 호출 · Tab=provider · Shift+Tab=model'));
     log('');
   };
-  rl.prompt();
+  // 1.9.246: 첫 prompt 표시 전에도 status bar 노출 (사용자 명시 UR-0016)
+  promptWithStatus();
   const handleMeta = async (cmd) => {
     const [op, ...rest] = cmd.slice(1).split(/\s+/);
     if (op === 'quit' || op === 'exit' || op === 'q') {
@@ -17098,6 +17198,20 @@ async function _agentRepl(root, opts) {
       rl.setPrompt(prompt());
       return false;
     }
+    // 1.9.247 (UR-0016 2단계): :fallback on|off — provider 실패 시 다음 ready agent 자동 전환 (opt-in)
+    if (op === 'fallback') {
+      const v = (rest[0] || '').toLowerCase();
+      if (v === 'on' || v === '1' || v === 'true') {
+        state.autoFallback = true;
+        log(C.green('  ↪ auto-fallback: ON (1.9.247) — 현재 provider transient 실패 (timeout/exit=null) 시 다음 ready agent 자동 전환 + 재시도'));
+      } else if (v === 'off' || v === '0' || v === 'false') {
+        state.autoFallback = false;
+        log(C.dim('  ↪ auto-fallback: OFF — 실패 시 사용자가 직접 :provider 전환'));
+      } else {
+        log(C.dim(`  현재 auto-fallback: ${state.autoFallback ? 'ON ↪' : 'OFF'}  — 사용: :fallback on|off`));
+      }
+      return false;
+    }
     if (op === 'clear') { process.stdout.write('\x1b[2J\x1b[H'); return false; }
     if (op === 'reset') { state.history = []; log(C.dim('  history 초기화됨')); return false; }
     if (op === 'history') {
@@ -17253,24 +17367,24 @@ async function _agentRepl(root, opts) {
     rl.on('line', async (line) => {
       const input = line.trim();
       _lastCycleLines = 0;  // 1.9.189: 사용자 입력 시 cycle overwrite 추적 reset
-      if (!input) { rl.prompt(); return; }
+      if (!input) { promptWithStatus(); return; }
       // 1.9.189 (사용자 명시): "/" slash 입력만으로 명령 list 표시 (claude code 영감).
       //   "/" 단독 → 명령 list 출력 후 prompt 복귀.
       //   "/help", "/quit" 등 "/" 접두사 → ":" 동등 처리 (alias).
       if (input === '/' || input === '/?') {
         _showSlashCommandList();
-        rl.prompt(); return;
+        promptWithStatus(); return;
       }
       // 1.9.189: "/" 접두사를 ":" 와 동등하게 처리 (사용자 명시 — "/ 가 모든 모델 공통 권한 trigger default")
       if (input.startsWith('/') && !input.startsWith('//')) {
         const shouldQuit = await handleMeta(':' + input.slice(1));
         if (shouldQuit) { resolve(); return; }
-        rl.prompt(); return;
+        promptWithStatus(); return;
       }
       if (input.startsWith(':')) {
         const shouldQuit = await handleMeta(input);
         if (shouldQuit) { resolve(); return; }
-        rl.prompt(); return;
+        promptWithStatus(); return;
       }
       // LLM 호출
       state.history.push({ role: 'user', content: input });
@@ -17293,18 +17407,19 @@ async function _agentRepl(root, opts) {
         }
       } else {
         log(C.yel(`  ⚠ ${state.provider} provider 미지원 — :provider ollama|claude|codex|gemini|copilot`));
-        rl.prompt(); return;
+        promptWithStatus(); return;
       }
       const dt = Date.now() - t0;
       _recordRun(root, { kind: 'agent_repl_turn', provider: state.provider, model: state.model, role: state.role, durationMs: dt, ok: result.ok, error: result.error, promptChars: finalPrompt.length, responseChars: (result.response || '').length });
       if (result.ok) {
         state.history.push({ role: 'assistant', content: result.response });
         // 1.9.170: stream 모드에서는 이미 실시간으로 출력됐으므로 헤더만 표시 (응답 중복 방지)
+        // 1.9.246: 정상 완료 작업은 초록색 ✓ 강조 (사용자 명시 UR-0016)
         if (state.streamMode && ['claude', 'codex', 'gemini', 'copilot'].includes(state.provider)) {
-          log(C.dim(`  [assistant: ${state.provider}/${state.model || 'default'}, role=${state.role}, ${dt}ms · ${result.response.length}자]`));
+          log(C.green(`  ✓ [assistant: ${state.provider}/${state.model || 'default'}, role=${state.role}, ${dt}ms · ${result.response.length}자]`));
         } else {
           log('');
-          log(C.bold(`assistant (${state.model || state.provider}, role=${state.role}, ${dt}ms)`));
+          log(C.green(`✓ assistant (${state.model || state.provider}, role=${state.role}, ${dt}ms)`));
           log(result.response);
         }
         // 1.9.188 (사용자 명시): 응답 끝 + 입력 구분선 (입력칸 시각 명확)
@@ -17323,6 +17438,47 @@ async function _agentRepl(root, opts) {
           log(C.dim(`     ↳ 가능 원인: 인증 누락 (login 필요)`));
           log(C.dim(`     ↳ 해결: ${state.provider} login ${state.provider === 'copilot' ? '(gh auth login)' : ''}`));
         }
+        // 1.9.247 (UR-0016 2단계): 자동 fallback — 사용자 명시 (`:fallback on` 또는 LEERNESS_REPL_AUTO_FALLBACK=1) 시
+        //   현재 provider 가 transient 실패 (timeout/exit=null/network) 시 다음 ready agent 로 자동 전환 + 1회 재시도.
+        //   사용자 명시 (이전 codex CLI exit=null 보고): "멀티 provider auto-fallback 도 검토".
+        const isTransient = /exit=null|timeout/i.test(errMsg);
+        if (state.autoFallback && isTransient) {
+          try {
+            const others = EXTERNAL_AGENTS.filter(a => a.id !== state.provider)
+                                           .map(a => ({ def: a, status: _checkAgent(a) }))
+                                           .filter(x => x.status.status === 'ready');
+            if (others.length > 0) {
+              const next = others[0].def.id;
+              log(C.green(`  ↪ auto-fallback (1.9.247): ${state.provider} 실패 → ${next} 자동 전환 + 재시도 중...`));
+              state.provider = next;
+              state.model = null;
+              const cat = _PROVIDER_MODEL_CATALOG[state.provider];
+              if (cat && cat.length) state.model = cat[0].id;
+              rl.setPrompt(prompt());
+              const t1 = Date.now();
+              let retry;
+              if (state.streamMode) retry = await _cliChatStream(root, state.provider, finalPrompt, { timeout: 120000 });
+              else retry = await _cliChat(root, state.provider, finalPrompt, { timeout: 90000 });
+              const dt1 = Date.now() - t1;
+              _recordRun(root, { kind: 'agent_repl_turn_fallback', provider: state.provider, model: state.model, role: state.role, durationMs: dt1, ok: retry.ok, error: retry.error, promptChars: finalPrompt.length, responseChars: (retry.response || '').length });
+              if (retry.ok) {
+                state.history.push({ role: 'assistant', content: retry.response });
+                log(C.green(`  ✓ fallback 성공 [${state.provider}/${state.model || 'default'}, ${dt1}ms · ${retry.response.length}자]`));
+                if (!state.streamMode) log(retry.response);
+                _printInputDivider();
+                if (state.history.length % 6 === 0) saveSession();
+                promptWithStatus();
+                return;
+              } else {
+                log(C.yel(`  ⚠ fallback 도 실패 (${next}): ${retry.error || 'unknown'}`));
+              }
+            } else {
+              log(C.dim(`     (auto-fallback: 다른 ready provider 없음)`));
+            }
+          } catch (e) {
+            log(C.dim(`     (auto-fallback 오류: ${e.message})`));
+          }
+        }
         // 전환 가능 provider 안내
         try {
           const others = EXTERNAL_AGENTS.filter(a => a.id !== state.provider)
@@ -17330,12 +17486,13 @@ async function _agentRepl(root, opts) {
                                          .filter(x => x.status.status === 'ready');
           if (others.length) {
             log(C.dim(`     💡 즉시 전환: ${others.map(x => `:provider ${x.def.id}`).join(' · ')}  또는 Tab 키`));
+            if (!state.autoFallback) log(C.dim(`     💡 다음 실패 시 자동 전환: \`:fallback on\` (1.9.247 UR-0016 2단계)`));
           } else {
             log(C.dim(`     💡 다른 provider 활성화: .env 에서 LEERNESS_ENABLE_<CLAUDE|CODEX|GEMINI|COPILOT>=1`));
           }
         } catch {}
       }
-      rl.prompt();
+      promptWithStatus();
     });
     rl.on('close', () => { saveSession(); resolve(); });
   });

package/package.json

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