# Milestone: Runner bootstrap, OTO binary, 노드 연결

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/control-plane-product-surface/PHASE.md`

## 목표

OTO Core가 발급하는 bootstrap 흐름을 Linux 단일 shell script 기준에서 확장해 Linux, macOS, Windows 대상 `oto` binary 설치와 runner/node 연결을 지원한다.
완료 후 대상 머신은 OTO가 미리 설치되어 있지 않아도 OS별 bootstrap command로 release asset을 내려받고, agent 설정을 만들고, `oto agent run`으로 OTO Core에 runner/node로 등록 또는 연결할 준비까지 진행할 수 있어야 한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

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

## 범위

- OTO Core bootstrap command/API와 embedded bootstrap asset 제공 경로를 OS별로 확장한다.
- Linux와 macOS는 POSIX shell 기반 설치 흐름을 우선 재사용하고, Windows는 PowerShell 기반 설치 흐름을 둔다.
- release asset 이름, OS/arch 감지, `oto` binary 설치 경로, config 경로, log/workspace 경로를 OS별 표준선으로 정리한다.
- 설치된 `oto` binary가 생성된 agent 설정을 사용해 OTO Core runner registry에 runner/node로 연결되는 최소 계약을 고정한다.
- bootstrap script와 server handler 테스트를 OS별 케이스로 확장한다.

## 기능

### Epic: [bootstrap-platforms] Cross-OS bootstrap contract

OS별 bootstrap command와 release asset 선택 기준을 OTO Core와 runner asset이 같은 의미로 해석하도록 만든다.

- [x] [platform-matrix] Linux, macOS, Windows의 우선 지원 OS/arch와 release asset naming 규칙을 정리한다. 검증: 문서와 테스트 fixture가 동일한 asset 이름을 사용한다.
- [x] [core-command] OTO Core bootstrap command 요청/응답이 대상 OS 또는 script 종류를 표현하고 올바른 bootstrap URL/command를 반환한다. 검증: `cd services/core && go test ./...`가 OS별 command 케이스를 포함해 통과한다.
- [x] [unix-bootstrap] Linux/macOS shell bootstrap이 OS/arch를 감지해 올바른 release asset을 내려받고 config/runtime 경로를 생성한다. 검증: `cd apps/runner && dart test test/oto_agent_bootstrap_script_test.dart` 또는 대응 smoke가 통과한다.
- [x] [windows-bootstrap] Windows PowerShell bootstrap이 release asset 다운로드, 압축 해제, config 생성, agent 실행 안내 또는 시작 흐름을 제공한다. 검증: script parsing/fixture 테스트가 Windows 경로와 quoting을 검증한다.
- [x] [oto-binary] bootstrap으로 설치된 `oto` binary의 실행 경로와 버전 확인 방법을 OS별로 고정한다. 검증: fixture 또는 smoke가 설치 후 `oto --version` 또는 동등한 binary 확인 절차를 검증한다.
- [x] [node-connect] bootstrap으로 생성된 agent 설정이 `oto agent run`에서 OTO Core runner registry에 runner/node로 등록 또는 연결되는 최소 흐름을 보장한다. 검증: `cd services/core && go test ./...`와 runner agent 연결 smoke 또는 fixture 테스트가 통과한다.
- [x] [docs-smoke] README와 `agent-test/local/agent-smoke.md`가 OS별 bootstrap command, secret 기록 금지, release URL 검증 기준을 최신화한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-16
- 완료 근거:
  - 원격 runner `/Users/toki/agent-work/oto`에서 `cd services/core && go test -count=1 ./...` 통과로 OS별 bootstrap command, embedded bootstrap asset serving, runner registry/httpserver 회귀를 확인했다.
  - 원격 runner `/Users/toki/agent-work/oto`에서 `cd apps/runner && dart test test/oto_agent_migration_plan_test.dart test/oto_agent_bootstrap_script_test.dart test/oto_agent_cli_test.dart test/oto_agent_config_test.dart test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart` 통과로 Unix bootstrap, binary verification, generated agent config, OTO Server runner 연결 smoke를 확인했다.
  - 원격 runner `/Users/toki/agent-work/oto`에서 `cd apps/runner && dart pub get && dart analyze` 통과로 runner 정적 분석 회귀를 확인했다.
  - 코드 레벨 종료 검토 중 bootstrap config YAML 값이 따옴표/백슬래시를 포함할 때 깨질 수 있는 작은 이슈를 확인했고, shell bootstrap은 double-quoted YAML escaping, PowerShell bootstrap은 single-quoted YAML escaping으로 보강했다.
  - 로컬 checkout에서 `git diff --check`, `cd services/core && go test -count=1 ./...`, `cd apps/runner && dart analyze`, `cd apps/runner && dart test test/oto_agent_migration_plan_test.dart test/oto_agent_bootstrap_script_test.dart test/oto_agent_cli_test.dart test/oto_agent_config_test.dart test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart test/oto_agent_bootstrap_ps1_test.dart`가 통과했다.
  - 원격 runner 임시 tree `/tmp/oto-verify-bootstrap.j89dYx`에서 로컬 HEAD와 이번 변경 파일을 기준으로 `cd services/core && go test -count=1 ./...`, `cd apps/runner && dart pub get && dart analyze && dart test test/oto_agent_migration_plan_test.dart test/oto_agent_bootstrap_script_test.dart test/oto_agent_cli_test.dart test/oto_agent_config_test.dart test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart test/oto_agent_bootstrap_ps1_test.dart`가 통과했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 코드 레벨 종료 검토에서 확인된 작은 YAML escaping 이슈를 처리했고, 원격 runner 기준 재검증이 통과해 `bootstrap-platforms` Epic과 Milestone을 완료 처리한다.

## 범위 제외

- checksum/signature 검증, certificate pinning, enrollment token rotation은 기본 구현을 막지 않는 후속 보안 강화로 둔다.
- OS별 system service 설치를 완성형 daemon 관리까지 확대하지 않는다. 필요하면 user-level background 실행 또는 수동 실행 안내를 먼저 둔다.
- private release host, credential, token 원문을 tracked 문서에 기록하지 않는다.

## 작업 컨텍스트

- 관련 경로: `services/core/internal/httpserver/**`, `services/core/internal/runnerregistry/**`, `apps/runner/lib/oto/agent/**`, `apps/runner/assets/script/**`, `apps/runner/test/**`, `README.md`, `agent-test/local/**`
- 표준선(선택): 우선 지원 OS는 Linux, macOS, Windows로 보고, 각 OS의 x64/arm64 지원 여부는 release asset 존재와 테스트 fixture로 명시한다.
- 표준선(선택): Linux/macOS는 shell, Windows는 PowerShell을 사용하며, 공통 설정 의미는 `agent.id`, `agent.alias`, `agent.enrollment_token`, `server.url`, `runtime.install_dir`, `runtime.workspace_root`, `runtime.log_dir`를 유지한다.
- 선행 작업: `독립 Control Plane 분리 마이그레이션`의 bootstrap command, `워크스페이스 포트/환경 표준화`의 release URL 기준, 폐기된 `Edge bootstrap 계약`의 Linux 설치 근거
- 후속 작업: Flutter 콘솔 스켈레톤, release packaging 자동화, checksum/signature 검증, OS별 service manager 통합
- 확인 필요: 없음
