# Milestone: `oto-agent` 등록 흐름

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/archive/phase/edge-direct-oto-agent/PHASE.md`

## 목표

설치된 `oto-agent`가 `iop-node`를 거치지 않고 Edge에 직접 outbound 연결하는 등록 흐름을 구현 가능한 단위로 정리한다.

## 상태

[폐기]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- Edge bootstrap script로 설치된 Linux `oto-agent`가 `~/.oto/agent/config.yaml`을 읽고 Edge에 직접 outbound 등록하는 흐름을 정의한다.
- bootstrap script가 전달한 agent 식별 값과 Edge 연결 정보를 사용해 등록을 시작하는 최소 흐름을 정의한다.
- 백그라운드 등록/실행 후 Edge 등록 완료와 최초 heartbeat 도착까지의 상태 전이를 정의한다.
- Edge identity 검증, checksum/signature, 장기 credential 세부 정책은 MVP 이후 보안 강화 항목으로 분리한다.

## 기능

### Epic: [registration-contract] Edge 직접 등록 계약

bootstrap으로 설치된 Linux `oto-agent`가 설정 파일을 읽고 Edge에 직접 등록되는 상태 전이를 묶는다.

- [x] [token-flow] bootstrap agent 식별 값 또는 token의 전달과 최초 등록 사용 흐름이 정의되어 있다.
- [x] [edge-identity] Edge identity 검증을 MVP 최소 연결 기준과 후속 보안 강화 기준으로 분리해 정리되어 있다.
- [x] [binary-integrity] OTO repo release asset 다운로드 기준과 후속 checksum/signature 강화 기준이 분리되어 있다.
- [x] [service-runtime] 백그라운드 실행 상태와 agent 프로세스 재시작 기준이 정의되어 있으며, bootstrap script 실행 후 다운로드된 `oto-agent`가 `~/.oto/agent/config.yaml`을 통해 Edge에 직접 연결하는 상태 전이가 구현 가능한 수준으로 분해되어 있다.
- [ ] [registration-state] Edge 등록 성공/실패, 최초 heartbeat 기반 online 판정, 재시도 기준과 백그라운드 실행 실패/등록 실패/heartbeat 미도착 상태 구분이 정의되어 있다. 검증: Edge 등록 완료와 최초 heartbeat 도착을 online으로 보는 판정 기준, 실패 상태 구분, 재시도 기준이 구현 가능한 수준으로 설명된다.

## 완료 리뷰

- 상태: 폐기
- 요청일: 없음
- 완료 근거: iop2oto online smoke와 workspace lock 해제 근거는 확인되었지만, 제품 기본 경로가 독립 OTO Server/Runner로 전환되어 iop Edge 직접 등록 Milestone은 완료 대상이 아니라 폐기한다.
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: iop Edge 직접 연결 내용은 독립 Control Plane 분리 마이그레이션의 source map/evidence로만 보존한다.

## 범위 제외

- generic node agent 기능을 포함하지 않는다.
- 원격 파이프라인 실행 메시지 전체를 구현하지 않는다.
- 운영용 인증서 관리 시스템을 구현하지 않는다.
- MVP에서 checksum/signature, Edge fingerprint, credential rotation 강제 구현을 포함하지 않는다.

## 작업 컨텍스트

- 관련 경로: `lib/oto/**`, `test/oto_agent_*`, `assets/script/shell/oto_agent_bootstrap.sh`
- 선행 Edge bootstrap 계약은 완료 상태로 아카이브되었으며, 일반 작업에서는 활성 Phase의 archive 링크와 아래 표준선을 기준으로 한다.
- 선행 계약의 상세 문서는 과거 기록 확인이나 복원이 명시된 경우에만 읽는다.
- 표준선(선택): Linux MVP는 OTO가 없는 대상 머신에서 bootstrap script로 release asset을 다운로드한 뒤 `~/.oto/agent/config.yaml`을 생성하고 백그라운드로 실행한다.
- 표준선(선택): online 판정은 Edge 등록 완료와 최초 heartbeat 도착을 모두 만족했을 때로 둔다.
- 표준선(선택): bootstrap agent 식별 값 또는 token은 보안 완성보다 등록 대상 식별과 최초 연결 매칭을 위한 최소 계약으로 먼저 둔다.
- 표준선(선택): 바이너리 무결성은 후속 강화 항목으로 두고, MVP에서는 release asset 다운로드 기준과 실패 처리만 먼저 정리한다.
- 구현 근거: `AgentConfig`는 `~/.oto/agent/config.yaml` 형태의 `agent.id`, `agent.alias`, `agent.enrollment_token`, `edge.url`, runtime 경로를 파싱한다.
- 구현 근거: `CommandAgent`는 `oto agent run --config <path>`를 통해 설정 파일을 읽고 `AgentRunner`로 등록을 시작한다.
- 구현 근거: `EdgeRegistrationClient`는 `proto_socket`으로 Edge endpoint에 연결해 enrollment token을 `RegisterRequest`로 전송하고 `RegisterResponse`를 accepted/rejected 결과로 변환한다.
- 구현 근거: registration/config/CLI 검증은 `test/oto_agent_config_test.dart`, `test/oto_agent_registration_test.dart`, `test/oto_agent_cli_test.dart`, `test/oto_iop_connection_smoke_test.dart`에 있다.
- MVP 재시작 기준: bootstrap으로 시작한 background 프로세스의 pid/log를 기준으로 사용자가 상태를 확인하고 `oto agent run --config <path>`를 재실행한다. 자동 재시작과 systemd user service는 후속 강화로 둔다.
- 남은 작업: Edge 등록 완료 이후 최초 heartbeat 도착까지의 online 판정과 재시도 정책은 iop2oto의 online smoke PASS evidence와 맞춰 OTO `registration-state`에 정리한다.
- 선행 OTO Milestone: OTO-iop proto-socket 통신 기반
- 선행 iop2oto Milestone: OTO Agent Registry 구현 → OTO Bootstrap Command 발급 → OTO Registration Online Smoke → OTO Registration Unlock Handoff
- iop2oto 잠금 해제 근거(2026-06-04): `OTO Agent Registry 구현`과 `OTO Bootstrap Command 발급`은 workspace lock에서 `enable`로 확인되었다. `OTO Registration Online Smoke`는 `agent-task/archive/2026/06/m-oto-registration-online-smoke/03+01,02_smoke_evidence/complete.log` 기준 `make test-oto-registration-online-smoke` PASS, `registration accepted`, `node.online`, `reason=first_heartbeat` evidence가 확인되었다.
- 외부 의존 잠금: `/config/workspace/.agent-roadmap-sync/locks.yaml`의 `oto:oto-agent-registration` entry에서 모든 `rely-on.status`가 `enable`로 동기화되어 이 Milestone의 구현 잠금은 해제되었다.
- 책임 경계: iop2oto는 Edge outbound enrollment를 받아들이는 registry/protocol/credential 기준을 정리한다.
- 책임 경계: OTO는 설치된 `oto-agent`가 해당 기준을 소비해 설정을 만들고 Edge에 직접 outbound 연결하는 상태 전이를 정리한다.
- 네트워크, 설치, packaging 관련 코드나 문서가 추가될 경우 관련 도메인 rule을 먼저 확인한다.
- 구현 계획: `agent-task/m-oto-agent-registration/` 하위 plan-code-review 루프로 진행한다.
- 확인 필요: Edge 등록 완료 이후 최초 heartbeat 도착까지의 online 판정과 재시도 정책을 OTO `registration-state`에 반영한다.
- 폐기 사유: OTO는 iop Edge에 직접 연결되는 domain agent가 아니라 `services/core` OTO Server와 `apps/runner` OTO runner 간 계약으로 재구성한다. 이 문서의 registration/heartbeat/bootstrap 근거는 `agent-roadmap/phase/independent-control-plane/milestones/control-plane-separation-migration.md`의 migration source로만 사용한다.
