@walwal-harness/cli 5.6.5 → 5.7.0

package/assets/templates/progress.json.template

@@ -1,8 +1,12 @@
 {
-  "version": 2,
+  "version": 3,
   "mode": "solo",
   "project_name": "",
   "pipeline": null,
+  "dispatch": {
+    "counter": 0,
+    "id": null
+  },
   "sprint": {
     "number": 0,
     "status": "init",

package/bin/init.js

@@ -346,6 +346,14 @@ function scaffoldHarness() {
         fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2) + '\n');
         log('progress.json migrated to v2 (mode + team_state added)');
       }
+      if (progress.version < 3) {
+        progress.version = 3;
+        if (!progress.dispatch) {
+          progress.dispatch = { counter: 0, id: null };
+        }
+        fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2) + '\n');
+        log('progress.json migrated to v3 (dispatch counter added)');
+      }
     } catch (e) {
       log('WARNING: Could not migrate progress.json');
     }

package/commands/harness-team.md

@@ -59,6 +59,39 @@ bash scripts/harness-tmux.sh --team --force-tmux
 
 **`--force-tmux` 필수**: iTerm2 감지 경로는 백그라운드에 iTerm2가 떠 있기만 해도 활성화되어 AppleScript 실패 시 팀 레이아웃이 조용히 사라짐. Team Mode는 항상 tmux로 강제하여 재현 가능한 레이아웃을 보장.
 
+### Step 2.5: Worker Pre-flight Bundle 빌드 (v5.6.6+)
+
+Worker 는 plain Agent 로 실행되어 SKILL.md Startup 체크리스트를 자동 주입받지 못한다. Lead 가 Worker spawn 직전에 **역할별 바인딩 문서를 프롬프트에 직접 주입**한다. 이렇게 하면 "Worker 가 읽어야 함" → "이미 읽은 상태로 시작" 으로 전환되어 스킵이 구조적으로 불가능해진다.
+
+```bash
+# Generator-{be|fe} / Evaluator-{functional|visual|code-quality} 별 번들 빌드
+build_preflight_bundle() {
+  local role="$1"   # generator-frontend | generator-backend | evaluator-functional | ...
+  local hroot="$2"  # HARNESS_ROOT (worktree 가 아닌 원본 루트)
+  {
+    echo "===== ROOT CONVENTIONS.md ====="
+    [ -f "$hroot/CONVENTIONS.md" ] && cat "$hroot/CONVENTIONS.md" || echo "(none)"
+    echo
+    echo "===== AGENTS.md ====="
+    [ -f "$hroot/AGENTS.md" ] && cat "$hroot/AGENTS.md" || echo "(none)"
+    echo
+    echo "===== .harness/conventions/shared.md ====="
+    [ -f "$hroot/.harness/conventions/shared.md" ] && cat "$hroot/.harness/conventions/shared.md" || echo "(empty)"
+    echo
+    echo "===== .harness/conventions/$role.md ====="
+    [ -f "$hroot/.harness/conventions/$role.md" ] && cat "$hroot/.harness/conventions/$role.md" || echo "(empty)"
+    echo
+    echo "===== .harness/gotchas/$role.md ====="
+    [ -f "$hroot/.harness/gotchas/$role.md" ] && cat "$hroot/.harness/gotchas/$role.md" || echo "(empty)"
+    echo
+    echo "===== .harness/memory.md ====="
+    [ -f "$hroot/.harness/memory.md" ] && cat "$hroot/.harness/memory.md" || echo "(empty)"
+  }
+}
+```
+
+Worker/내부 Evaluator Agent 프롬프트 상단에 이 번들 출력을 `## Binding Rules (pre-loaded)` 섹션으로 삽입한다. Worker 는 이를 **추가 조회 없이 이미 적용되는 규범**으로 취급한다.
+
 ### Step 3: 초기 Worker 생성 (Auto-Dispatch)
 
 **v5.6.4+**: 개별 dequeue 대신 **`auto-dispatch`** 한 번으로 모든 idle team 에 ready feature 를 원자적으로 배정합니다. 의존성 없는 작업은 병렬로 즉시 시작됩니다.
@@ -97,10 +130,11 @@ ORCHESTRATION LOOP:
 
   Background Agent 완료 알림을 받으면:
 
-  1. Worker 결과 분석:
-     - PASS인 경우 → Step 4a (Merge + Unblock)
-     - FAIL (재시도 가능)인 경우 → Step 4b (Retry)
-     - ESCALATED인 경우 → 사용자에게 알림, 해당 팀 유휴
+  1. Worker 결과 분석 (반환 메시지 첫 줄 태그로 분기):
+     - `PASS` → Step 4a (Merge + Unblock)
+     - `FAIL` (재시도 가능) → Step 4b (Retry)
+     - `RATE_LIMIT` → Step 4c (Rate-Limit Hold, 10m probe)
+     - `ESCALATED` → 사용자에게 알림, 해당 팀 유휴
 
   2. **Auto-Dispatch (필수)** — worker 완료 직후 idle 이 된 팀뿐 아니라
      모든 idle team 에 ready feature 를 즉시 재배정:
@@ -145,6 +179,47 @@ Worker가 PASS로 반환되면:
    echo "$(date +'%Y-%m-%d %H:%M') | lead | pass | {FEATURE_ID} merged + unblocked deps" >> .harness/progress.log
    ```
 
+#### Step 4c: Rate-Limit Hold (토큰 한도 대응 · v5.6.7+)
+
+Worker 반환 첫 줄이 `RATE_LIMIT` 으로 시작하면 Lead 는 **에러 아닌 hold 모드**로 전환한다. 나머지 Worker 들은 자연 완료까지 계속 실행되고, 그 결과도 RATE_LIMIT 이면 합쳐서 hold 상태에 누적된다.
+
+```bash
+# 1) Checkpoint 기록 (current in_progress + ready 스냅샷 저장)
+bash "$HARNESS_ROOT/scripts/harness-queue-manager.sh" hold rate_limit 600 .
+
+# 2) 로그 + tmux pane 타이틀 변경
+echo "$(date +'%Y-%m-%d %H:%M') | lead | hold | rate-limit detected, pausing 10m" >> .harness/progress.log
+tmux rename-window "⏸ HOLD (resume ~$(date -v+10M +%H:%M 2>/dev/null || date -d '+10 min' +%H:%M))" 2>/dev/null || true
+
+# 3) 실패한 feature 는 requeue (WIP worktree 는 유지 — merge 없이 재사용)
+bash "$HARNESS_ROOT/scripts/harness-queue-manager.sh" requeue {FEATURE_ID} .
+```
+
+4) **ScheduleWakeup 으로 10분 뒤 재진입 스케줄**:
+```
+ScheduleWakeup({
+  delaySeconds: 600,
+  prompt: "/harness-team resume",
+  reason: "rate-limit hold — 10m probe"
+})
+```
+
+5) Lead LOOP return (중단 아님 — wake-up 이 재진입 트리거).
+
+**Wake-up 재진입 시 Lead 동작** (`/harness-team resume` 처리):
+
+```bash
+# Probe: claude CLI 가 실제로 응답하는지 최소 호출로 확인
+bash "$HARNESS_ROOT/scripts/harness-queue-manager.sh" resume-probe .
+# 종료 코드: 0=clear, 1=still held, 2=escalated(>12h)
+```
+
+- **0 (clear)** → 체크포인트 삭제됨. 즉시 `auto-dispatch` 실행 → Step 4 LOOP 복귀.
+- **1 (still held)** → 다시 `ScheduleWakeup(600, "/harness-team resume", "rate-limit still held — cycle N")` 스케줄. hold_count 증가.
+- **2 (escalated)** → 72 사이클(12시간) 초과. 사용자 개입 알림 후 LOOP 종료. 체크포인트 파일 (`.harness/actions/team-checkpoint.json`) 에 전체 상태가 남아있으므로 사용자가 수동 복구 가능.
+
+**핵심 원칙**: 토큰 리밋은 "실패"가 아닌 "일시 정지". 진행 중이던 worktree/queue 상태는 그대로 보존되고, 10분 간격 probe 로 해제 즉시 이어서 진행한다. Session 을 닫아도 이어지길 원한다면 `ScheduleWakeup` 대신 `schedule` 스킬(CronCreate) 로 cron-backed 재시도 설정 가능.
+
 #### Step 4b: Retry (FAIL 처리)
 
 Worker가 FAIL (재시도 가능)로 반환되면:
@@ -171,6 +246,15 @@ Worker가 FAIL (재시도 가능)로 반환되면:
 당신은 Harness Team-{N} 워커입니다. **단일 Feature**에 대해 Gen→Eval 사이클을 수행합니다.
 완료 후 결과를 반환합니다. 다음 Feature는 Lead가 할당합니다.
 
+## Binding Rules (pre-loaded — 스킵 금지, 이미 적용됨)
+
+Lead 가 Step 2.5 에서 build_preflight_bundle 로 생성한 번들이 아래에 주입됩니다.
+당신은 이 규칙을 이미 읽은 상태로 시작합니다. 추가 조회 불필요:
+
+{PREFLIGHT_BUNDLE}
+
+**작업 시작 전 필수 출력**: 위 번들에서 이번 Feature 작업에 **적용되는 규칙**을 3~8 줄로 요약한 뒤 진행하라. 비어있으면 "(empty)" 로 명시. 이 요약 없이 Phase 1 로 진입하면 Self-FAIL 처리하고 재시작한다. 내부 Evaluator Agent 를 생성할 때도 같은 번들을 `{PREFLIGHT_BUNDLE}` 자리에 그대로 전달하라 (Evaluator 도 plain Agent 이므로 자동주입 없음).
+
 ## 할당된 Feature
 - Feature ID: {FEATURE_ID}
 - 프로젝트 루트: 현재 디렉토리 (worktree 복사본)
@@ -301,6 +385,18 @@ logev fail "{FEATURE_ID} FAIL #{ATTEMPT} — {사유}"
 logev fail "{FEATURE_ID} FINAL FAIL after 5 attempts"
 ```
 Lead에게 반환: `ESCALATED | {FEATURE_ID} | attempts=5 | last_feedback={마지막_피드백}`
+
+### RATE_LIMIT (토큰 한도 감지 시 — v5.6.7+)
+
+Gen 또는 Eval Phase 중 429 / "rate_limit" / "quota" / "overloaded_error" / "token limit" / "usage limit" 메시지를 만나면:
+
+```bash
+logev hold "{FEATURE_ID} rate-limit hit — returning RATE_LIMIT to Lead"
+```
+Lead에게 반환 **첫 줄에 반드시 `RATE_LIMIT` 태그 포함**:
+`RATE_LIMIT | {FEATURE_ID} | phase={gen|eval} | attempt={N} | err={원문요약}`
+
+작업을 **포기하지 말고** 현재까지의 변경분을 worktree 에 그대로 commit (WIP). Lead 가 hold 해제 후 같은 worktree 로 resume.
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.6.5",
+  "version": "5.7.0",
   "description": "Production harness for AI agent engineering — Solo/Team mode, Planner, Generator(BE/FE), Evaluator chain (Code-Quality → Functional → Visual), optional Brainstormer. Supports React, Next.js, and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"

package/scripts/harness-archive.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# harness-archive.sh — 스프린트 종료 시 자동 아카이빙
+#
+# 동작:
+#   1. .harness/actions/ 의 스프린트 산출물을 .harness/archive/D-NNN/S-NNN/ 로 이동
+#   2. progress.json 의 sprint 상태를 초기화 (신규 dispatch 준비)
+#   3. dispatch.id 가 없으면 counter++ 로 새 dispatch 시작
+#
+# 유지되는 파일 (이동하지 않음):
+#   - .harness/gotchas/**, .harness/conventions/**, .harness/ref/**
+#   - .harness/config.json, .harness/memory.md
+#   - .harness/progress.json (초기화만)
+#
+# 호출 주체: harness-next.sh (next_agent="archive" 도달 시 자동)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/harness-render-progress.sh" 2>/dev/null || true
+
+PROJECT_ROOT="${1:-.}"
+PROJECT_ROOT="$(cd "$PROJECT_ROOT" && pwd)"
+
+PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+ACTIONS_DIR="$PROJECT_ROOT/.harness/actions"
+ARCHIVE_ROOT="$PROJECT_ROOT/.harness/archive"
+
+if [ ! -f "$PROGRESS" ]; then
+  echo "[archive] ERROR: progress.json not found" >&2
+  exit 1
+fi
+
+command -v jq >/dev/null 2>&1 || { echo "[archive] ERROR: jq required" >&2; exit 1; }
+
+# ── Read current dispatch/sprint numbers ──
+dispatch_counter=$(jq -r '.dispatch.counter // 0' "$PROGRESS")
+dispatch_id=$(jq -r '.dispatch.id // empty' "$PROGRESS")
+sprint_num=$(jq -r '.sprint.number // 0' "$PROGRESS")
+
+# Ensure dispatch id exists (fallback for legacy progress.json without dispatch)
+if [ -z "$dispatch_id" ] || [ "$dispatch_id" = "null" ]; then
+  if [ "$dispatch_counter" -lt 1 ]; then
+    dispatch_counter=1
+  fi
+  dispatch_id=$(printf 'D-%03d' "$dispatch_counter")
+fi
+
+sprint_id=$(printf 'S-%03d' "$sprint_num")
+target_dir="$ARCHIVE_ROOT/$dispatch_id/$sprint_id"
+
+echo ""
+echo "  ── Archive ────────────────────────────"
+echo "  Dispatch : $dispatch_id"
+echo "  Sprint   : $sprint_id"
+echo "  Target   : ${target_dir#$PROJECT_ROOT/}"
+
+# ── Move actions/ contents into archive ──
+if [ -d "$ACTIONS_DIR" ] && [ "$(ls -A "$ACTIONS_DIR" 2>/dev/null)" ]; then
+  mkdir -p "$target_dir"
+  moved=0
+  for f in "$ACTIONS_DIR"/*; do
+    [ -e "$f" ] || continue
+    name="$(basename "$f")"
+    if [ -e "$target_dir/$name" ]; then
+      # Collision — suffix with timestamp to avoid overwrite
+      ts=$(date +%Y%m%d-%H%M%S)
+      mv "$f" "$target_dir/${name%.}.${ts}"
+    else
+      mv "$f" "$target_dir/"
+    fi
+    moved=$((moved + 1))
+  done
+  echo "  Moved    : $moved file(s)"
+else
+  echo "  Moved    : 0 file(s) (actions/ empty)"
+fi
+
+# ── Reset progress.json for next dispatch ──
+# - sprint → init
+# - agents → cleared
+# - artifacts → pending
+# - dispatch.id cleared (next dispatcher run will allocate new D-NNN)
+# - failure → cleared
+jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
+  .pipeline = null
+  | .dispatch.id = null
+  | .sprint = { number: 0, status: "init", retry_count: 0 }
+  | .current_agent = null
+  | .agent_status = "pending"
+  | .completed_agents = []
+  | .next_agent = "dispatcher"
+  | .failure = { agent: null, location: null, message: null, retry_target: null }
+  | (.artifacts // {}) as $a
+  | .artifacts = ($a | with_entries(
+      if (.value | type) == "object"
+      then .value = { status: "pending", updated_by: null, updated_at: null }
+      else .
+      end))
+  | .updated_at = $now
+' "$PROGRESS" > "${PROGRESS}.tmp" && mv "${PROGRESS}.tmp" "$PROGRESS"
+
+# ── Clear handoff so next session starts fresh ──
+HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
+echo '{}' > "$HANDOFF"
+
+echo "  Status   : archived, progress reset"
+echo ""
+echo "  ✓ 다음 요청은 새로운 dispatch 로 시작합니다."
+echo ""

package/scripts/harness-dashboard.sh

@@ -11,6 +11,7 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 PROJECT_ROOT="${1:-}"
 if [ -z "$PROJECT_ROOT" ]; then
@@ -420,5 +421,6 @@ while true; do
   # from any previous frame (fixes wrapped shell-prompt bleed-through).
   printf '%s\n' "$buf" | awk '{printf "%s\033[K\n", $0}'
   tput ed 2>/dev/null
-  sleep 3
+  printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
+  wait_or_refresh 3 || true
 done

package/scripts/harness-gotcha-memory.sh

@@ -7,6 +7,7 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 PROJECT_ROOT="${1:-}"
 if [ -z "$PROJECT_ROOT" ]; then
@@ -181,7 +182,11 @@ while true; do
   sig=$(compute_signature)
   if [ "$sig" != "$LAST_SIG" ]; then
     render
+    printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
     LAST_SIG="$sig"
   fi
-  sleep "$REFRESH_SEC"
+  if ! wait_or_refresh "$REFRESH_SEC"; then
+    # 'r' 키 → 캐시 무효화해서 다음 루프에서 강제 렌더
+    LAST_SIG=""
+  fi
 done

package/scripts/harness-monitor.sh

@@ -9,6 +9,7 @@
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 # ── Args ──
 # Usage: harness-monitor.sh [project-root] [--team N]
@@ -382,6 +383,7 @@ while true; do
     check_transitions
   fi
 
-  sleep 3
+  printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
+  wait_or_refresh 3 || true
 done
 

package/scripts/harness-next.sh

@@ -499,19 +499,29 @@ if [ "$next_agent" != "null" ] && [ "$next_agent" != "archive" ] && [ "$agent_st
 
 elif [ "$next_agent" = "archive" ]; then
   audit_log "system" "archive" "start" "sprint-${sprint_num}" "sprint cycle complete"
-  jq -n \
-    --arg from "${current_agent:-evaluator}" \
-    --argjson sprint "$sprint_num" \
-    --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-    '{
-      from: $from,
-      to: "archive",
-      prompt: "Sprint 문서를 아카이브하세요.\n.harness/actions/의 스프린트 문서를 .harness/archive/sprint-NNN/으로 이동합니다.\n.harness/handoff.json을 읽고 sprint 번호를 확인하세요.",
-      sprint: $sprint,
-      model: "opus",
-      thinking_mode: null,
-      timestamp: $timestamp
-    }' > "$HANDOFF"
+
+  # ── Auto-archive: run archive script synchronously ──
+  # harness-archive.sh moves .harness/actions/* to .harness/archive/D-NNN/S-NNN/
+  # and resets progress.json. On next user prompt the flow starts fresh as a new dispatch.
+  if bash "$SCRIPT_DIR/harness-archive.sh" "$PROJECT_ROOT"; then
+    audit_log "system" "archive" "complete" "sprint-${sprint_num}" "auto-archived"
+  else
+    echo "  ⚠ archive script failed — falling back to manual handoff" >&2
+    audit_log "system" "archive" "fail" "sprint-${sprint_num}" "script failed"
+    jq -n \
+      --arg from "${current_agent:-evaluator}" \
+      --argjson sprint "$sprint_num" \
+      --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      '{
+        from: $from,
+        to: "archive",
+        prompt: "Sprint 문서를 아카이브하세요. harness-archive.sh 가 실패했습니다 — 수동으로 .harness/actions/* 를 .harness/archive/D-NNN/S-NNN/ 로 이동하세요.",
+        sprint: $sprint,
+        model: "opus",
+        thinking_mode: null,
+        timestamp: $timestamp
+      }' > "$HANDOFF"
+  fi
 
 else
   echo '{}' > "$HANDOFF"

package/scripts/harness-prompt-history.sh

@@ -7,6 +7,7 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+source "$SCRIPT_DIR/lib/harness-keywait.sh"
 
 PROJECT_ROOT="${1:-}"
 if [ -z "$PROJECT_ROOT" ]; then
@@ -158,5 +159,6 @@ while true; do
   tput cup 0 0 2>/dev/null
   echo "$buf"
   tput ed 2>/dev/null
-  sleep 3
+  printf "${DIM}  [r] refresh  [q] quit${RESET}\033[K\n"
+  wait_or_refresh 3 || true
 done

package/scripts/harness-queue-manager.sh

@@ -487,6 +487,68 @@ cmd_idle_slots() {
   }' "$QUEUE"
 }
 
+# ── Rate-Limit Hold checkpoint (v5.6.7+) ──
+CHECKPOINT="$PROJECT_ROOT/.harness/actions/team-checkpoint.json"
+
+cmd_hold() {
+  # Args: <reason> [retry_seconds=600]
+  local reason="${1:-rate_limit}"
+  local retry_secs="${2:-600}"
+  local now_iso retry_iso
+  now_iso="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  retry_iso="$(date -u -v+"${retry_secs}"S +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+              || date -u -d "+${retry_secs} seconds" +%Y-%m-%dT%H:%M:%SZ)"
+  acquire_queue_lock
+  trap release_queue_lock EXIT
+  local in_progress pending
+  in_progress="$(jq '[.teams[] | select(.current_feature != null) |
+                     {team: .team_id, feature: .current_feature, phase: (.current_phase // "gen")}]' "$QUEUE")"
+  pending="$(jq '[.features[] | select(.status == "ready") | .id]' "$QUEUE")"
+  local tmp="${CHECKPOINT}.tmp"
+  jq -n --arg ts "$now_iso" --arg retry "$retry_iso" --arg reason "$reason" \
+        --argjson inprog "$in_progress" --argjson ready "$pending" \
+        '{timestamp:$ts, retry_at:$retry, last_error:$reason,
+          in_progress:$inprog, ready_features:$ready,
+          hold_count: 1, escalate_after: 72}' > "$tmp" && mv "$tmp" "$CHECKPOINT"
+  release_queue_lock
+  trap - EXIT
+  echo "[hold] checkpoint written — retry_at=$retry_iso reason=$reason"
+}
+
+cmd_resume_probe() {
+  # Lightweight probe — called on ScheduleWakeup resume.
+  # Exits 0 if ready to resume, 1 if still held, 2 if escalated.
+  [ ! -f "$CHECKPOINT" ] && { echo "[resume] no checkpoint — nothing to resume"; exit 0; }
+  local hold_count escalate_after
+  hold_count="$(jq -r '.hold_count // 1' "$CHECKPOINT")"
+  escalate_after="$(jq -r '.escalate_after // 72' "$CHECKPOINT")"
+  if [ "$hold_count" -ge "$escalate_after" ]; then
+    echo "[resume] ESCALATED — held $hold_count cycles (max=$escalate_after). Manual intervention required."
+    exit 2
+  fi
+  # Probe: minimal claude call — if rate-limited, exits non-zero quickly.
+  if command -v claude >/dev/null 2>&1; then
+    if echo "ping" | timeout 30 claude -p "reply only: pong" >/dev/null 2>&1; then
+      echo "[resume] probe OK — clearing hold"
+      rm -f "$CHECKPOINT"
+      exit 0
+    fi
+  fi
+  # Still held — increment and report
+  local tmp="${CHECKPOINT}.tmp"
+  jq '.hold_count = (.hold_count + 1) | .last_probe_at = now | todate' "$CHECKPOINT" > "$tmp" && mv "$tmp" "$CHECKPOINT"
+  echo "[resume] still held (cycle $((hold_count+1))/$escalate_after) — schedule another wake-up"
+  exit 1
+}
+
+cmd_hold_status() {
+  if [ ! -f "$CHECKPOINT" ]; then
+    echo '{"held":false}'
+    return
+  fi
+  jq '. + {held:true}' "$CHECKPOINT"
+}
+
 # ── Dispatch ──
 case "$CMD" in
   init)           cmd_init "$@" ;;
@@ -500,8 +562,11 @@ case "$CMD" in
   recover)        cmd_recover ;;
   next-sprint)    cmd_next_sprint ;;
   status)         cmd_status ;;
+  hold)           cmd_hold "$@" ;;
+  resume-probe)   cmd_resume_probe ;;
+  hold-status)    cmd_hold_status ;;
   *)
-    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|pass|fail|requeue|recover|next-sprint|update_phase|status> [args]"
+    echo "Usage: harness-queue-manager.sh <init|dequeue|auto-dispatch|idle-slots|pass|fail|requeue|recover|next-sprint|update_phase|status|hold|resume-probe|hold-status> [args]"
     exit 1
     ;;
 esac

package/scripts/lib/harness-keywait.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# harness-keywait.sh — 패널 refresh/quit 키 대기 헬퍼
+#
+# 사용법:
+#   source scripts/lib/harness-keywait.sh
+#   while true; do
+#     render_panel
+#     echo "  [r] refresh  [q] quit"
+#     if wait_or_refresh 3; then
+#       # 타임아웃 → 일반 주기 리프레시
+#       :
+#     else
+#       # 'r' 키 즉시 리프레시 (반환값 != 0)
+#       :
+#     fi
+#   done
+#
+# 키 처리:
+#   'r' / 'R' / Enter → 즉시 복귀 (return 1 — 강제 리프레시 신호)
+#   'q' / 'Q'         → exit 0 (패널 종료)
+#   그 외 / 타임아웃  → return 0 (정상 주기 리프레시)
+#
+# TTY 가 아니면 plain sleep 으로 동작 (Claude Code Bash 도구 등에서도 안전).
+
+wait_or_refresh() {
+  local secs="${1:-3}"
+
+  # Non-TTY fallback
+  if ! [ -t 0 ]; then
+    sleep "$secs"
+    return 0
+  fi
+
+  local key=""
+  # -t: timeout, -n 1: 1글자, -s: 에코 안함
+  # read 는 Enter 에서도 타임아웃 전에 즉시 복귀 (빈 키)
+  if IFS= read -rsn 1 -t "$secs" key 2>/dev/null; then
+    case "$key" in
+      q|Q)
+        # 커서 복원 후 종료
+        tput cnorm 2>/dev/null || true
+        clear
+        exit 0
+        ;;
+      r|R|"")
+        # 강제 리프레시 시그널
+        return 1
+        ;;
+      *)
+        # 기타 키는 무시하고 일반 복귀
+        return 0
+        ;;
+    esac
+  fi
+  # 타임아웃
+  return 0
+}

package/skills/dispatcher/SKILL.md

@@ -42,6 +42,18 @@ jq '.agent_status = "completed" | .completed_agents += ["planner"]'   .harness/p
      - Gotcha 교정 후 재작업 → `failure.retry_target` (해당 에이전트)
    - `pipeline` → 선택된 파이프라인 (FULLSTACK/FE-ONLY/BE-ONLY)
    - `sprint.number` → `1`, `sprint.status` → `"in_progress"` (신규 파이프라인인 경우에만)
+   - **신규 파이프라인인 경우** `dispatch.id` 가 `null` 이면 counter 를 올리고 새 ID 를 발급 (v5.7+):
+     ```bash
+     # dispatch.id 가 이미 있으면 기존 dispatch 유지, 없으면 새로 발급
+     cur=$(jq -r '.dispatch.id // ""' .harness/progress.json)
+     if [ -z "$cur" ]; then
+       next=$(jq -r '((.dispatch.counter // 0) + 1)' .harness/progress.json)
+       new_id=$(printf 'D-%03d' "$next")
+       bash scripts/harness-progress-set.sh . \
+         ".dispatch.counter = $next | .dispatch.id = \"$new_id\""
+     fi
+     ```
+     아카이빙 후 `dispatch.id` 는 `null` 로 리셋되므로, 다음 dispatcher 실행 시 새 D-NNN 이 할당된다.
 2. `.harness/progress.log`에 요약 한 줄 추가
 3. **STOP. 다음 에이전트를 직접 호출하지 않는다.**
 4. 출력: `"✓ Dispatcher 완료. bash scripts/harness-next.sh 실행하여 다음 단계 확인."`