@walwal-harness/cli 4.0.0-alpha.9 → 4.0.0-beta.10

package/scripts/harness-monitor.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
-# harness-monitor.sh — Panel 2: Task & Agent Lifecycle 모니터링
-# audit.log 스트리밍 + progress.json 변경 감지
+# harness-monitor.sh — Agent Lifecycle Monitor
+#
+# v3 모드: 단일 이벤트 스트림 (progress.json 변경 감지 + audit.log)
+# v4 모드: 팀별 섹션 분리 (feature-queue.json + progress.log 기반)
+#
 # Usage: bash scripts/harness-monitor.sh [project-root]
 
 set -uo pipefail
@@ -17,8 +20,9 @@ if [ -z "$PROJECT_ROOT" ]; then
 fi
 
 PROGRESS="$PROJECT_ROOT/.harness/progress.json"
+PROGRESS_LOG="$PROJECT_ROOT/.harness/progress.log"
 AUDIT_LOG="$PROJECT_ROOT/.harness/actions/audit.log"
-HANDOFF="$PROJECT_ROOT/.harness/handoff.json"
+QUEUE="$PROJECT_ROOT/.harness/actions/feature-queue.json"
 
 # ── ANSI helpers ──
 BOLD="\033[1m"
@@ -28,28 +32,169 @@ YELLOW="\033[33m"
 RED="\033[31m"
 CYAN="\033[36m"
 MAGENTA="\033[35m"
+BLUE="\033[34m"
 RESET="\033[0m"
 
+# ── Team colors ──
+T1_COLOR="$CYAN"
+T2_COLOR="$MAGENTA"
+T3_COLOR="$YELLOW"
+
+team_color() {
+  case "$1" in
+    1|team-1) echo "$T1_COLOR" ;;
+    2|team-2) echo "$T2_COLOR" ;;
+    3|team-3) echo "$T3_COLOR" ;;
+    *)        echo "$DIM" ;;
+  esac
+}
+
+# ══════════════════════════════════════════
+# v4 모드: 팀별 섹션 렌더링
+# ══════════════════════════════════════════
+
+render_v4_header() {
+  echo -e "${BOLD}TEAM MONITOR${RESET}  ${DIM}$(date +%H:%M:%S)${RESET}"
+  echo ""
+}
+
+render_team_section() {
+  local team_num="$1"
+  local color
+  color=$(team_color "$team_num")
+
+  # 팀 상태 from queue
+  local t_status="idle" t_feature="—" t_phase="—" t_attempt=""
+  if [ -f "$QUEUE" ]; then
+    t_status=$(jq -r ".teams[\"$team_num\"].status // \"idle\"" "$QUEUE" 2>/dev/null)
+    t_feature=$(jq -r ".teams[\"$team_num\"].feature // \"—\"" "$QUEUE" 2>/dev/null)
+    if [ "$t_feature" != "—" ] && [ "$t_feature" != "null" ]; then
+      t_phase=$(jq -r --arg f "$t_feature" '.queue.in_progress[$f].phase // "?"' "$QUEUE" 2>/dev/null)
+      t_attempt=$(jq -r --arg f "$t_feature" '.queue.in_progress[$f].attempt // 1' "$QUEUE" 2>/dev/null)
+    fi
+  fi
+
+  # 상태 아이콘
+  local icon="○"
+  case "$t_status" in
+    busy) icon="▶" ;;
+    idle) icon="○" ;;
+  esac
+
+  # Phase 표시
+  local phase_str=""
+  case "$t_phase" in
+    gen)  phase_str="Gen" ;;
+    gate) phase_str="Gate" ;;
+    eval) phase_str="Eval" ;;
+    *)    phase_str="" ;;
+  esac
+
+  # 헤더 라인
+  printf "%b%b T%s%b " "$color" "$icon" "$team_num" "$RESET"
+  if [ "$t_feature" != "—" ] && [ "$t_feature" != "null" ]; then
+    printf "%s " "$t_feature"
+    if [ -n "$phase_str" ]; then
+      printf "%b%s%b" "$color" "$phase_str" "$RESET"
+    fi
+    if [ -n "$t_attempt" ] && [ "$t_attempt" != "—" ] && [ "$t_attempt" != "1" ]; then
+      printf " %b#%s%b" "$DIM" "$t_attempt" "$RESET"
+    fi
+  else
+    printf "%bidle%b" "$DIM" "$RESET"
+  fi
+  echo ""
+
+  # 팀 로그 (progress.log에서 team-N 엔트리만 추출)
+  if [ -f "$PROGRESS_LOG" ]; then
+    grep -i "team-${team_num}\|team_${team_num}" "$PROGRESS_LOG" 2>/dev/null | tail -5 | while IFS= read -r line; do
+      local ts action detail
+      ts=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$1); print $1}')
+      action=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); print $3}')
+      detail=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
+
+      local short_ts
+      short_ts=$(echo "$ts" | grep -oE '[0-9]{2}:[0-9]{2}' | tail -1 || echo "$ts")
+
+      if [ ${#detail} -gt 35 ]; then detail="${detail:0:33}.."; fi
+
+      # 액션별 아이콘
+      local a_icon="·" a_color="$DIM"
+      case "$action" in
+        gen)      a_icon="▶"; a_color="$GREEN" ;;
+        eval)     a_icon="✦"; a_color="$BLUE" ;;
+        pass)     a_icon="✓"; a_color="$GREEN" ;;
+        fail)     a_icon="✗"; a_color="$RED" ;;
+        dequeue)  a_icon="→"; a_color="$CYAN" ;;
+        gate)     a_icon="◆"; a_color="$YELLOW" ;;
+        *)        a_icon="·"; a_color="$DIM" ;;
+      esac
+
+      printf "  %b%s%b %b%s%b %b%s%b\n" \
+        "$DIM" "$short_ts" "$RESET" \
+        "$a_color" "$a_icon" "$RESET" \
+        "$DIM" "$detail" "$RESET"
+    done
+  fi
+}
+
+render_v4() {
+  render_v4_header
+
+  # 팀 수 확인
+  local team_count=3
+  if [ -f "$QUEUE" ]; then
+    team_count=$(jq '.teams | length' "$QUEUE" 2>/dev/null || echo 3)
+  fi
+
+  for i in $(seq 1 "$team_count"); do
+    render_team_section "$i"
+    echo ""
+  done
+
+  # Lead/시스템 이벤트 (team이 아닌 엔트리)
+  echo -e "${BOLD}SYSTEM${RESET}"
+  if [ -f "$PROGRESS_LOG" ]; then
+    grep -v 'team-[0-9]' "$PROGRESS_LOG" 2>/dev/null | grep -v '^#' | grep -v '^$' | tail -5 | while IFS= read -r line; do
+      local ts agent action detail
+      ts=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$1); print $1}')
+      agent=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$2); print $2}')
+      action=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); print $3}')
+      detail=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
+
+      local short_ts
+      short_ts=$(echo "$ts" | grep -oE '[0-9]{2}:[0-9]{2}' | tail -1 || echo "$ts")
+
+      if [ ${#detail} -gt 35 ]; then detail="${detail:0:33}.."; fi
+
+      printf "  %b%s%b %s %b%s%b\n" \
+        "$DIM" "$short_ts" "$RESET" \
+        "$agent" \
+        "$DIM" "$detail" "$RESET"
+    done
+  fi
+}
+
+# ══════════════════════════════════════════
+# v3 모드: 단일 스트림 (기존 동작)
+# ══════════════════════════════════════════
+
 LAST_AGENT=""
 LAST_STATUS=""
 LAST_SPRINT=""
-EVENT_COUNT=0
 
 print_event() {
   local ts="$1" icon="$2" color="$3" msg="$4"
-  EVENT_COUNT=$((EVENT_COUNT + 1))
   echo -e "  ${DIM}${ts}${RESET}  ${color}${icon}${RESET}  ${msg}"
 }
 
-# ── Header ──
-print_header() {
+print_v3_header() {
   echo -e "${BOLD}╔══════════════════════════════════════╗${RESET}"
   echo -e "${BOLD}║  AGENT LIFECYCLE MONITOR             ║${RESET}"
   echo -e "${BOLD}╚══════════════════════════════════════╝${RESET}"
   echo ""
 }
 
-# ── Detect agent transitions from progress.json ──
 check_transitions() {
   if [ ! -f "$PROGRESS" ]; then return; fi
 
@@ -61,39 +206,22 @@ check_transitions() {
   local now
   now=$(date +"%H:%M:%S")
 
-  # Sprint change
   if [ "$sprint" != "$LAST_SPRINT" ] && [ -n "$LAST_SPRINT" ]; then
     print_event "$now" ">>>" "$MAGENTA" "${BOLD}Sprint ${sprint} started${RESET}"
     echo ""
   fi
 
-  # Agent change
   if [ "$agent" != "$LAST_AGENT" ] && [ -n "$LAST_AGENT" ]; then
     if [ "$LAST_AGENT" != "none" ] && [ "$LAST_AGENT" != "null" ]; then
       print_event "$now" " ✓ " "$GREEN" "${LAST_AGENT} → ${BOLD}done${RESET}"
     fi
     if [ "$agent" != "none" ] && [ "$agent" != "null" ]; then
       print_event "$now" " ▶ " "$CYAN" "${BOLD}${agent}${RESET} started"
-
-      # Show handoff context if available
-      if [ -f "$HANDOFF" ]; then
-        local from focus
-        from=$(jq -r '.from // empty' "$HANDOFF" 2>/dev/null)
-        focus=$(jq -r '.focus_features // [] | join(", ")' "$HANDOFF" 2>/dev/null)
-        if [ -n "$from" ] && [ "$from" != "null" ]; then
-          echo -e "         ${DIM}handoff from: ${from}${RESET}"
-        fi
-        if [ -n "$focus" ] && [ "$focus" != "null" ]; then
-          echo -e "         ${DIM}focus: ${focus}${RESET}"
-        fi
-      fi
     fi
   fi
 
-  # Status change (same agent)
   if [ "$agent" = "$LAST_AGENT" ] && [ "$status" != "$LAST_STATUS" ] && [ -n "$LAST_STATUS" ]; then
-    local status_color="$RESET"
-    local status_icon="•"
+    local status_color="$RESET" status_icon="•"
     case "$status" in
       running)   status_color="$GREEN";  status_icon=" ▶ " ;;
       completed) status_color="$CYAN";   status_icon=" ✓ " ;;
@@ -103,7 +231,6 @@ check_transitions() {
     esac
     print_event "$now" "$status_icon" "$status_color" "${agent} → ${BOLD}${status}${RESET}"
 
-    # Show failure detail
     if [ "$status" = "failed" ]; then
       local fail_msg
       fail_msg=$(jq -r '.failure.message // empty' "$PROGRESS" 2>/dev/null)
@@ -118,76 +245,84 @@ check_transitions() {
   LAST_SPRINT="$sprint"
 }
 
-# ── Stream audit.log new lines ──
 stream_audit() {
   if [ ! -f "$AUDIT_LOG" ]; then return; fi
-
-  # Use tail -f in background, parse each new line
   tail -n 0 -f "$AUDIT_LOG" 2>/dev/null | while IFS= read -r line; do
-    # Skip comments/headers
     if [[ "$line" == "#"* ]] || [[ -z "$line" ]]; then continue; fi
-
-    # Parse: TIMESTAMP | AGENT | ACTION | STATUS | TARGET | DETAIL
-    local ts agent action status target detail
+    local ts agent action status target
     ts=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$1); print $1}')
     agent=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$2); print $2}')
     action=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); print $3}')
     status=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
     target=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$5); print $5}')
-    detail=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$6); print $6}')
 
-    # Color by status
     local color="$RESET" icon="•"
     case "$status" in
-      start)    color="$CYAN";   icon="▶" ;;
-      complete) color="$GREEN";  icon="✓" ;;
-      fail)     color="$RED";    icon="✗" ;;
-      pass)     color="$GREEN";  icon="✓" ;;
-      skip)     color="$DIM";    icon="–" ;;
+      start)    color="$CYAN";  icon="▶" ;;
+      complete) color="$GREEN"; icon="✓" ;;
+      fail)     color="$RED";   icon="✗" ;;
+      pass)     color="$GREEN"; icon="✓" ;;
+      skip)     color="$DIM";   icon="–" ;;
     esac
 
-    # Short timestamp (HH:MM:SS from ISO)
     local short_ts
     short_ts=$(echo "$ts" | grep -oE '[0-9]{2}:[0-9]{2}:[0-9]{2}' || echo "$ts")
-
-    echo -e "  ${DIM}${short_ts}${RESET}  ${color}${icon}${RESET}  ${BOLD}${agent}${RESET} ${action} ${target} ${DIM}${detail}${RESET}"
+    echo -e "  ${DIM}${short_ts}${RESET}  ${color}${icon}${RESET}  ${BOLD}${agent}${RESET} ${action} ${target}"
   done &
   AUDIT_TAIL_PID=$!
 }
 
-# ── Cleanup ──
+# ══════════════════════════════════════════
+# Mode detection & main loop
+# ══════════════════════════════════════════
+
 cleanup() {
   if [ -n "${AUDIT_TAIL_PID:-}" ]; then
     kill "$AUDIT_TAIL_PID" 2>/dev/null || true
   fi
+  tput cnorm 2>/dev/null
   exit 0
 }
 trap cleanup EXIT INT TERM
 
-# ── Main ──
-print_header
+# 매 루프마다 v4/v3 동적 감지 — 시작 후에도 모드 전환 가능
+tput civis 2>/dev/null
+clear
 
-# Initialize state
-if [ -f "$PROGRESS" ]; then
-  LAST_AGENT=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
-  LAST_STATUS=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
-  LAST_SPRINT=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
-fi
+CURRENT_MODE=""
 
-# Show existing history
-if [ -f "$PROGRESS" ]; then
-  echo -e "  ${BOLD}History${RESET}"
-  jq -r '.history // [] | .[] | "  \(.timestamp)  \(.agent) — \(.action): \(.detail)"' "$PROGRESS" 2>/dev/null
-  echo ""
-  echo -e "  ${DIM}── Live events below ──${RESET}"
-  echo ""
-fi
+while true; do
+  # 동적 모드 감지
+  if [ -f "$QUEUE" ]; then
+    NEW_MODE="v4"
+  else
+    NEW_MODE="v3"
+  fi
 
-# Start audit log streaming
-stream_audit
+  # 모드 전환 시 화면 초기화
+  if [ "$NEW_MODE" != "$CURRENT_MODE" ]; then
+    clear
+    CURRENT_MODE="$NEW_MODE"
+    if [ "$CURRENT_MODE" = "v3" ]; then
+      # v3 초기화
+      if [ -f "$PROGRESS" ]; then
+        LAST_AGENT=$(jq -r '.current_agent // "none"' "$PROGRESS" 2>/dev/null)
+        LAST_STATUS=$(jq -r '.agent_status // "pending"' "$PROGRESS" 2>/dev/null)
+        LAST_SPRINT=$(jq -r '.sprint.number // 0' "$PROGRESS" 2>/dev/null)
+      fi
+      stream_audit
+    fi
+  fi
 
-# Poll progress.json for transitions
-while true; do
-  check_transitions
-  sleep 2
+  if [ "$CURRENT_MODE" = "v4" ]; then
+    buf=$(render_v4 2>&1)
+    tput cup 0 0 2>/dev/null
+    echo "$buf"
+    tput ed 2>/dev/null
+  else
+    check_transitions
+  fi
+
+  sleep 3
 done
+

package/scripts/harness-next.sh

@@ -59,21 +59,10 @@ if [ -f "$PIPELINE_JSON" ]; then
 fi
 
 # ─────────────────────────────────────────
-# fe_stack + fe_target 치환 헬퍼
-#   pipeline_selection.pipelines 에서 읽은 에이전트명을 fe_stack/fe_target 에 따라 치환
-#   - react: 그대로
-#   - flutter+web: generator-frontend → generator-frontend-flutter 만 치환, eval 은 그대로 (Playwright 사용 가능)
-#   - flutter+mobile/desktop: eval 도 정적 분석용으로 치환, evaluator-visual 은 __skip__
+# fe_stack 치환 (no-op — Flutter 지원 제거됨, 하위 호환용 stub)
 # ─────────────────────────────────────────
 substitute_fe_stack() {
-  local agent="$1"
-  if [ "$fe_stack" != "flutter" ]; then
-    echo "$agent"
-    return
-  fi
-  local sub
-  sub=$(jq -r ".flow.pipeline_selection.fe_stack_substitution.${fe_stack}.by_target[\"${fe_target}\"][\"${agent}\"] // \"${agent}\"" "$CONFIG" 2>/dev/null)
-  echo "$sub"
+  echo "$1"
 }
 
 # ─────────────────────────────────────────
@@ -105,7 +94,7 @@ run_pre_eval_gate() {
   # current_agent가 generator가 아닌 경우 (예: dispatcher로 리라우팅된 상태),
   # completed_agents에서 마지막 generator를 찾는다
   case "$source_agent" in
-    generator-frontend|generator-frontend-flutter)
+    generator-frontend)
       location="frontend"
       checks_key="frontend_checks"
       ;;
@@ -118,7 +107,7 @@ run_pre_eval_gate() {
       local last_gen
       last_gen=$(jq -r '.completed_agents // [] | map(select(startswith("generator-"))) | last // empty' "$PROGRESS" 2>/dev/null)
       case "$last_gen" in
-        generator-frontend|generator-frontend-flutter)
+        generator-frontend)
           location="frontend"
           checks_key="frontend_checks"
           ;;

package/scripts/harness-prompt-history.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# harness-prompt-history.sh — Prompt History pane for v4 tmux layout
+# progress.log + audit.log에서 유저 프롬프트/에이전트 활동 히스토리를 표시
+# Usage: bash scripts/harness-prompt-history.sh [project-root]
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/harness-render-progress.sh"
+
+PROJECT_ROOT="${1:-}"
+if [ -z "$PROJECT_ROOT" ]; then
+  PROJECT_ROOT="$(resolve_harness_root ".")" || { echo "[history] .harness/ not found."; exit 1; }
+fi
+
+PROGRESS_LOG="$PROJECT_ROOT/.harness/progress.log"
+AUDIT_LOG="$PROJECT_ROOT/.harness/actions/audit.log"
+
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+RED="\033[31m"
+CYAN="\033[36m"
+MAGENTA="\033[35m"
+RESET="\033[0m"
+
+render_header() {
+  echo -e "${BOLD}PROMPT HISTORY${RESET}  ${DIM}$(date +%H:%M:%S)${RESET}"
+  echo ""
+}
+
+render_progress_log() {
+  if [ ! -f "$PROGRESS_LOG" ]; then
+    echo -e "  ${DIM}(no progress.log yet)${RESET}"
+    return
+  fi
+
+  grep -v '^#' "$PROGRESS_LOG" 2>/dev/null | grep -v '^$' | tail -20 | while IFS= read -r line; do
+    local ts agent action detail
+    ts=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$1); print $1}')
+    agent=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$2); print $2}')
+    action=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); print $3}')
+    detail=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
+
+    local short_ts icon color
+    short_ts=$(echo "$ts" | grep -oE '[0-9]{2}:[0-9]{2}:[0-9]{2}' || echo "$ts")
+
+    case "$agent" in
+      dispatcher*)  icon="▸" ; color="$MAGENTA" ;;
+      brainstormer) icon="◇" ; color="$CYAN" ;;
+      planner*)     icon="□" ; color="$YELLOW" ;;
+      generator*)   icon="▶" ; color="$GREEN" ;;
+      eval*)        icon="✦" ; color="$RED" ;;
+      user|manual)  icon="★" ; color="$BOLD" ;;
+      team*)        icon="⊕" ; color="$CYAN" ;;
+      *)            icon="·" ; color="$DIM" ;;
+    esac
+
+    if [ ${#detail} -gt 40 ]; then detail="${detail:0:38}.."; fi
+
+    printf "  %b%b%b %b%-8s%b %b%s%b %b%s%b\n" \
+      "$color" "$icon" "$RESET" \
+      "$DIM" "$short_ts" "$RESET" \
+      "$RESET" "$agent" "$RESET" \
+      "$DIM" "$action" "$RESET"
+    if [ -n "$detail" ] && [ "$detail" != " " ]; then
+      echo -e "    ${DIM}${detail}${RESET}"
+    fi
+  done
+}
+
+render_audit_tail() {
+  if [ ! -f "$AUDIT_LOG" ]; then return; fi
+
+  echo ""
+  echo -e "${BOLD}AUDIT${RESET}"
+
+  grep -v '^#' "$AUDIT_LOG" 2>/dev/null | grep -v '^$' | tail -10 | while IFS= read -r line; do
+    local ts agent action status target
+    ts=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$1); print $1}')
+    agent=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$2); print $2}')
+    action=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$3); print $3}')
+    status=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$4); print $4}')
+    target=$(echo "$line" | awk -F'|' '{gsub(/^ +| +$/,"",$5); print $5}')
+
+    local color="$RESET" icon="·"
+    case "$status" in
+      start)    color="$CYAN";  icon="▶" ;;
+      complete) color="$GREEN"; icon="✓" ;;
+      fail)     color="$RED";   icon="✗" ;;
+      pass)     color="$GREEN"; icon="✓" ;;
+      skip)     color="$DIM";   icon="–" ;;
+    esac
+
+    local short_ts
+    short_ts=$(echo "$ts" | grep -oE '[0-9]{2}:[0-9]{2}:[0-9]{2}' || echo "$ts")
+
+    if [ ${#target} -gt 25 ]; then target="${target:0:23}.."; fi
+
+    printf "  %b%b%b %b%s%b %-10s %b%s%b\n" \
+      "$color" "$icon" "$RESET" \
+      "$DIM" "$short_ts" "$RESET" \
+      "$agent" \
+      "$DIM" "$target" "$RESET"
+  done
+}
+
+render_all() {
+  render_header
+  render_progress_log
+  render_audit_tail
+}
+
+# ── Main loop ──
+tput civis 2>/dev/null
+trap 'tput cnorm 2>/dev/null; exit 0' EXIT INT TERM
+clear
+
+while true; do
+  buf=$(render_all 2>&1)
+  tput cup 0 0 2>/dev/null
+  echo "$buf"
+  tput ed 2>/dev/null
+  sleep 3
+done

package/scripts/harness-studio-setup.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# harness-studio-setup.sh — Claude 세션에서 3-column 레이아웃 자동 구축
+#
+# ┌──────────────┬──────────────┬──────────────┐
+# │              │  Dashboard   │              │
+# │  Claude      │  (v4 queue)  │  Team Monitor│
+# │  (Lead)      ├──────────────┤  (lifecycle) │
+# │              │  Command     │              │
+# │              │  History     │              │
+# └──────────────┴──────────────┴──────────────┘
+#
+# 두 가지 상황을 모두 처리:
+#   A) tmux 안에서 실행 → 현재 pane을 split하여 레이아웃 구축
+#   B) tmux 밖에서 실행 → 새 tmux 세션 생성, Claude를 좌측 pane에서 재실행
+#
+# Usage:
+#   bash scripts/harness-studio-setup.sh [project-root]
+#
+# 이미 구축됐으면 skip (멱등성 보장)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SESSION_NAME="harness-studio"
+
+PROJECT_ROOT="${1:-}"
+if [ -z "$PROJECT_ROOT" ]; then
+  dir="$(pwd)"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.harness" ]; then PROJECT_ROOT="$dir"; break; fi
+    dir="$(dirname "$dir")"
+  done
+fi
+
+if [ -z "$PROJECT_ROOT" ] || [ ! -d "$PROJECT_ROOT/.harness" ]; then
+  echo "[studio] .harness/ not found."
+  exit 1
+fi
+
+# ── Resolve Claude command ──
+CLAUDE_CMD="claude --dangerously-skip-permissions"
+if [ -f "$PROJECT_ROOT/.harness/handoff.json" ]; then
+  _model=$(jq -r '.model // empty' "$PROJECT_ROOT/.harness/handoff.json" 2>/dev/null)
+  if [ -n "$_model" ] && [ "$_model" != "null" ]; then
+    CLAUDE_CMD="$CLAUDE_CMD --model $_model"
+  fi
+fi
+
+# ══════════════════════════════════════════
+# Case A: 이미 tmux 안에 있음 → pane split
+# ══════════════════════════════════════════
+if [ -n "${TMUX:-}" ]; then
+  # 멱등성: 이미 pane이 3개 이상이면 skip
+  PANE_COUNT=$(tmux list-panes | wc -l | tr -d ' ')
+  if [ "$PANE_COUNT" -ge 3 ]; then
+    echo "[studio] Layout already set up ($PANE_COUNT panes). Skipping."
+    exit 0
+  fi
+
+  PANE_CLAUDE=$(tmux display-message -p '#{pane_id}')
+  echo "[studio] Setting up 3-column layout (in-place split)..."
+
+  # Left 35% | Right 65%
+  PANE_MID=$(tmux split-window -h -p 65 -t "$PANE_CLAUDE" -c "$PROJECT_ROOT" \
+    -P -F '#{pane_id}' \
+    "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-dashboard-v4.sh\" \"${PROJECT_ROOT}\"'")
+
+  # Middle 45% | Right 55%
+  PANE_RIGHT=$(tmux split-window -h -p 55 -t "$PANE_MID" -c "$PROJECT_ROOT" \
+    -P -F '#{pane_id}' \
+    "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-monitor.sh\" \"${PROJECT_ROOT}\"'")
+
+  # Dashboard top 45% | History bottom 55%
+  PANE_HISTORY=$(tmux split-window -v -p 55 -t "$PANE_MID" -c "$PROJECT_ROOT" \
+    -P -F '#{pane_id}' \
+    "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-prompt-history.sh\" \"${PROJECT_ROOT}\"'")
+
+  # Pane titles
+  tmux select-pane -t "$PANE_CLAUDE"  -T "Lead (Claude)"
+  tmux select-pane -t "$PANE_MID"     -T "Dashboard"
+  tmux select-pane -t "$PANE_HISTORY" -T "Command History"
+  tmux select-pane -t "$PANE_RIGHT"   -T "Team Monitor"
+
+  tmux set-option pane-border-status top 2>/dev/null || true
+  tmux set-option pane-border-format " #{pane_title} " 2>/dev/null || true
+
+  # 포커스를 Claude pane으로 복귀
+  tmux select-pane -t "$PANE_CLAUDE"
+
+  echo "[studio] Layout ready (in-place)."
+  exit 0
+fi
+
+# ══════════════════════════════════════════
+# Case B: tmux 밖에 있음 → 새 세션 생성
+# ══════════════════════════════════════════
+
+# 이미 세션이 있으면 attach만
+if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+  echo "[studio] Session '$SESSION_NAME' already exists. Attaching..."
+  echo "[studio] ATTACH_TMUX=$SESSION_NAME"
+  exit 0
+fi
+
+echo "[studio] Creating new tmux session with 3-column layout..."
+
+# 1. 새 세션 → Left pane (Claude 실행)
+PANE_MAIN=$(tmux new-session -d -s "$SESSION_NAME" -c "$PROJECT_ROOT" -x 220 -y 55 \
+  -P -F '#{pane_id}')
+
+# 2. Left 35% | Right 65%
+PANE_MID=$(tmux split-window -h -p 65 -t "$PANE_MAIN" -c "$PROJECT_ROOT" \
+  -P -F '#{pane_id}' \
+  "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-dashboard-v4.sh\" \"${PROJECT_ROOT}\"'")
+
+# 3. Middle 45% | Right 55%
+PANE_RIGHT=$(tmux split-window -h -p 55 -t "$PANE_MID" -c "$PROJECT_ROOT" \
+  -P -F '#{pane_id}' \
+  "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-monitor.sh\" \"${PROJECT_ROOT}\"'")
+
+# 4. Dashboard top 45% | History bottom 55%
+PANE_HISTORY=$(tmux split-window -v -p 55 -t "$PANE_MID" -c "$PROJECT_ROOT" \
+  -P -F '#{pane_id}' \
+  "bash --norc --noprofile -c 'exec bash \"${SCRIPT_DIR}/harness-prompt-history.sh\" \"${PROJECT_ROOT}\"'")
+
+# 5. Left pane에서 Claude 자동 실행
+tmux send-keys -t "$PANE_MAIN" "unset npm_config_prefix 2>/dev/null" Enter
+tmux send-keys -t "$PANE_MAIN" "clear && $CLAUDE_CMD" Enter
+
+# Pane titles
+tmux select-pane -t "$PANE_MAIN"    -T "Lead (Claude)"
+tmux select-pane -t "$PANE_MID"     -T "Dashboard"
+tmux select-pane -t "$PANE_HISTORY" -T "Command History"
+tmux select-pane -t "$PANE_RIGHT"   -T "Team Monitor"
+
+tmux set-option -t "$SESSION_NAME" pane-border-status top 2>/dev/null || true
+tmux set-option -t "$SESSION_NAME" pane-border-format " #{pane_title} " 2>/dev/null || true
+
+# Focus on Claude pane
+tmux select-pane -t "$PANE_MAIN"
+
+echo "[studio] Session '$SESSION_NAME' created."
+echo "[studio] ATTACH_TMUX=$SESSION_NAME"