feat: add flutter-desktop-control-ui & unity-3d-desktop-character milestones, update roadmap

agent-roadmap/ROADMAP.md

@@ -75,7 +75,7 @@ Phase는 실행 순서가 아니라 도메인/책임 영역의 구조적 지도
 
 - [진행중] Automation Runtime과 Bridge 확장
   - 경로: [PHASE.md](phase/automation-runtime-bridge/PHASE.md)
-  - 요약: 정적 lane/G 이후의 시간대·quota 기반 `adapter + target` 선택과 작업별 failover를 우선 구현하고, provider/grade routing 뒤에는 Node와 독립 `iop-agent` CLI가 공유하는 공통 Go Agent Task runtime으로 현재 Python 감시 루프를 전체 동등성 기준에서 이전한다. Flutter 설정 UI와 Unity 3D Character는 CLI 이후 별도 Milestone으로 두고, 원격 터널링과 oto scheduler/CI-CD는 2차로 잠근다.
+  - 요약: 정적 lane/G 이후의 시간대·quota 기반 선택과 failover를 공통 Go Agent Task runtime으로 확장해 Node와 독립 `iop-agent` CLI가 공유하고, 현재 Python 감시 루프를 전체 동등성 기준에서 이전한다. Flutter Desktop Control UI와 Unity 3D Desktop Character는 CLI 이후 별도 Milestone으로 두고, provider/grade routing은 같은 공통 경계에 연결하며 원격 터널링과 oto scheduler/CI-CD는 2차로 잠근다.
 
 - [계획] 지식과 도구 최적화 확장
   - 경로: [PHASE.md](phase/knowledge-tool-optimization-extension/PHASE.md)

agent-roadmap/phase/automation-runtime-bridge/PHASE.md

@@ -8,7 +8,7 @@
 
 Runtime과 Automation 실행 흐름을 공통화하고, agent 설치형 대상과 비설치형 대상의 제어 경로를 분리해 확장한다.
 CLI 실행, specialized agent 등록, bootstrap/enrollment, OpenAI-compatible workspace agent 실행 계약을 서로 충돌하지 않는 운영 경로로 정리했다.
-NomadCode가 IOP를 실행 백엔드로 사용할 수 있도록 하는 Responses 기반 workspace agent 실행 계약과 정적 lane/G 결과를 시간대·quota·실행 상태와 결합하는 Agent Task 동적 실행 Target Selector를 완료했다. 후속으로 provider/grade routing을 닫고, Node와 독립 `iop-agent` CLI가 함께 사용하는 공통 Go Agent Task runtime으로 현재 Python 감시 루프를 전체 동등성 기준에서 이전한다. Flutter 설정 UI와 Unity 3D Character는 CLI 이후의 별도 Milestone으로 둔다.
+NomadCode가 IOP를 실행 백엔드로 사용할 수 있도록 하는 Responses 기반 workspace agent 실행 계약과 정적 lane/G 결과를 시간대·quota·실행 상태와 결합하는 Agent Task 동적 실행 Target Selector를 완료했다. 후속으로 Node와 독립 `iop-agent` CLI가 함께 사용하는 공통 Go Agent Task runtime으로 현재 Python 감시 루프를 전체 동등성 기준에서 이전하고 provider/grade routing을 같은 공통 경계에 연결한다. Flutter Desktop Control UI와 Unity 3D Desktop Character는 CLI 이후의 별도 Milestone으로 둔다.
 원격 터미널/CLI 터널링과 oto scheduler/CI-CD 자동화는 2차 스케치로 잠그고, 현재 활성 구현 범위로 끌어오지 않는다.
 
 ## Milestone 흐름
@@ -98,6 +98,14 @@ Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실
   - 경로: [iop-agent-cli-runtime](milestones/iop-agent-cli-runtime.md)
   - 요약: 현재 Python 감시·dispatcher와 Node CLI runtime의 전체 동등성을 공통 Go CLI Provider·AgentTaskManager 및 독립 `iop-agent` binary로 이전하고 UI 구현은 후속 Milestone으로 분리한다.
 
+- [스케치] Flutter Desktop Control UI
+  - 경로: [flutter-desktop-control-ui](milestones/flutter-desktop-control-ui.md)
+  - 요약: `iop-agent` local proto-socket을 소비해 YAML 전체 설정, project registry, 실행 상태·오류·로그와 macOS app lifecycle을 제공하는 Flutter 설정·운영 UI를 스케치한다.
+
+- [스케치] Unity 3D Desktop Character
+  - 경로: [unity-3d-desktop-character](milestones/unity-3d-desktop-character.md)
+  - 요약: Flutter와 독립적으로 같은 local proto-socket을 소비하고 작업 상태를 투명 배경 3D 캐릭터와 animation으로 표현하는 macOS Unity client를 스케치한다.
+
 - [스케치] 에이전트 작업 루프 오케스트레이션 MVP
   - 경로: [agent-workflow-loop-orchestration-mvp](milestones/agent-workflow-loop-orchestration-mvp.md)
   - 요약: 교체 가능한 최초 요청 라우터가 코딩·저장소 조회·일반 요청을 direct, Plan, Milestone과 lane/G0X로 분류하고, 사용자 agent의 tool call로 작업 파일을 만든 뒤 파일 상태, 하이브리드 실행과 상위 모델 리뷰를 연결하는 작업 루프를 스케치한다.

agent-roadmap/phase/automation-runtime-bridge/milestones/cli-agent-group-grade-routing.md

@@ -107,5 +107,6 @@ CLI provider agent와 목적별 agent group, 예약어 설정을 runtime이 해
 - 표준선(선택): selector는 provider/agent 하나만 반환한다. known failure의 retry/failover는 공통 runtime이 소유하고 unknown 오류는 추정 복구 없이 표면화한다.
 - 표준선(선택): 같은 provider credential/profile의 cloud quota는 project별로 분할하지 않는 app-global 공유 snapshot이며 group routing은 공통 quota 입력을 읽기만 한다.
 - 선행 작업: CLI Automation Runtime 안정화, OpenAI Responses Input Surface, OpenAI Workspace Agent Execution Contract
-- 후속 작업: [IOP Agent CLI Runtime](iop-agent-cli-runtime.md), [Provider 사용량 알림과 운영 표면](provider-usage-notification-operations-surface.md)
+- 관련 공통화 작업: [IOP Agent CLI Runtime](iop-agent-cli-runtime.md)
+- 후속 작업: [Provider 사용량 알림과 운영 표면](provider-usage-notification-operations-surface.md)
 - 확인 필요: 없음

agent-roadmap/phase/automation-runtime-bridge/milestones/flutter-desktop-control-ui.md

@@ -0,0 +1,86 @@
+# Milestone: Flutter Desktop Control UI
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+`iop-agent`의 전체 YAML 설정과 실행 상태를 macOS Flutter 앱에서 관리할 수 있는 설정·운영 표면을 제공한다.
+binary가 소유하는 local proto-socket을 소비하고 Flutter에 provider 선택, 작업 실행 또는 복구 로직을 복제하지 않은 채 설치 가능한 Desktop 제품으로 패키징한다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] [IOP Agent CLI Runtime](iop-agent-cli-runtime.md)의 config/status/event/control 계약과 macOS binary lifecycle 경계가 구현 계획의 입력으로 고정되어 있다.
+- [ ] YAML 전체 설정, project registry, 실행 상태와 오류 표면을 agent-ui 화면 정의로 옮길 수 있도록 UI 정보 구조와 상태 목록을 확정한다.
+- [ ] macOS app bundle, background 실행, 종료, 재연결과 실제 로그인 환경 smoke 범위를 기능 Task와 연결한다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 불필요
+- SDD 문서: 없음
+- SDD 사유: 현재는 확정된 `iop-agent` local 계약을 소비할 Flutter client 범위를 나누는 스케치이며, process lifecycle·config write·배포 계약을 구현 가능한 계획으로 승격할 때 SDD 필요 여부를 다시 판정한다.
+- 잠금 해제 조건: 아래 체크리스트
+  - [ ] 승격 조건을 모두 충족해 `[계획]`으로 전환되어 있다.
+  - [ ] agent-ui 정의와 구현 계획이 binary 계약 및 기능 Task에 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- macOS 우선 Flutter 설정·운영 UI와 설치 가능한 `.app` shell
+- binary 측 local proto-socket을 통한 provider/project 조회, config read/write, 실행 상태·event·control 소비
+- YAML에서 설정 가능한 provider/global 기본값, project override, ordered selection rule과 자동 실행 설정 전체의 UI 편집 표면
+- `iop-agent` sidecar 시작·중단·재연결, background lifecycle, tray/menu와 project별 상태·오류·로그 표면
+
+## 기능
+
+### Epic: [config-ops-ui] 설정과 운영 표면
+
+CLI 사용 없이 runtime 설정과 project 작업 상태를 관리하는 UI capability를 묶는다.
+
+- [ ] [config-parity] UI가 현재 YAML schema의 모든 사용자 설정을 손실 없이 조회·편집·검증하고 project override와 ordered rule priority를 보존한다.
+- [ ] [project-registry] 명시 등록 project와 workspace instance를 조회·추가·수정·제거하고 clone/worktree/branch 식별 정보를 표시한다.
+- [ ] [runtime-control] project별 auto-run, start, stop, resume와 대기 중인 작업·Milestone 상태를 local control 계약으로 관리한다.
+- [ ] [ops-surface] provider/model, quota/status, 작업 loop, 오류와 project-local log 위치를 현재 runtime 관측 수준보다 축소하지 않고 표시한다.
+
+### Epic: [macos-delivery] macOS 제품 수명주기
+
+Flutter shell과 `iop-agent` binary를 하나의 설치·실행 경험으로 제공하는 산출물을 묶는다.
+
+- [ ] [binary-lifecycle] 앱이 포함된 `iop-agent` binary를 단일 owner로 시작·종료하고 창 종료, 명시 종료, 재실행과 비정상 종료에서 orphan·중복 process를 만들지 않는다.
+- [ ] [desktop-shell] 설정 창, background/tray 진입점과 최소 상태·오류 surface가 macOS app bundle로 패키징된다.
+- [ ] [reconnect] socket 단절, binary 재시작과 config revision 변경 후 UI가 마지막 확인 상태를 오인하지 않고 재동기화한다.
+- [ ] [logged-smoke] 실제 로그인된 macOS 환경에서 설치, 최초 실행, YAML import/편집, 다중 project 제어, 종료·재시작과 오류 표면화를 검증한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 후속 Flutter 제품 범위를 분리한 최초 스케치이며 승격 조건과 구현 gate가 남아 있다.
+- 검토 항목: 없음
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- Unity 3D Character, transparent character window와 animation
+- provider credential 로그인, token 저장과 계정 전환
+- provider 선택, retry/failover, AgentTaskManager와 workflow 상태 머신의 Flutter 재구현
+- Edge/Control Plane 포함, Windows/Linux packaging과 배포 채널 운영
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/desktop-agent-ui`, `apps/desktop-agent`, `packages/go`, `proto/iop`, `agent-ui`
+- 표준선(선택): Flutter는 client이며 설정 원본, config validation, provider 실행과 작업 상태 전이는 `iop-agent` binary가 소유한다.
+- 표준선(선택): 화면 설정은 YAML의 부분집합이 아니라 전체 사용자 설정을 다루며, binary 조회 결과로 안전한 초기값을 제안하되 project override를 명시적으로 보존한다.
+- 표준선(선택): macOS를 최초 지원 플랫폼으로 고정하고 Windows/Linux는 별도 후속 범위로 둔다.
+- 큐 배치: [oto 자동화 스케줄러와 CI-CD 연동 (2차)](oto-automation-scheduler-second-wave.md) 뒤, [Unity 3D Desktop Character](unity-3d-desktop-character.md) 앞
+- 선행 작업: [IOP Agent CLI Runtime](iop-agent-cli-runtime.md)
+- 후속 작업: [Unity 3D Desktop Character](unity-3d-desktop-character.md), Windows/Linux Desktop packaging
+- 확인 필요: 없음

agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md

@@ -19,7 +19,7 @@
 - [ ] 보류된 [공통 Agent Task Runtime과 Desktop Agent](shared-agent-task-runtime-desktop-agent.md)와 [기존 SDD](../../../sdd/automation-runtime-bridge/shared-agent-task-runtime-desktop-agent/SDD.md)의 runtime 요구사항을 CLI 범위로 이관하고 Python·Node 참조 동작의 parity inventory를 고정한다.
 - [x] 공통 runtime lifecycle, YAML config, checkpoint, provider process와 binary 측 local proto-socket 경계를 [SDD](../../../sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md)에 고정하고 필요한 agent-contract 작성 범위를 확정했다.
 - [x] 기능 Task와 Acceptance Scenario·Evidence Map을 연결했다.
-- [ ] Flutter 설정 UI와 Unity 3D Character를 각각 후속 Milestone 후보로 분리하고 현재 범위에 UI 구현이 섞이지 않았는지 확인한다.
+- [x] [Flutter Desktop Control UI](flutter-desktop-control-ui.md)와 [Unity 3D Desktop Character](unity-3d-desktop-character.md)를 각각 후속 Milestone으로 분리하고 현재 범위에서 client UI 구현을 제외했다.
 
 ## 구현 잠금
 
@@ -103,13 +103,14 @@ UI 없이도 설치·설정·실행·관측 가능한 제품 표면을 묶는다
 - 관련 경로: `packages/go`, `apps/node`, `proto/iop`, `agent-task`, `agent-roadmap`
 - 표준선(선택): `iop-agent`는 headless runtime과 CLI entry이며 설정·project registry·최소 checkpoint의 관리 주체다. workspace는 작업 파일의 source of truth이지 runtime 설정 소유자가 아니다.
 - 표준선(선택): Node와 `iop-agent`는 공통 provider/manager package를 소비하고 host-specific command, wire와 lifecycle adapter만 가진다.
-- 표준선(선택): Python은 정책·오류·관측 behavior fixture로만 사용하고 Go 타입과 테스트로 재구현한다. Python에 없는 선택 엔진은 완료된 selector와 group routing Milestone을 기준으로 작성한다.
+- 표준선(선택): Python은 정책·오류·관측 behavior fixture로만 사용하고 Go 타입과 테스트로 재구현한다. Python에 없는 선택 엔진은 완료된 selector와 group routing Milestone 요구사항을 기준으로 작성한다.
 - 표준선(선택): CLI는 모든 선언 provider를 대상으로 전체 동등성을 제공하며 지원 provider, 선택 엔진, quota, review와 복구 기능을 축소한 선행판을 두지 않는다.
 - 표준선(선택): local proto-socket은 binary가 소유하는 client-neutral 경계다. Flutter와 Unity는 후속 Milestone에서 서로 통신하지 않고 각자 이 경계를 소비한다.
 - 표준선(선택): 자동 실행과 provider approval bypass는 기본 on이며 사용자는 언제든 project를 중단할 수 있다. provider authentication과 credential은 각 CLI가 소유하고 `iop-agent`는 이미 인증된 실행만 사용한다.
 - 표준선(선택): 세부 command 이름, package/file 배치, proto field, retry backoff 수치와 log serialization은 계획·SDD·contract 단계에서 기존 구조와 표준안으로 정하며 사용자 결정 항목으로 올리지 않는다.
 - 이전 설계 참조: [공통 Agent Task Runtime과 Desktop Agent](shared-agent-task-runtime-desktop-agent.md)와 [기존 SDD](../../../sdd/automation-runtime-bridge/shared-agent-task-runtime-desktop-agent/SDD.md). 결합된 Desktop delivery는 구현하지 않고 CLI parity 요구사항만 계획 승격 시 이관한다.
-- 큐 배치: [CLI Agent Group Grade Routing](cli-agent-group-grade-routing.md) 뒤, [에이전트 작업 루프 오케스트레이션 MVP](agent-workflow-loop-orchestration-mvp.md) 앞
-- 선행 작업: [Agent Task 동적 실행 Target Selector](../../../archive/phase/automation-runtime-bridge/milestones/agent-task-runtime-target-selector.md), [Pi CLI Provider Integration](pi-cli-provider-integration.md), [CLI Agent Group Grade Routing](cli-agent-group-grade-routing.md)
-- 후속 작업: Flutter Desktop 설정·운영 UI Milestone, Unity 3D Character Milestone, [에이전트 작업 루프 오케스트레이션 MVP](agent-workflow-loop-orchestration-mvp.md), [Provider 사용량 알림과 운영 표면](provider-usage-notification-operations-surface.md)
+- 큐 배치: [Stream Evidence Gate Core](../../knowledge-tool-optimization-extension/milestones/stream-evidence-gate-core.md) 뒤, [Flutter Desktop Control UI](flutter-desktop-control-ui.md) 앞
+- 선행 작업: [Stream Evidence Gate Core](../../knowledge-tool-optimization-extension/milestones/stream-evidence-gate-core.md), [Agent Task 동적 실행 Target Selector](../../../archive/phase/automation-runtime-bridge/milestones/agent-task-runtime-target-selector.md)
+- 참조·연결 작업: [Pi CLI Provider Integration](pi-cli-provider-integration.md), [CLI Agent Group Grade Routing](cli-agent-group-grade-routing.md)
+- 후속 작업: [Flutter Desktop Control UI](flutter-desktop-control-ui.md), [Unity 3D Desktop Character](unity-3d-desktop-character.md), [에이전트 작업 루프 오케스트레이션 MVP](agent-workflow-loop-orchestration-mvp.md), [Provider 사용량 알림과 운영 표면](provider-usage-notification-operations-surface.md)
 - 확인 필요: 없음

agent-roadmap/phase/automation-runtime-bridge/milestones/shared-agent-task-runtime-desktop-agent.md

@@ -17,7 +17,7 @@
 ## 보류 사유
 
 - 공통 runtime, Flutter Desktop과 배포를 한 번에 구현하는 결합 범위는 더 이상 실행하지 않는다.
-- 현재 첫 구현 범위는 [IOP Agent CLI Runtime](iop-agent-cli-runtime.md)으로 분리했으며, 이 문서와 SDD는 CLI 요구사항 이관 및 후속 Flutter·Unity Milestone 작성의 참조로만 유지한다.
+- 현재 범위는 [IOP Agent CLI Runtime](iop-agent-cli-runtime.md), [Flutter Desktop Control UI](flutter-desktop-control-ui.md), [Unity 3D Desktop Character](unity-3d-desktop-character.md)로 분리했으며, 이 문서와 SDD는 이관 요구사항의 참조로만 유지한다.
 
 ## 승격 조건
 
@@ -34,7 +34,7 @@
   - [ ] SDD 사용자 리뷰가 없거나 승인·해결되었다.
   - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
   - [ ] Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
-- 결정 필요: 현재 보류. [D01 범위 이관 기록](../../../sdd/automation-runtime-bridge/shared-agent-task-runtime-desktop-agent/user_review_0.log)은 후속 Flutter Desktop Milestone 범위이며 IOP Agent CLI 결정 항목이 아니다.
+- 결정 필요: 현재 보류. [D01 범위 이관 기록](../../../sdd/automation-runtime-bridge/shared-agent-task-runtime-desktop-agent/user_review_0.log)은 [Flutter Desktop Control UI](flutter-desktop-control-ui.md) 범위이며 IOP Agent CLI 결정 항목이 아니다.
 
 ## 범위
 
@@ -188,7 +188,7 @@ Edge 없이 실행되는 macOS 제품 껍데기와 설치·운영 기준을 제
 - 표준선(선택): Desktop은 Flutter가 관리하는 local Go sidecar process를 기본 topology로 삼고, Node는 동일 library를 in-process로 사용한다. 정확한 IPC와 lifecycle 계약은 SDD 잠금에서 고정한다.
 - 표준선(선택): 설정 merge는 app-owned defaults 뒤 app registry의 project override를 적용하며 ordered rule array는 전체 교체한다. 현재 실행은 immutable revision을 사용하고 hot reload는 다음 agent invocation 경계에서만 활성화한다.
 - 표준선(선택): 자동 실행과 approval bypass는 기본 on이다. auth는 CLI가 소유하고 app은 이미 인증된 실행만 사용한다.
-- 큐 배치: [CLI Agent Group Grade Routing](cli-agent-group-grade-routing.md) 뒤, [Provider 사용량 알림과 운영 표면](provider-usage-notification-operations-surface.md) 앞의 기존 작업 루프 위치를 유지한다.
+- 큐 배치: 보류되어 전역 큐에서 제외하고 [IOP Agent CLI Runtime](iop-agent-cli-runtime.md) -> [Flutter Desktop Control UI](flutter-desktop-control-ui.md) -> [Unity 3D Desktop Character](unity-3d-desktop-character.md)로 대체한다.
 - 선행 작업: [Agent Task 동적 실행 Target Selector](../../../archive/phase/automation-runtime-bridge/milestones/agent-task-runtime-target-selector.md), [Pi CLI Provider Integration](pi-cli-provider-integration.md), [CLI Agent Group Grade Routing](cli-agent-group-grade-routing.md)
-- 후속 작업: [에이전트 작업 루프 오케스트레이션 MVP](agent-workflow-loop-orchestration-mvp.md), 완성형 Flutter 설정 UI, Windows/Linux packaging, 외부 알림·운영 dashboard, signing/notarization과 배포 채널
-- 확인 필요: 현재 없음. Desktop background lifecycle은 후속 Flutter Desktop Milestone을 만들 때 다시 검토한다.
+- 후속 작업: [Flutter Desktop Control UI](flutter-desktop-control-ui.md), [Unity 3D Desktop Character](unity-3d-desktop-character.md), [에이전트 작업 루프 오케스트레이션 MVP](agent-workflow-loop-orchestration-mvp.md), Windows/Linux packaging, 외부 알림·운영 dashboard, signing/notarization과 배포 채널
+- 확인 필요: 현재 없음. Desktop background lifecycle은 [Flutter Desktop Control UI](flutter-desktop-control-ui.md)의 승격 조건에서 검토한다.

agent-roadmap/phase/automation-runtime-bridge/milestones/unity-3d-desktop-character.md

@@ -0,0 +1,86 @@
+# Milestone: Unity 3D Desktop Character
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+`iop-agent`의 작업 상태를 투명 배경의 3D 캐릭터로 표현하는 macOS Unity client를 제공한다.
+Flutter UI와 직접 결합하거나 실행 로직을 중복하지 않고, 같은 local proto-socket을 독립적으로 소비하는 데스크톱 캐릭터 표면으로 구현한다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] [IOP Agent CLI Runtime](iop-agent-cli-runtime.md)의 client-neutral status/event/control 계약에서 캐릭터가 소비할 상태와 재연결 규칙을 확정한다.
+- [ ] idle, working, reviewing, waiting, error와 completed 상태를 교체 가능한 3D avatar·animation state로 매핑하고 transparent window 상호작용 범위를 정리한다.
+- [ ] macOS transparent rendering, click-through, drag, always-on-top, resource budget과 실제 로그인 환경 smoke를 기능 Task와 연결한다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 불필요
+- SDD 문서: 없음
+- SDD 사유: 현재는 확정된 local event 계약을 소비할 독립 Unity client의 제품 범위를 나누는 스케치이며, native window plugin·process lifecycle·배포 계약을 구현 가능한 계획으로 승격할 때 SDD 필요 여부를 다시 판정한다.
+- 잠금 해제 조건: 아래 체크리스트
+  - [ ] 승격 조건을 모두 충족해 `[계획]`으로 전환되어 있다.
+  - [ ] avatar 상태 모델과 macOS window/platform 검증 계획이 기능 Task에 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- macOS 우선 Unity 3D client와 transparent·frameless character window
+- binary 측 local proto-socket을 통한 runtime 상태·event 소비와 연결 상태 표시
+- idle, working, reviewing, waiting, error, completed를 표현하는 avatar·animation state machine
+- drag, click/click-through, always-on-top, 위치 저장과 binary 단절·재연결 동작
+
+## 기능
+
+### Epic: [character-runtime] 캐릭터 상태 client
+
+runtime event를 안정된 3D 표현 상태로 바꾸는 client capability를 묶는다.
+
+- [ ] [socket-client] Unity client가 Flutter와 독립적으로 `iop-agent`에 연결하고 snapshot 이후 event를 순서대로 소비하며 재연결 시 상태를 재동기화한다.
+- [ ] [state-mapping] provider/model 내부 세부를 캐릭터에 하드코딩하지 않고 runtime 상태를 idle, working, reviewing, waiting, error와 completed animation으로 결정적으로 매핑한다.
+- [ ] [avatar-contract] 교체 가능한 avatar, animation clip과 상태 transition 계약을 제공해 특정 캐릭터 asset에 runtime을 종속시키지 않는다.
+- [ ] [error-surface] 인증·provider·quota·작업 오류와 binary 연결 실패를 정상 작업 animation으로 오인하지 않고 명시적인 상태로 표현한다.
+
+### Epic: [transparent-delivery] 투명 창과 macOS 배포
+
+3D 캐릭터를 데스크톱 표면에 안정적으로 표시하는 플랫폼 산출물을 묶는다.
+
+- [ ] [transparent-window] alpha 투명 배경, frameless·always-on-top 창과 다중 모니터 좌표를 macOS에서 제공한다.
+- [ ] [pointer-policy] 캐릭터 hit 영역의 click/drag와 배경 click-through를 전환 가능하게 제공하고 사용자가 언제든 창을 이동·숨김·종료할 수 있다.
+- [ ] [lifecycle-budget] 독립 client가 `iop-agent` binary를 중복 실행하지 않고 연결·종료하며 idle/active resource budget과 animation throttling을 지킨다.
+- [ ] [logged-smoke] 실제 로그인된 macOS 환경에서 투명 렌더링, 입력, animation, socket 재연결, sleep/wake와 다중 모니터 동작을 검증한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 후속 Unity 캐릭터 범위를 분리한 최초 스케치이며 승격 조건과 구현 gate가 남아 있다.
+- 검토 항목: 없음
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- Flutter 설정·운영 화면과 YAML 편집 기능
+- provider 선택, task orchestration, retry/failover와 binary lifecycle의 Unity 재구현
+- 최종 캐릭터 IP·아트 스타일 확정과 대규모 avatar marketplace
+- Windows/Linux transparent window와 mobile/web 배포
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/desktop-character`, `packages/go`, `proto/iop`, `agent-ui`
+- 표준선(선택): Unity는 독립 표시 client이며 `iop-agent`가 상태·event 원본과 control 권한을 소유한다.
+- 표준선(선택): Flutter와 Unity는 서로의 process나 protocol을 소유하지 않고 같은 client-neutral local proto-socket을 각각 소비한다.
+- 표준선(선택): 첫 avatar는 교체 가능한 검증 asset으로 두고 최종 캐릭터 디자인은 runtime·window capability와 분리한다.
+- 큐 배치: [Flutter Desktop Control UI](flutter-desktop-control-ui.md) 뒤, 전역 큐 마지막
+- 선행 작업: [IOP Agent CLI Runtime](iop-agent-cli-runtime.md)
+- 후속 작업: Windows/Linux Character packaging과 avatar content 확장
+- 확인 필요: 없음

agent-roadmap/priority-queue.md

@@ -75,3 +75,9 @@
 
 24. [oto 자동화 스케줄러와 CI-CD 연동 (2차)](phase/automation-runtime-bridge/milestones/oto-automation-scheduler-second-wave.md)
     oto 기반 자동화, scheduler, CI-CD 연동 후보를 스케치한다.
+
+25. [Flutter Desktop Control UI](phase/automation-runtime-bridge/milestones/flutter-desktop-control-ui.md)
+    `iop-agent` local proto-socket을 소비해 YAML 전체 설정과 project·실행·오류·로그를 관리하는 macOS Flutter 설정·운영 UI를 제공한다.
+
+26. [Unity 3D Desktop Character](phase/automation-runtime-bridge/milestones/unity-3d-desktop-character.md)
+    같은 local proto-socket을 독립적으로 소비하고 작업 상태를 투명 배경 3D 캐릭터와 animation으로 표현하는 macOS Unity client를 제공한다.