@tuzi-ince/hi-loop 0.4.1 → 0.4.3

package/README.md

@@ -487,6 +487,20 @@ MCP 도구의 `cwd` 기본값은 `CLAUDE_PROJECT_DIR || process.cwd()` 다 —
 반대로 순수 `process.cwd()` — 터미널에서 cd한 곳이 사용자의 명시 의도이고, 통합 터미널에
 새어든 env가 그것을 덮으면 하위 프로젝트 겨냥이 깨지기 때문이다.)
 
+### 🛑 실패를 어떻게 멈출까 — 카운트 대신 사람 판단 (`--on-fail`)
+
+기본은 `--max-loops`(10)까지 자동 치유다(무인 환경 백스톱). 하지만 대화형·비싼 검사(e2e)에서는
+카운트보다 **사람 판단**이 낫다 — `--on-fail` 로 정한다:
+
+| 값 | 동작 |
+|---|---|
+| `heal` (기본) | `--max-loops` 안에서 자동 치유 (종전) |
+| `stop` | 첫 실패에서 즉시 종료 |
+| **`ask`** | 실패/불능에서 **"재시도할까 / 종료할까"를 사람에게 물음** (pause/resume). MCP 에선 `awaiting` 반환 → `hiloop_answer` 로 답하고 재호출 |
+
+`ask` 는 비싼 e2e 루프에 특히 유용하다 — 8.5분·수달러짜리 회차를 무인으로 반복하지 않고,
+**판정 불능(무결성·환경)**까지 사람에게 표면화한다. 무인(`--ask never`)에선 물을 수 없으니 안전하게 종료한다.
+
 ### 💸 비용은 엔진이 센다 — 그리고 싸지 않다
 
 **`--max-loops` 는 비용 상한이 아니다.** 실패 루프가 10회를 다 쓰면 비용이 크게 뛸 수 있다.

package/bin/hi-loop.js

@@ -27,7 +27,8 @@ const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
 
 사용법:
   hi-loop run --goal "<요구사항>" [--test "npm test"] [--max-loops 10] [--budget-usd 5]
-               [--stagnation 3 | --no-stagnation] [--verify-spec] [--spec docs/DESIGN.md] [--cwd .]
+               [--stagnation 3 | --no-stagnation] [--on-fail heal|ask|stop] [--verify-spec]
+               [--spec docs/DESIGN.md] [--cwd .]
                [--ship "<배포 명령>"] [--on-ship-fail stop|heal]
                [--review | --no-review] [--max-review-rounds 2]
                [--design-review | --no-design-review] [--max-design-rounds 2]

package/docs/SPEC.md

@@ -100,7 +100,8 @@ runLoop({
   - **한계**: 이것은 관측이지 강제가 아니다. 엔진은 CLI를 spawn할 뿐 에이전트의 쓰기를
     가로챌 수 없다(DESIGN.md L8).
 - FR-2.4 **ACT(HEAL)**: 실패 시 stdout/stderr 마지막 4000자를 잘라 에이전트에 들이밀고
-  "이 에러를 고쳐라"로 재지시. `maxLoops`(기본 10)까지 반복.
+  "이 에러를 고쳐라"로 재지시. `maxLoops`(기본 10)까지 반복. 대화형에선 `--on-fail ask`(FR-22)로
+  자동 반복 대신 사람이 재시도·종료를 정할 수 있다.
 - FR-2.5 CHECK가 통과하면 즉시 종료하고 `status: 'passed'`.
 - FR-2.5a **Gaps 공개 (L10).** `passed` 시 결과에 `report`(Evidence + Gaps)를 붙이고
   로거로 출력한다. moai의 5-섹션 규약 중 핵심인 Gaps를 담는다.
@@ -222,7 +223,7 @@ runLoop({
 - FR-4.3 노출 도구:
   | tool | input | 동작 |
   |---|---|---|
-  | `hiloop_run` | `goal`(필수), `testCommand?`, `maxLoops?`, `verifySpec?`, `spec?`, `reconcile?`, `reconcileSpec?`, `checks?`, `cwd?` | 루프 실행 후 결과 텍스트 반환. `budgetUsd`·`stagnation`은 노출 안 함(CLI 전용). `checks`=`[{cmd,when?}]` 조건부 검사(CLI `--check/--when` 의 MCP 노출) — UI 변경 회차에만 e2e 같은 게이트를 **엔진이 강제**한다 |
+  | `hiloop_run` | `goal`(필수), `testCommand?`, `maxLoops?`, `verifySpec?`, `spec?`, `reconcile?`, `reconcileSpec?`, `checks?`, `onFail?`, `cwd?` | 루프 실행 후 결과 텍스트 반환. `budgetUsd`·`stagnation`은 노출 안 함(CLI 전용). `checks`=`[{cmd,when?}]` 조건부 검사(UI 변경 회차에만 e2e 등 **엔진 강제**). `onFail`=`heal\|ask\|stop`(FR-22, 실패 시 사람에게 물음) |
   | `hiloop_status` | `cwd?` | 현재 `.hi-loop/STATE.json` 요약 반환 |
   | `hiloop_reset` | `cwd?` | 상태 파일 삭제 |
 - FR-4.4 도구 오류는 예외를 던지지 않고 `isError: true` + 메시지로 반환한다.
@@ -232,6 +233,10 @@ runLoop({
   를 명시하면 그것이 최우선. (CLI 는 이와 달리 순수 `process.cwd()` — 터미널에서 cd 한 곳이
   사용자의 명시 의도이고, 통합 터미널에 새어든 env 가 그것을 덮으면 하위 프로젝트 겨냥이 깨진다.)
 - FR-4.7 `hiloop_run` 은 루프 진입 전 에이전트 preflight(FR-20)를 거친다.
+- FR-4.8 **진행 알림(progress).** `hiloop_run` 은 루프가 도는 동안 회차마다 `notifications/progress`
+  를 보낸다(클라이언트가 progressToken 을 준 경우). 이게 없으면 e2e 같은 긴 루프가 클라이언트
+  유휴 타임아웃(기본 30분)에 조용히 끊긴다. `wrap()` 이 SDK `extra`(progress·signal)를 핸들러에
+  전달하고, 핸들러가 로그 라인마다 알림을 보낸다. 알림 실패는 루프에 영향 없다(fail-open).
 
 ### FR-5. 텔레그램 알림 (`src/telegram.js`)
 
@@ -444,6 +449,23 @@ DISCOVER → PLAN → DESIGN_REVIEW → DO ⇄ CHECK ⇄ HEAL → CODE_REVIEW
 - FR-21.6 결정은 `state.reconciled` 로 기록해 같은 goal 재개 시 다시 묻지 않는다. 답한 재개는
   판정기를 재호출하지 않는다(gate 가 저장된 답을 돌려준다).
 
+### FR-22. on-fail 게이트 — 카운트 대신 사람 판단 (`--on-fail`, `src/build.js`)
+
+무인 자동 치유는 대화형·비싼 검사(e2e)에서 폭주하거나 헛돈다(실측: git 미추적 무결성 위반을
+8.5분×회차 자동 재시도). 카운트만으로는 "언제 멈출지"를 모른다. 그래서 대화형에서는 **사람 판단**을
+멈춤 기준으로 쓸 수 있게 한다(카운트 기본값 `maxLoops`는 종전 10 그대로 — 이건 무인 환경용 백스톱).
+
+- FR-22.1 `--on-fail heal|ask|stop` (기본 `heal`). CHECK 실패 시 안쪽 루프 처리:
+  - `heal`: 종전대로 `maxLoops` 안에서 자동 치유(기존 동작 불변).
+  - `stop`: 첫 실패에서 즉시 종료(`stopReason: on-fail-stop`).
+  - `ask`: **사람에게 재시도/종료를 묻는다**(pause/resume, FR-16). `awaiting` 반환 → `hiloop_answer`
+    로 답하고 재호출. 'a'=재시도(회차 +1, `state.extraLoops`), 'b'=종료(`user-stop`).
+- FR-22.2 **PLAN 회차(1)는 게이트 제외** — 구현 전이라 실패가 당연하다(DO 로 넘어간다).
+- FR-22.3 **판정 불능(blocked) 구분**: 무결성 위반·비회귀 같은 메타 문제는 자동 수정이 대개
+  무의미하다. ask 질문이 "실패"가 아니라 **"불능"**으로 표시돼 사람이 알아채게 한다.
+- FR-22.4 **무인 안전**: `--ask never`(물을 사람 없음)에서 `on-fail ask` 는 pause 하지 않고
+  안전하게 종료한다 — 답을 못 받는데 멈춰 있으면 무한/폭주가 된다.
+
 ---
 
 ## 3. 비기능 요구사항

package/docs/guide.md

@@ -122,7 +122,11 @@ hi-loop-setup               # 실제 적용
 
 ## 4. 사용법
 
-### 4-1. CLI 직접 실행 (사람 / 데몬 / 텔레그램 봇)
+> **주 경로는 MCP(§4-2)다.** 대부분은 코드 어시스턴트(클로드코드·커서)가 `hiloop_run` 같은
+> **MCP 도구로 hi-loop 을 부른다.** CLI(§4-1)는 사람이 터미널에서·데몬·봇·CI 로 직접 구동할 때 쓴다.
+> 두 경로는 **같은 엔진·같은 상태 머신**을 쓰므로 동작은 동일하다 — 인터페이스만 다르다.
+
+### 4-1. CLI 직접 실행 (사람 / 데몬 / 텔레그램 봇 / CI)
 
 ```bash
 hi-loop run --goal "JWT 인증 미들웨어를 만들어라" \
@@ -135,7 +139,8 @@ hi-loop run --goal "JWT 인증 미들웨어를 만들어라" \
 |---|---|---|---|
 | `--goal` | `-g` | (필수) | 달성할 요구사항 |
 | `--test` | `-t` | `npm test` | 성패를 판정할 명령 |
-| `--max-loops` | `-m` | `10` | 최대 루프(=에이전트 호출) **횟수** 상한 |
+| `--max-loops` | `-m` | `10` | 최대 루프(=에이전트 호출) **횟수** 상한 (무인 환경 백스톱) |
+| `--on-fail` | — | `heal` | CHECK 실패/불능 시: `heal`(자동 치유) / `ask`(사람에게 재시도·종료 물음) / `stop`(즉시 종료). 대화형·비싼 e2e 에선 `ask` 권장 |
 | `--budget-usd` | — | (없음=무제한) | 누적 **비용** 상한(USD). 넘으면 다음 호출 전에 중단 |
 | `--stagnation` | — | `3` | 같은 실패가 이 횟수 연속이면 조기 종료. `--no-stagnation` 으로 끔 |
 | `--verify-spec` | — | (꺼짐) | 통과 후 별도 검증자로 스펙 대비 구현을 심판 (하향 전용, 비용 증가) |
@@ -163,6 +168,21 @@ hi-loop status              # 현재 루프 상태 요약 (누적 비용·정체
 hi-loop --help
 ```
 
+> **실패 시 자동 반복 대신 사람에게 물음 (`--on-fail ask`)**: 대화형·비싼 e2e 에서 무인 자동
+> 치유가 폭주하는 걸 막는다. CHECK 실패/불능에서 루프가 **멈추고 재시도/종료를 묻는다**(exit 3).
+> `heal`(기본, 자동 치유) 동작은 그대로다. 무인(`--ask never`)에선 물을 수 없으니 안전하게 종료한다.
+>
+> ```bash
+> hi-loop run --goal "..." --test "cd frontend && npx playwright test" --on-fail ask
+>   # ❌ 테스트 실패 → ⏸ 선택이 필요합니다 [ON_FAIL:2]
+>   #    계속 진행할까요?  a) 재시도  b) 종료
+>   # → hi-loop answer <a|b>          (exit 3)
+>
+> hi-loop answer a                    # 재시도 → 같은 goal 로 run 을 다시 호출하면 이어서 진행
+> ```
+> MCP 에선 `hiloop_run({ goal, onFail: "ask" })` → `awaiting` 반환 → `hiloop_answer` 로 답하고 재호출.
+> 판정 불능(무결성·환경)일 땐 질문이 "실패"가 아니라 **"불능"**으로 표시돼 사람이 알아챈다.
+
 > **문서↔소스 정합 (`--spec` / `--reconcile`)**: 기본적으로 이 엔진의 스펙·테스트는 에이전트
 > **자신이** 쓴 것이라, 통과가 "자기 테스트를 통과"에 그칠 수 있다(완료 보고의 Gaps 가 이를 공개한다).
 > 사람이 관리하는 표준 문서(`docs/DESIGN.md`, `hi-loop-setup` 이 만든다)를 오라클로 세우면 그 한계를 좁힌다:
@@ -254,21 +274,57 @@ hi-loop rollback --cwd .    # 작업 대상 지정
   안전망 스냅샷으로 한 번 더 떠두므로, 롤백 자체를 잘못 눌러도 다시 앞으로 갈 수 있다.
 - git 저장소가 아니면 체크포인트가 없으니 롤백도 조용히 no-op이다.
 
-### 4-2. MCP 서버 (클로드코드 / 커서)
+### 4-2. MCP 서버 (클로드코드 / 커서) — **주 사용 경로 (권장)**
 
-`hi-loop-setup` 후 에이전트를 재시작하면 도구 6개가 뜬다.
+대부분의 사용은 CLI 가 아니라 **코드 어시스턴트(클로드코드·커서)가 MCP 도구로 hi-loop 을 부르는**
+방식이다. `hi-loop-setup` 후 에이전트를 재시작하면 도구 6개가 뜬다.
 
 | 도구 | 인자 | 용도 |
 |---|---|---|
-| `hiloop_run` | `goal`(필수), `testCommand`, `maxLoops`, `verifySpec`, `full`, `ship`, `watch`, `stopAfter`, `spec`, `reconcile`, `reconcileSpec`, `checks`, `cwd` | 자가 치유(+전과정) 루프 실행 |
+| `hiloop_run` | `goal`(필수), `testCommand`, `maxLoops`, `verifySpec`, `full`, `ship`, `watch`, `stopAfter`, `spec`, `reconcile`, `reconcileSpec`, `checks`, `onFail`, `cwd` | 자가 치유(+전과정) 루프 실행 |
 | `hiloop_answer` | `choice`, `note`, `cwd` | 대기 중인 질문에 답하고 재개 가능 상태로 되돌림 |
 | `hiloop_status` | `cwd` | 진행 상태 조회 (장시간 루프를 들여다보는 창) |
 | `hiloop_rollback` | `to`, `cwd` | 체크포인트로 파일 복원 |
 | `hiloop_reset` | `cwd` | `.hi-loop/STATE.json` 초기화 |
 | `hiloop_setup` | `dryRun`, `cwd` | 프로젝트 설정 주입 |
 
+#### 기본 흐름 — 실행 → 진행 → (필요 시) 멈춤·재개
+
+```
+hiloop_run({ goal, testCommand, cwd })
+   │  루프가 도는 동안 회차마다 progress 알림을 보낸다(아래 참조) → 클라이언트가 안 끊긴다
+   ├─▶ ✅ 통과   → 결과 텍스트 + Gaps(검증 한계) 반환. 끝.
+   ├─▶ ❌ 실패   → 실패 요약 반환(heal 기본은 maxLoops 까지 자동 치유 후).
+   └─▶ ⏸ awaiting → **사람의 선택이 필요**. 질문을 사용자에게 그대로 제시하고,
+                    hiloop_answer({ choice }) 로 답한 뒤 **같은 goal 로 hiloop_run 을 다시 호출**해 이어간다.
+```
+
+**멈춤·재개(ask)는 MCP 의 핵심 패턴이다.** MCP 는 단일 요청/응답이라 서버가 사람을 기다릴 수 없다.
+그래서 hi-loop 은 **상태를 저장하고 `awaiting` 으로 반환**한다(차단 안 함). 멈추는 지점은 셋:
+- **DISCOVER 분기**(상호배타 선택), **SHIP 직전**(비가역 배포), **on-fail ask**(테스트 실패/불능).
+- 어느 경우든 `hiloop_run` 이 `⏸ 사용자의 선택이 필요합니다 …` 를 반환한다 → 그 질문을 사용자에게
+  보여주고 → `hiloop_answer({ choice: "a" })` → **같은 goal 로 `hiloop_run` 재호출**하면 그 지점부터 잇는다.
+
+#### 실패를 사람이 통제하기 — `onFail: "ask"` (대화형·비싼 e2e 권장)
+
+기본(`heal`)은 `maxLoops` 까지 무인 자동 치유다. 대화형에서 비싼 e2e 를 무인으로 반복시키지 않으려면:
+
+```js
+hiloop_run({ goal: "...", testCommand: "cd frontend && npx playwright test", onFail: "ask" })
+//  ❌ 실패/불능 → ⏸ awaiting "재시도할까요 / 종료할까요?"
+hiloop_answer({ choice: "a" })   // a=재시도, b=종료
+//  → 같은 goal 로 hiloop_run 재호출하면 한 회차 더 돌린다
+```
+판정 불능(무결성·환경)일 땐 질문이 "실패"가 아니라 **"불능"**으로 표시된다.
+
+#### 긴 루프가 안 끊긴다 — progress 알림
+
+`hiloop_run` 은 루프가 도는 동안 **회차마다 진행 알림(`notifications/progress`)을 보낸다.** 그래서
+e2e 처럼 오래 걸리는 루프도 클라이언트 유휴 타임아웃(기본 30분)에 조용히 끊기지 않는다. 그럼에도
+매우 긴 무인 루프를 돌릴 땐, `hiloop_run` 대신 한 번 던지고 **`hiloop_status` 로 폴링**하는 편이 안전하다.
+
 > MCP `hiloop_run`은 CLI와 달리 `--budget-usd`·`--stagnation`을 노출하지 않는다.
-> 예산 상한이 필요하면 CLI(`hi-loop run`)를 쓴다. 정체 감지는 기본값(3회)으로 동작한다.
+> 예산 상한이 꼭 필요하면 CLI(`hi-loop run`)를 쓴다. 정체 감지는 기본값(3회)으로 동작한다.
 
 > **UI 변경 회차에만 e2e 를 엔진이 강제하기 (`checks`).** `checks: [{cmd, when?}]` 를 주면
 > `testCommand` 대신 이 배열이 판정 기준이 되고, `when` 글롭에 맞는 파일이 바뀐 회차에만 그 검사를

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuzi-ince/hi-loop",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "CLI와 MCP 모드를 지원하는 초경량 자율형 자가 치유 엔진",
   "type": "module",
   "license": "MIT",

package/src/ask.js

@@ -123,6 +123,18 @@ export function applyAnswer(state, { choice, note = '', now = new Date().toISOSt
   };
 }
 
+/** FR-22 on-fail 게이트 질문 스펙 (재시도/종료). createAsk 에 그대로 넘긴다. */
+export function onFailAsk({ stage, blocked, summary }) {
+  return {
+    stage,
+    question: `${blocked ? '⚠️ 테스트를 판정할 수 없습니다(불능).' : '테스트가 실패했습니다.'}\n${summary}\n계속 진행할까요?`,
+    options: [
+      { key: 'a', label: '재시도 — 수정하고 한 번 더 돌린다', impact: '회차·비용 추가' },
+      { key: 'b', label: '종료 — 여기서 멈춘다', impact: '지금까지의 산출물은 남는다' },
+    ],
+  };
+}
+
 /** 에이전트가 스스로 세운 가정을 기록한다 (policy=never 또는 분기가 아닌 모호성). */
 export function recordAssumption(state, { text, stage, now = new Date().toISOString() }) {
   const clean = String(text ?? '').trim();

package/src/build.js

@@ -46,10 +46,12 @@ function addCost(prev, delta) {
 
 export async function runBuildLoop(ctx) {
   const { goal, cwd, logger, notify, statePath, baselineFiles, designReviewEnabled, ports, opts } = ctx;
-  const { maxLoops, budgetUsd, testCommand, stagnationLimit, verifySpec, handoffEvery, maxDesignRounds, stopAfter } = opts;
+  const { maxLoops, budgetUsd, testCommand, stagnationLimit, verifySpec, handoffEvery, maxDesignRounds, stopAfter, onFail, askPolicy } = opts;
   const { agentRunner, testRunner, integrityChecker, checkpointer, fileLister, specVerifier, designReviewer, treeKeyReader } = ports;
   // state 는 이 루프에서 속성만 바뀌고 재대입되지 않는다 — 참조를 그대로 잡아도 안전하다.
   const state = ctx.state;
+  // FR-22: on-fail ask 로 사용자가 "재시도"를 고른 만큼 회차 상한이 늘어난다(사람이 곧 상한).
+  const cap = () => maxLoops + (state.extraLoops || 0);
 
     state.stage = 'BUILD';
     state.status = 'running';
@@ -61,7 +63,14 @@ export async function runBuildLoop(ctx) {
     }
     saveState(statePath, state);
 
-    while (state.iteration < maxLoops) {
+    // FR-22 재개: 직전 실패에서 on-fail ask 로 물었던 답을 처리한다('a'=재시도→회차 +1, 'b'=종료).
+    const pendingFail = [...(state.answers ?? [])].find((a) => a.stage === `ON_FAIL:${state.iteration}`);
+    if (pendingFail) {
+      if (pendingFail.choice === 'a') state.extraLoops = (state.extraLoops || 0) + 1;
+      else return { ok: false, stopReason: 'user-stop', detail: '사용자가 종료를 선택했습니다.' };
+    }
+
+    while (state.iteration < cap()) {
       // 예산은 **다음 호출 앞**에서 막는다. 이미 쓴 돈은 되돌릴 수 없으므로
       // 할 수 있는 일은 "더 쓰지 않는 것"뿐이다.
       if (budgetUsd != null && state.costUsd >= budgetUsd) {
@@ -206,6 +215,21 @@ export async function runBuildLoop(ctx) {
       state.lastError = truncate(failure, LIMITS.lastError);
       state.phase = 'ACT';
 
+      // ---- FR-22 on-fail 게이트 ----
+      // 실패/불능을 사람에게 물을지·즉시 멈출지. PLAN 회차(1)는 제외한다(구현 전이라 실패가 당연).
+      // heal(기본)은 이 블록을 건너뛰어 종전대로 자동 치유한다 — 기존 동작 불변.
+      if (state.iteration >= 2 && onFail !== 'heal') {
+        const blocked = !integrity.ok || regressed.length > 0; // 판정 불능/메타 문제(무결성·비회귀)
+        // stop, 또는 물을 수 없는 환경(ask never)은 안전하게 종료 — 무인 폭주 방지.
+        if (onFail === 'stop' || askPolicy === 'never') {
+          saveState(statePath, state);
+          return { ok: false, stopReason: 'on-fail-stop', detail: truncate(state.lastError, 500) };
+        }
+        // ask: 사람에게 재시도/종료를 묻는다. pause 신호만 반환하고 loop.js 가 ask 를 세팅한다.
+        saveState(statePath, state);
+        return { paused: true, onFail: { stage: `ON_FAIL:${state.iteration}`, blocked, summary: truncate(state.lastError, 400) } };
+      }
+
       // ---- 정체 감지 (L2) ----
       // 같은 실패가 stagnationLimit 회 연속이면 이 접근으로는 못 고친다는 뜻 —
       // 같은 값을 태우며 maxLoops 를 다 쓰는 것은 순수한 낭비다(실측: 함정에 $3.07).
@@ -236,7 +260,7 @@ export async function runBuildLoop(ctx) {
         logger(`[hi-loop] ❌ 테스트 실패 (code ${check?.code}) — 치유를 시도합니다.`);
       }
 
-      if (stagnationLimit != null && state.stagnantRuns >= stagnationLimit && state.iteration < maxLoops) {
+      if (stagnationLimit != null && state.stagnantRuns >= stagnationLimit && state.iteration < cap()) {
         logger(`[hi-loop] 🔁 같은 실패가 ${state.stagnantRuns}회 반복 — 접근이 막혔습니다. ${state.iteration}회차에서 중단합니다. (누적 $${state.costUsd.toFixed(2)})`);
         return {
           ok: false,
@@ -246,7 +270,7 @@ export async function runBuildLoop(ctx) {
       }
 
       // ---- 세션 핸드오프 & 컨텍스트 다이어트 (FR-3.2) ----
-      if (state.iteration % handoffEvery === 0 && state.iteration < maxLoops) {
+      if (state.iteration % handoffEvery === 0 && state.iteration < cap()) {
         state.sessionId = null;
         state.sessionSerial += 1;
         saveState(statePath, state);

package/src/cli-options.js

@@ -90,6 +90,9 @@ export function parseRunOptions(args, { staged = {} } = {}) {
 
   const onShipFail = enumOpt('on-ship-fail', ['stop', 'heal'], 'stop');
   if (onShipFail?.error) return bad(onShipFail.error);
+  // FR-22: CHECK 실패/불능 시 안쪽 루프를 어떻게 다룰까. heal=자동수정(기본) / ask=사람에게 물음 / stop=즉시 중단.
+  const onFail = enumOpt('on-fail', ['heal', 'ask', 'stop'], 'heal');
+  if (onFail?.error) return bad(onFail.error);
   const onWatchFail = enumOpt('on-watch-fail', ['stop', 'rollback', 'heal'], 'stop');
   if (onWatchFail?.error) return bad(onWatchFail.error);
 
@@ -138,6 +141,7 @@ export function parseRunOptions(args, { staged = {} } = {}) {
       commitMessage: str('commit-message'),
       onShipFail,
       onWatchFail,
+      onFail,
       askPolicy,
       yes: Boolean(args.yes),
       full: Boolean(args.full),

package/src/loop.js

@@ -23,7 +23,7 @@ import { makeNotifier } from './telegram.js';
 import { makeShipper, makeWatcher, WATCH_DEFAULTS } from './ship.js';
 import { makeCodeReviewer, makeDesignReviewer } from './review.js';
 import { makeDiscoverer } from './discover.js';
-import { formatAsk, createAsk, pauseForAsk, shouldAsk, DEFAULT_ASK_POLICY } from './ask.js';
+import { formatAsk, createAsk, pauseForAsk, shouldAsk, onFailAsk, DEFAULT_ASK_POLICY } from './ask.js';
 import { STAGE_HANDLERS } from './stages.js';
 import { runBuildLoop } from './build.js';
 import { buildStageContext } from './stage-context.js';
@@ -65,6 +65,7 @@ async function runLoopBody({
   flakyProbe = false,
   specPath = null, // --spec: 스펙 오라클을 표준 문서로 고정(FR-19). null=엔진이 경로 결정.
   checks = null,
+  onFail = 'heal', // FR-22: CHECK 실패/불능 시 안쪽 루프 처리. heal(자동) | ask(사람에게) | stop(중단).
   handoffEvery = 4,
   // ---- 라이프사이클 (FR-13, FR-14) ----
   shipCommand = null,
@@ -245,7 +246,7 @@ async function runLoopBody({
       shipCommand, watchCommand, onShipFail, onWatchFail, watchForMs, watchEveryMs,
       watchTolerate, maxReviewRounds, maxLoops, budgetUsd, testCommand, stagnationLimit,
       verifySpec, flakyProbe, checks, handoffEvery, maxDesignRounds, stopAfter,
-      commit, commitMessage, commitStyle,
+      commit, commitMessage, commitStyle, onFail, askPolicy,
     },
   });
 
@@ -268,6 +269,12 @@ async function runLoopBody({
       state.status = 'running';
       saveState(statePath, state);
       const built = await runBuildLoop(ctx);
+      // FR-22: on-fail ask — 빌드 루프가 실패/불능에서 사람 판단을 요청하며 멈췄다.
+      if (built.paused) {
+        state.ask = createAsk(onFailAsk(built.onFail));
+        state.status = 'awaiting';
+        return pauseResult();
+      }
       if (built.stopped) return stopResult('PLAN');
       if (!built.ok) return finish('failed', { stopReason: built.stopReason, detail: built.detail });
       if (shouldStopAfter('BUILD')) return stopResult('BUILD');
@@ -290,5 +297,4 @@ async function runLoopBody({
     saveState(statePath, state);
   }
 }
-
 export default runLoop;

package/src/mcp-server.js

@@ -44,13 +44,30 @@ export const tools = {
       reconcile,
       reconcileSpec,
       checks,
+      onFail,
       cwd = defaultCwd(),
-    }) => {
+    }, extra) => {
       if (!goal) return fail('goal 은 필수입니다.');
       // 루프를 돌리기 전에 에이전트가 실행 가능한지 확인한다 — 미설치/실행불가면
       // 회차를 태우지 않고 여기서 행동지침을 돌려준다(호스트 LLM 이 사용자에게 전달).
       const pre = await preflightAgent();
       if (!pre.ok) return fail(pre.message);
+      // MCP progress: 루프 로그가 나올 때마다 클라이언트에 진행 알림을 보낸다. 이게 없으면
+      // 긴 루프(e2e 등)가 조용히 유휴 타임아웃(기본 30분)에 걸려 클라이언트 호출만 끊긴다.
+      // 클라이언트가 progressToken 을 준 경우에만 보낸다(안 주면 조용히 stderr 로만 로그).
+      const progressToken = extra?._meta?.progressToken;
+      let ticks = 0;
+      const runLogger = (line) => {
+        log(line);
+        if (progressToken != null && typeof extra?.sendNotification === 'function') {
+          extra
+            .sendNotification({
+              method: 'notifications/progress',
+              params: { progressToken, progress: (ticks += 1), message: String(line).replace(/^\[hi-loop[^\]]*\]\s*/, '').slice(0, 200) },
+            })
+            .catch(() => {}); // 알림 실패는 루프에 영향 없음
+        }
+      };
       const result = await runLoop({
         goal,
         testCommand,
@@ -66,8 +83,9 @@ export const tools = {
         // 조건부 검사(--check/--when 의 MCP 노출): 주면 testCommand 대신 이 배열이 판정 기준이 된다.
         // when 글롭에 맞는 파일이 바뀐 회차에만 그 검사를 돌린다(UI 변경 회차에만 e2e 등).
         checks: Array.isArray(checks) && checks.length ? checks : null,
+        onFail: onFail || 'heal',
         cwd,
-        logger: log,
+        logger: runLogger,
       });
 
       // 사람이 골라야 하는 지점에서 멈췄다. 호스트 LLM 이 이 질문을 사용자에게 그대로
@@ -145,11 +163,11 @@ export const tools = {
   },
 };
 
-/** 예외를 isError 응답으로 감싼다 (FR-4.4) */
+/** 예외를 isError 응답으로 감싼다 (FR-4.4). extra(progress·signal)를 핸들러에 그대로 넘긴다. */
 export function wrap(handler) {
-  return async (args) => {
+  return async (args, extra) => {
     try {
-      return await handler(args ?? {});
+      return await handler(args ?? {}, extra);
     } catch (err) {
       // 환경 오류(에이전트 미설치·인증 만료 등)는 이미 행동지침 메시지다 — 그대로 전달한다.
       if (err?.kind === 'environment') return fail(err.message);
@@ -188,6 +206,10 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
         goal: z.string().describe('달성할 요구사항'),
         testCommand: z.string().optional().describe('검증 명령 (기본 "npm test")'),
         maxLoops: z.number().int().min(1).max(50).optional().describe('최대 루프 횟수 (기본 10)'),
+        onFail: z
+          .enum(['heal', 'ask', 'stop'])
+          .optional()
+          .describe('CHECK 실패/불능 시 처리. heal(기본)=maxLoops 안에서 자동 치유 / ask=사람에게 재시도·종료를 물음(awaiting 반환 → hiloop_answer 로 답하고 재호출) / stop=즉시 종료. 대화형에선 ask 권장'),
         verifySpec: z.boolean().optional().describe('통과 시 별도 검증자로 스펙 대비 구현을 심판 (하향 전용, 비용 증가)'),
         full: z.boolean().optional().describe('전체 라이프사이클(발굴·설계리뷰·코드리뷰)까지 실행 (비용 증가)'),
         ship: z.string().optional().describe('배포 명령. 주면 테스트 통과 후 실행하고 exit code 로 판정한다 (실행 전 사용자 확인)'),

package/src/resume.js

@@ -57,6 +57,7 @@ export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd, sp
       specPath: pinnedSpecPath ?? prev.specPath ?? paths.specPath,
       specPinned: pinnedSpecPath ? true : Boolean(prev.specPinned),
       reconciled: Boolean(prev.reconciled),
+      extraLoops: Number.isFinite(prev.extraLoops) ? prev.extraLoops : 0,
       testPath: prev.testPath ?? paths.testPath,
       costUsd: Number.isFinite(prev.costUsd) ? prev.costUsd : 0,
       // 기준선이 없던 시절의 상태로 재개하면 이번 회차 지문이 곧 기준선이 된다.

package/src/state.js

@@ -146,6 +146,8 @@ export function createState({
     specPinned: Boolean(pinnedSpecPath),
     // FR-21: 문서 정합 게이트를 이미 거쳤는가. 같은 goal 재개 시 다시 묻지 않도록.
     reconciled: false,
+    // FR-22: on-fail ask 에서 사용자가 "재시도"를 고를 때마다 +1. maxLoops 위에 얹혀 회차를 늘린다.
+    extraLoops: 0,
     specSummary: '',
     lastError: '',
     costUsd: 0,