---
spec_doc_type: spec
spec_id: runtime/iop-agent-cli-runtime
status: 구현됨
source_evidence:
  - type: contract
    path: agent-contract/inner/iop-agent-cli-runtime.md
    notes: 독립 host lifecycle, config, durable state와 local-control 경계
  - type: contract
    path: agent-contract/inner/agent-runtime.md
    notes: host가 소비하는 공통 provider와 AgentTaskManager 계약
  - type: code
    path: apps/agent/internal/command/root.go
    notes: headless CLI command surface
  - type: code
    path: apps/agent/internal/bootstrap/module.go
    notes: daemon, task loop, project log, client process와 local-control 조립
  - type: code
    path: apps/agent/internal/taskloop/module.go
    notes: project lifecycle, milestone selection, preview, reconciliation과 상태 projection
  - type: code
    path: apps/agent/internal/localcontrol/server.go
    notes: same-OS-user Unix proto-socket server
  - type: test
    path: apps/agent/cmd/agent/main_test.go
    notes: headless S10 transcript와 compiled-binary lifecycle coverage
  - type: test
    path: apps/agent/internal/taskloop/module_test.go
    notes: fake provider persisted lifecycle, rollback과 restart coverage
  - type: sdd
    path: agent-roadmap/archive/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md
    notes: acceptance scenario와 evidence map
  - type: complete-log
    path: agent-task/archive/2026/07/m-iop-agent-cli-runtime_1/complete.log
    notes: cli-surface final PASS와 final verification evidence
---

# 스펙: IOP Agent CLI Runtime

## 목적

개인 장비에서 독립 실행되는 `iop-agent` headless host의 현재 기능을 정리한다. 이 host는 공통 provider와 AgentTaskManager를 조립해 CLI·daemon·local control 표면으로 제공하며, Node나 Python dispatcher를 대체하는 별도 shared-runtime 구현을 소유하지 않는다.

## 기능 목록

| 기능 | 설명 |
|------|------|
| Headless CLI | `validate`, provider/project/milestone 조회·선택, `preview`, `serve`, `start`, `stop`, `resume`, `status`와 제한된 `task-loop` 명령을 text 또는 JSON으로 제공한다. |
| 설정 조합 | repo-global의 비밀정보 없는 기본값과 user-local device/project override를 엄격히 검증·합성하고, 실행은 캡처한 불변 revision을 사용한다. |
| 수동 project lifecycle | project의 Milestone을 명시 선택한 뒤에만 시작하며, preview는 durable state나 provider invocation 없이 같은 선택·dependency 판정을 반환한다. |
| 지속 runtime과 관측 | daemon은 공통 runtime의 reconciliation을 주기적으로 수행하고 project별 work, dispatch ordinal, overlay/integration, blocker와 project log를 상태로 제공한다. |
| Local control과 client process | 소유 OS 사용자의 local proto-socket을 통해 상태와 project/client control을 제공하고, Flutter·Unity subprocess의 시작·중단·복구와 Unity detail 요청의 Flutter start/focus 중계를 소유한다. |
| 안전한 host 조립 | bootstrap은 하나의 durable state store 위에 task runtime, project log, client process manager와 local-control server를 조립하며 시작 실패 시 이미 시작한 component를 역순 정리한다. |

## 범위

- 포함: `iop-agent` CLI/daemon, repo-global·user-local runtime config 조합, project lifecycle projection, local socket, client process와 host-owned durable state.
- 제외: 공통 provider 실행·selection·retry·AgentTaskManager 알고리즘, Edge-Node protobuf 변환, Flutter·Unity UI 구현, provider 로그인과 credential 저장, active `agent-task`의 dispatcher/worker/review orchestration.

## 주요 흐름

```mermaid
flowchart LR
  Operator[운영자 또는 same-user client] --> CLI[iop-agent CLI]
  CLI --> Command[Command service]
  Command --> Snapshot[Validated runtime snapshot]
  Snapshot --> Runtime[taskloop.Runtime]
  Runtime --> Shared[Shared Agent Runtime]
  Shared --> State[Durable state and project logs]
  CLI -->|serve| Bootstrap[Daemon bootstrap]
  Bootstrap --> Runtime
  Bootstrap --> Socket[Local proto-socket]
  Socket --> ClientManager[Flutter/Unity process manager]
```

`serve`는 지속 reconciliation과 local control을 실행한다. 나머지 CLI command는 같은 durable state를 제한적으로 조회하거나 명시 lifecycle intent를 기록하며, preview는 side effect를 만들지 않는다.

## 계약

- [IOP Agent CLI Runtime contract](../../agent-contract/inner/iop-agent-cli-runtime.md)는 standalone host lifecycle, config, local control과 client process 경계를 정의한다.
- [Agent Runtime contract](../../agent-contract/inner/agent-runtime.md)는 host가 소비하는 공통 provider와 AgentTaskManager 의미를 정의한다.
- [SDD](../../agent-roadmap/archive/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md)는 S10 CLI와 관련 acceptance/evidence 연결을 정의한다.

## 설정/데이터/이벤트

- repo-global input은 read-only이며 provider/default/selection policy template만 포함한다. user-local input은 device root, project registration, override, client launch policy와 durable state 위치를 포함한다.
- runtime snapshot은 두 입력의 revision과 합성 결과를 보존한다. 현재 실행은 이미 캡처한 revision을 유지하고, 유효한 다음 revision만 이후 invocation에 반영한다.
- local proto-socket은 owner-only state root와 socket permissions, same-OS-user peer credential을 전제로 한다. app token fallback은 없다.
- host는 project/work 상태, local command receipt, client process identity와 project log를 durable record로 보존한다. 공통 runtime의 lifecycle, admission, review와 integration 결정은 공유 계약을 따른다.

## 검증

- `go test -count=1 ./apps/agent/...` - CLI, bootstrap, task loop, local control과 client process package가 현재 checkout에서 통과해야 한다.
- `go test -count=1 -race ./apps/agent/internal/taskloop ./apps/agent/internal/command ./apps/agent/internal/bootstrap ./packages/go/agenttask ./packages/go/agentstate` - shared state와 host lifecycle의 race regression을 확인한다.
- `make build-agent` 및 `make test-iop-agent-logged-smoke-preflight` - binary build와 logged-smoke harness preflight를 확인한다.

## 한계와 주의사항

- 실제 provider 로그인과 logged-in macOS smoke는 credential을 이 spec이나 repo-global config에 기록하지 않고 별도 환경에서 수행한다.
- `iop-agent`는 active `agent-task`의 dispatcher, worker, self-check와 official review 경로를 대체하거나 그 경로에서 실행되지 않는다.
- Flutter·Unity는 local control을 소비하는 client이며 provider 선택, task scheduling 또는 daemon ownership을 갖지 않는다.

## 변경 기록

- 2026-07-31: [IOP Agent CLI Runtime Milestone](../../agent-roadmap/archive/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md)의 종료 검토를 위해 현재 코드·계약·S10 완료 evidence를 기준으로 생성했다.