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

Milestone: IOP Agent CLI Runtime

위치

• Roadmap: ROADMAP.md
• Phase: PHASE.md

목표

모델이 감시하던 Agent Task 실행 루프를 프로덕션 Go runtime과 독립 실행 가능한 iop-agent CLI로 이전한다. 현재 Python dispatcher와 Node CLI runtime에서 검증된 provider 실행, 선택, quota, 오류, 복구, review와 관측 동작을 축소하지 않고 흡수하며, 개인 장비의 단일 iop-agent가 여러 project와 Flutter·Unity subprocess를 소유하고 Node도 같은 공통 CLI Provider·AgentTaskManager 구현을 소비하게 한다.

상태

[완료]

승격 조건

• 폐기된 공통 Agent Task Runtime과 Desktop Agent와 기존 SDD의 runtime 요구사항을 CLI 범위로 이관하고, 스킬 기반 1차 테스트를 거쳐 안정화된 Python 작업과 Node 참조 동작을 parity inventory 입력으로 고정했다.
• 공통 runtime lifecycle, YAML config, checkpoint, provider process와 binary 측 local proto-socket 경계를 SDD에 고정하고 필요한 agent-contract 작성 범위를 확정했다.
• 기능 Task와 Acceptance Scenario·Evidence Map을 연결했다.
• Flutter Desktop Control UI와 Unity 3D Desktop Character를 각각 후속 Milestone으로 분리하고 현재 범위에서 client UI 구현을 제외했다.

구현 잠금

• 상태: 해제
• SDD: 필요
• SDD 문서: SDD.md
• SDD 사유: 공통 runtime/Node host 경계, lifecycle, task overlay·change-set 통합, retry·identity·checkpoint, config/proto event 계약과 실제 로그인 환경 smoke를 함께 변경한다.
• 잠금 해제 조건: 아래 체크리스트
  • SDD 잠금이 해제되어 있다.
  • D05 provider approval 기본 정책이 승인·해결되었다.
  • D06 병렬 COW Overlay와 직렬 통합이 승인·해결되었다.
  • Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
  • Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
  • 나머지 승격 조건을 충족해 [계획]으로 전환되어 있다.
• 결정 필요: 없음

범위

• packages/go의 공통 CLI Provider·AgentTaskManager와 이를 실행하는 독립 iop-agent binary/CLI
• Node 내부 CLI provider를 공통 모듈 소비 방식으로 전환하고 Node·iop-agent에 provider나 manager 구현을 중복하지 않는 경계
• 선언된 provider와 provider/model/profile 공식 이름, one-shot/persistent 실행, stream/session/resume, quota/status, cancel, retry/failover와 오류 표면화
• repo-global 설정의 비밀정보 없는 provider/selection 공통 기본값·정책 템플릿과 user-local 설정의 project registry, 장비 경로, provider 실행 참조, project override, 자동 재개 및 client process 설정을 분리한다. runtime은 repo-global 설정을 쓰지 않고 local override와 checkpoint만 갱신한다.
• 사용자가 project와 Milestone을 선택해 최초 실행을 명시적으로 시작하며 ready Milestone을 자동 시작하지 않는다. 시작 기록이 있는 중단 작업만 기본 자동 재개하되 auto_resume_interrupted local 설정으로 조정한다.
• 등록 workspace 선택은 해당 canonical folder 안의 agent 작업을 사전 승인한 것으로 본다. iop-agent는 dispatch 전에 workspace grant와 provider의 unattended/approval-bypass 실행 capability를 검증하고, 불충족이면 agent를 호출하지 않고 project-local blocker와 사용자 설정 안내 알림을 낸다.
• dependency-ready는 스킬의 명시 predecessor만 따르고 숫자 순서에서 의존성을 추론하지 않는다. 서로 다른 project/workspace instance와 같은 canonical workspace의 independent sibling을 병렬 실행하되, 같은 workspace의 각 task는 pinned base snapshot 위의 독립 copy-on-write writable layer에서 실행하고 canonical base를 직접 쓰지 않는다.
• COW, 격리 worktree 또는 full clone이 적용되지 않은 project 구현 shared checkout에서는 PLAN의 Modified Files Summary를 deterministic write-set으로 사용한다. dispatcher는 workspace 전체 task group이 공유하는 claim ledger에서 교집합이 있는 active task를 논리적 predecessor로 만들지 않고 실행 대기시키며, worker·selfcheck·official review·follow-up 전체 lifecycle 동안 원자적 file claim을 유지·이관·해제한다. 이 claim은 같은 target file의 동시 수정을 막는 최소 guard이며, disjoint file을 수정하는 다른 task의 미완성 변경까지 읽는 build/test를 격리하지는 않는다.
• 완료 task는 immutable change set으로 동결해 결정적 순서로 canonical workspace에 하나씩 통합한다. clean three-way merge는 자동 승인하고 conflict, 검증 실패와 관리되지 않은 base drift는 task-local blocker로 보존한다. 실제 Git branch/index/commit 의미가 필요한 task만 격리 worktree 또는 full clone을 fallback으로 사용한다.
• project-owned Milestone/Plan/Code Review/USER_REVIEW/completion artifact를 해석하는 workflow adapter, provider-neutral review submission matcher와 Pi same-context evidence repair
• 장비·소유 OS 사용자 범위의 iop-agent singleton lease, workspace별 invocation lease, durable route/checkpoint, process/session locator, failure budget, restart reconciliation과 task-local blocker
• project-local agent-log와 runtime-owned WORK_LOG.md의 task별 pinned loop, attempt, locator 및 exactly-once archive reconciliation
• iop-agent가 Flutter·Unity를 소유 subprocess로 시작·중단·복구하고, 같은 OS 사용자에게 제한된 local proto-socket으로 상태·event·control을 제공하는 경계. Unity의 상세 보기 요청은 iop-agent가 Flutter를 시작하거나 전면 표시하는 command로 중계한다. 실제 protocol 원문은 구현 계획의 첫 계약 작업에서 agent-contract로 고정한다.

기능

Epic: [runtime-core] 공통 Provider와 AgentTaskManager

Node와 독립 CLI가 같은 실행 구현을 소비하는 runtime capability를 묶는다.

• [common-runtime] CLI Provider, emitter/stream/session, quota/status, failure codec과 AgentTaskManager가 공통 Go package의 단일 구현으로 제공된다.
• [provider-catalog] YAML에 선언된 지원 provider/model/profile을 discovery하고 이미 인증된 실행 환경에서 run, resume, cancel과 status를 수행한다.
• [task-manager] AgentTaskManager가 모델 감시 없이 project 작업 상태를 읽고, 수동 선택·시작된 Milestone의 dependency-ready task를 격리 mode로 dispatch하며 review·직렬 통합과 후속 작업을 끝까지 진행하고 중단된 시작 기록은 설정에 따라 자동 재개한다.
• [guardrail-admission] 등록 canonical workspace의 사전 승인 범위, path containment, task별 writable-root confinement와 provider별 unattended/approval-bypass capability를 dispatch 전에 검증하고, 불충족이면 실행 없이 typed blocker·설정 안내 event를 제공한다.
• [node-consumer] Node가 공통 runtime을 소비하는 얇은 bridge로 전환되고 기존 Node 실행 계약과 provider 동작을 보존한다.

Epic: [policy-state] 선택 정책과 내구 상태

여러 project와 provider를 무인 실행하면서 선택·복구 결과를 재현할 수 있는 상태를 묶는다.

• [config-registry] repo-global read-only defaults/policy와 user-local registry/override/state의 schema·소유권·merge precedence, ordered rule array 전체 교체, isolation backend·local root·retention 설정, file watcher와 immutable execution revision 경계가 제공된다.
• [target-policy] 공통 evaluator가 host/project 정책을 주입받아 조건과 배열 순서에 따라 provider/model 하나를 반환하고 durable route plan에 판단 근거와 후보 이력을 보존한다.
• [quota-failure] provider별 quota/status와 알려진 오류를 typed result로 정규화하고 선언 정책 안에서만 retry/failover하며 unknown 오류는 해당 work unit에 표면화한다.
• [workflow-evidence] 모든 provider/model/execution class에 같은 artifact matcher와 review gate를 적용하고 Pi의 selfcheck 후 미작성 review artifact는 같은 native context에서 보완한다.
• [state-recovery] 장비의 singleton supervisor와 workspace별 manager/base-mutation lease, checkpoint, process/session·overlay locator, integration queue/record, failure budget과 completion reconciliation이 restart·cancel·부분 실패에서도 중복 실행 없이 복구된다.

Epic: [workspace-isolation] 병렬 Overlay와 통합

같은 canonical workspace를 공유하는 작업을 파일 쓰기 단계에서 격리하고 검증된 결과만 base에 반영하는 capability를 묶는다.

• [overlay-workspace] dependency-ready task마다 tracked·untracked·dirty content를 포함한 pinned base fingerprint와 독립 writable layer, 통합 read view 및 task별 temp/cache 경로를 제공한다. unattended/bypass child도 writable root가 해당 layer로 제한되어 canonical base·공용 Git index/ref·다른 task layer를 직접 변경하지 못한다.
• [change-set-integration] 완료 overlay를 base fingerprint·file operation·write-set·검증 evidence를 가진 immutable change set으로 동결하고 dispatch ordinal에 따라 직렬 three-way 통합한다. clean 결과는 자동 승인하며 conflict·검증 실패·관리되지 않은 base drift는 원본 overlay를 보존한 task-local blocker가 되고 partial base mutation 없이 뒤의 독립 change set 통합은 계속된다.
• [shared-checkout-write-lock] COW/worktree/clone이 적용되지 않은 project 구현 checkout에서는 PLAN의 정확히 하나인 Modified Files Summary를 LLM 없이 정규화한 file write-set으로 사용하고, dispatcher가 workspace 전체 task group의 공통 ledger에서 worker 시작 전 전체 key를 원자적으로 claim해 worker·selfcheck·official review 동안 유지하며 follow-up PLAN에는 claim을 원자적으로 이관한다. 교집합은 dependency가 아닌 대기 상태로 두고, 누락·중복·빈 값·glob·workspace 외부·디렉터리 target, 통제되지 않은 PLAN revision 변경과 restart 시 소유권 불명확 상태는 fail-closed한다. verified completion과 live owner 부재가 확인되거나 명시적 reset이 task-owned mutation의 안전한 정리를 검증한 뒤에만 release/reconcile하고, shared checkout에서 만든 최종 evidence는 다른 active mutation이 없는 stable source 또는 격리 workspace에서 재검증한다.

Epic: [cli-delivery] Headless CLI와 운영 검증

UI 없이도 설치·설정·실행·관측 가능한 제품 표면을 묶는다.

• [cli-surface] iop-agent가 binary와 repo-global/local 설정 예시, 설정 검증, provider/project/Milestone 조회·선택·preview, serve/start/stop/resume, overlay/integration 상태와 blocker 확인을 일관된 CLI command로 제공한다.
• [project-logs] 현재 최소 관측 수준을 축소하지 않는 project-local event/log와 task별 loop·attempt·process/overlay/change-set/integration locator가 연결된 WORK_LOG timeline을 제공한다.
• [parity-cutover] Python·Node 동작을 absorb | replace | not-applicable로 분류하고 미분류 동작, Python runtime 의존성과 Node provider 중복 없이 Go runtime으로 전환한다. Python 구현은 parity와 cutover evidence를 확보할 때까지 참조 fixture로 보존하고 Milestone 완료 전환 시 폐기한다.
• [logged-smoke] 실제 로그인된 macOS CLI 환경에서 discovery, 실행, stream, quota/status, cancel, 재호출, restart와 다중 project 동작을 검증한다.

Epic: [client-control] Local Client Process와 제어

Flutter·Unity client의 process ownership과 같은 사용자 local control 경계를 묶는다.

• [local-control] 같은 OS 사용자의 후속 client가 사용할 local proto-socket의 binary 측 lifecycle, 상태, event와 control endpoint가 별도 app token 없이 OS-user 경계로 제공된다.
• [client-process-manager] 장비의 단일 iop-agent가 Flutter·Unity subprocess를 중복 없이 시작·중단·재연결하고, Unity의 상세 UI command를 Flutter start/focus로 중계하며 client 종료가 runtime 소유권을 역전시키지 않는다.

완료 리뷰

• 상태: 통과
• 요청일: 2026-07-28
• 동기화일: 2026-07-31
• 완료 근거(기존): Node 공통 runtime bridge, provider catalog, guardrail admission, AgentTaskManager, config registry, target policy, quota/failure, workflow evidence, state recovery, workspace overlay, change-set integration, dispatcher workspace ownership의 PASS와 current checkout fresh test를 근거로 13개 기능 Task를 완료 처리했다.
• 완료 근거(추가): project logs, local control, client process manager, logged smoke, parity cutover의 exact Task id Roadmap Completion과 현재 checkout의 공통 Go package test 및 logged-smoke manifest 검증을 근거로 5개 기능 Task를 추가 완료 처리했다.
• 완료 근거(최신): cli-surface closure의 exact Task id Roadmap Completion PASS와 S10 headless CLI lifecycle/status·race·build·logged-smoke preflight evidence를 확인했다. 현재 checkout에서도 격리 cache로 go test -count=1 ./apps/agent/...가 통과했다.
• 검토 항목: 19/19 기능 Task와 각 SDD Acceptance Scenario·Evidence Map 연결, 구현 잠금 해제, 사용자 리뷰 부재를 확인했다.
• Spec sync: updated — IOP Agent CLI Runtime 스펙을 현재 코드·계약·S10 완료 evidence에 맞춰 생성하고 agent-spec 색인에 등록했다.
• agent-ui 상태 반영: 해당 없음
• 리뷰 코멘트: 코드·계약·검증 감사와 Spec sync가 통과했다. 모든 종료 조건을 충족해 [완료] 전환과 archive를 진행한다.

범위 제외

• Flutter 설정·운영 UI, tray, macOS .app shell과 UI가 daemon lifecycle을 관리하는 기능
• Unity 3D Character, transparent window, animation, click-through와 Flutter package 통합
• Flutter·Unity client 구현과 화면 정의. 현재 범위는 binary 측 process ownership과 local protocol 경계 및 fixture client 검증까지만 포함한다.
• provider 로그인, credential/token 저장, 계정 전환과 billing 구매 자동화
• 실행 중 개별 action 승인 UI와 prompt. 현재 기본은 등록 workspace 범위의 전자동 approval bypass이며, workspace 밖 권한 확장과 guardrail 우회는 포함하지 않는다.
• agent-ops를 사용하지 않는 일반 요청의 direct/Plan/Milestone 분류와 합성 tool call 주입. 이는 에이전트 작업 루프 오케스트레이션 MVP의 범위다.
• Edge, Control Plane, remote terminal tunnel, 외부 알림/dashboard, oto scheduler/CI-CD와 Windows/Linux desktop packaging
• Python 코드를 production에서 import·실행·번역 호출하거나 진행 중 Python process 상태를 승계하는 방식

작업 컨텍스트

• 관련 경로: packages/go, apps/node, proto/iop, agent-task, agent-roadmap, agent-ops/skills/project/orchestrate-agent-task-loop
• 표준선(선택): 개인 장비의 소유 OS 사용자 범위에서 하나의 active iop-agent만 실행하고 여러 project와 Flutter·Unity subprocess를 관리한다. Flutter·Unity는 client이며 daemon이나 서로의 process를 직접 소유하지 않는다.
• 표준선(선택): repo-global 설정은 비밀정보 없는 공통 provider/default/selection policy template만 버전 관리하고 runtime은 읽기만 한다. user-local 설정·상태는 project registry, 장비 경로, provider command/env reference, project override, 자동 재개, client launch policy, checkpoint/lease를 소유하며 repo-global 뒤에 적용한다. credential은 각 provider CLI가 소유한다.
• 표준선(선택): Node와 iop-agent는 공통 provider/manager package를 소비하고 host-specific command, wire와 lifecycle adapter만 가진다.
• 표준선(선택): 스킬 기반 1차 테스트를 거쳐 안정화된 Python 작업과 이전 Milestone·SDD·실행 결과를 provider, scheduler, workflow artifact, review/finalization, process/session, quota/error, log/reconciliation parity inventory의 입력으로 사용하고 각 동작을 Go 타입과 테스트로 재구현한다.
• 표준선(선택): Python 구현은 Go parity와 cutover evidence가 확보될 때까지 behavior fixture로만 보존하며 production fallback으로 사용하지 않는다. Milestone 완료 전환 시 Python 구현을 폐기하고 남은 runtime 의존성이 없음을 검증한다.
• 표준선(선택): CLI는 모든 선언 provider를 대상으로 전체 동등성을 제공하며 지원 provider, 선택 엔진, quota, review와 복구 기능을 축소한 선행판을 두지 않는다.
• 표준선(선택): 새 Milestone 선택·최초 시작은 항상 수동이고 시작 기록이 있는 중단 작업의 자동 재개만 기본 on이다. 자동 재개 여부는 local 설정이며 사용자는 언제든 project를 중단할 수 있다.
• 표준선(선택): 스킬의 dependency grammar는 명시 predecessor만 권위로 삼고 번호 순서에서 암묵 의존성을 만들지 않는다. 스킬의 canonical-base 직접 병렬 쓰기는 Go runtime에서 replace한다. 같은 workspace의 independent sibling은 pinned base 위의 task별 COW writable layer에서 실행하고 immutable change set만 deterministic serial merge하며, worktree/full clone은 실제 Git 격리가 필요한 경우의 fallback이다.
• 표준선(선택): 위 격리 경계가 아직 적용되지 않은 project implementation shared checkout에서는 PLAN Modified Files Summary의 정규화된 file target을 dispatcher runtime claim의 source로 사용한다. claim 충돌은 기능 의존성이 아니라 같은 target file의 동시 수정을 막기 위한 일시적 admission wait이며, isolated COW/worktree/clone 실행의 병렬성을 제한하지 않는다. file claim은 disjoint target task의 read/build/test 격리까지 보장하지 않으므로 완료 evidence는 다른 active mutation이 없는 stable source 또는 격리 workspace에서 재검증한다.
• 표준선(선택): shared-checkout dispatcher 변경은 같은 repository의 별도 dev clone에서 독립 PLAN으로 구현·검증한 뒤 shared-checkout-write-lock 완료 evidence로 통합한다. 정책 도입 전에 이미 같은 checkout에서 시작된 작업은 번호나 현재 active/archive 위치와 무관하게 잠금이 소급 적용됐다고 간주하지 않고 위 final verification 조건을 다시 충족해야 한다.
• 표준선(선택): local proto-socket은 binary가 소유하고 같은 OS 사용자 client를 신뢰하는 경계다. Flutter와 Unity는 각자 이 경계를 소비하며 Unity의 상세 UI 요청은 iop-agent가 Flutter를 시작·표시하는 command로 중계한다.
• 표준선(선택): 완전 자동화를 기본으로 하며 등록 workspace는 그 canonical folder 범위의 agent 작업을 사용자가 사전 승인한 것으로 본다. provider authentication과 credential은 각 CLI가 소유하고, iop-agent는 workspace guardrail과 unattended/approval-bypass capability가 모두 확인된 실행만 허용한다. 미충족 provider/project는 호출하지 않고 설정 안내 알림을 낸다.
• 표준선(선택): 세부 command 이름, package/file 배치, proto field, retry backoff 수치와 log serialization은 계획·SDD·contract 단계에서 기존 구조와 표준안으로 정하며 사용자 결정 항목으로 올리지 않는다.
• 이전 설계 참조: 공통 Agent Task Runtime과 Desktop Agent와 기존 SDD. 결합된 Desktop delivery는 구현하지 않고 CLI parity 요구사항만 현재 Milestone에 이관했다.
• 큐 배치: Stream Evidence Gate Core 뒤, Flutter Desktop Control UI 앞
• 선행 작업: Stream Evidence Gate Core, Agent Task 동적 실행 Target Selector
• 참조·연결 작업: Pi CLI Provider Integration, CLI Agent Group Grade Routing
• 후속 작업: Flutter Desktop Control UI, Unity 3D Desktop Character, 에이전트 작업 루프 오케스트레이션 MVP, Provider 사용량 알림과 운영 표면
• 확인 필요: 없음