<!-- task=m-runner-proto-socket-transport-hardening/05+02,03,04_socket_smoke plan=0 tag=API -->

# Plan - API

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것까지가 구현입니다. 검증을 실행하고 실제 stdout/stderr를 붙인 뒤 active 파일을 그대로 두고 review ready로 보고하세요. 선택된 SDD 결정 또는 Milestone `구현 잠금 > 결정 필요` 항목이 막으면 review stub의 `사용자 리뷰 요청` 섹션을 채우고 멈추며, 직접 사용자에게 질문하거나 `USER_REVIEW.md`, `complete.log`, archive를 만들지 않습니다. 환경/secret/서비스 문제나 증거 공백은 일반 follow-up 대상으로 기록합니다.

## 배경

Milestone의 마지막 socket-transport task는 local/remote smoke evidence를 socket-centered 기준으로 고정하는 것이다. 앞선 lifecycle, dispatch/state, runner-actions, compatibility-boundary 결과를 받아 `agent-test/local/agent-smoke.md`, Makefile/test grouping, runner smoke가 HTTP registration/polling을 기본 evidence처럼 쓰지 않도록 정리한다.

## 사용자 리뷰 요청 흐름

사용자 리뷰 요청은 선택된 SDD 결정 또는 선택된 Milestone lock 결정이 실구현을 차단할 때만 active `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 기록한다. 구현 중 직접 사용자 프롬프트, 채팅 선택지, `request_user_input`, `USER_REVIEW.md` 생성은 금지이며, code-review가 검증과 파일 생성을 소유한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/control-plane-product-surface/milestones/runner-proto-socket-transport-hardening.md`
- Task ids:
  - `socket-smoke`: local/remote smoke 기준을 socket-first runner transport evidence로 갱신한다.
- Completion mode: check-on-pass
- Split dependency:
  - `02+01_dispatch_state` PASS complete evidence가 있어야 구현을 시작한다.
  - `03+01,02_runner_actions` PASS complete evidence가 있어야 구현을 시작한다.
  - `04+01_compat_boundary` PASS complete evidence가 있어야 구현을 시작한다.

## Spec Targets

- SDD: `agent-roadmap/sdd/control-plane-product-surface/runner-proto-socket-transport-hardening/SDD.md`
- Acceptance scenarios:
  - `S06`: task=`socket-smoke`; evidence=`agent local smoke와 runner/core smoke가 socket-first lifecycle, dispatch, action, compatibility boundary를 검증한다.`
- Completion mode: spec-check-on-pass

## 분석 결과

### 읽은 파일

- `agent-test/local/rules.md`
- `agent-test/local/agent-smoke.md`
- `agent-test/local/framework-smoke.md`
- `agent-ops/rules/project/domain/agent/rules.md`
- `agent-ops/rules/project/domain/framework/rules.md`
- `agent-roadmap/phase/control-plane-product-surface/milestones/runner-proto-socket-transport-hardening.md`
- `agent-roadmap/sdd/control-plane-product-surface/runner-proto-socket-transport-hardening/SDD.md`
- `Makefile`
- `apps/runner/test/oto_agent_registration_test.dart`
- `apps/runner/test/oto_server_connection_smoke_test.dart`
- `apps/runner/lib/oto/agent/agent_runner.dart`
- `apps/runner/lib/oto/agent/registration_client.dart`
- `services/core/internal/runnersocket/server.go`
- `services/core/internal/httpserver/server_test.go`

### 테스트 환경 규칙

`test_env=local`을 적용했다. `agent-test/local/agent-smoke.md`의 agent 필수 명령, Makefile의 runner test list, Go core full test를 모두 socket-centered evidence로 맞춘다. 이 작업은 앞선 split 결과를 종합하므로 targeted tests만 통과해도 안 되고 smoke 문서 기준과 실제 명령이 함께 맞아야 한다.

### 테스트 커버리지 공백

- `oto_server_connection_smoke_test.dart`의 첫 smoke는 HTTP registration client를 쓰고 있어 socket-first smoke의 대표 evidence로 부적합하다.
- `_startCore`는 socket listener env를 준비하지만 pass criteria가 socket lifecycle/dispatch/action을 명확히 요구하지 않는다.
- `agent-test/local/agent-smoke.md`는 runner transport hardening 전용 pass/fail criteria가 부족하다.

### 심볼 참조

`oto_server_connection_smoke_test.dart`, `_startCore`, `OtoServerSocketRegistrationClient`, `OtoServerPushJobSession`, `Makefile`의 `test-runner`, `agent-test/local/agent-smoke.md`의 runner 명령을 중심으로 확인했다.

### 분할 판단

이 작업은 최종 smoke 정리이므로 `dispatch-state`, `runner-actions`, `compat-boundary` 결과를 모두 기다린다. 선행 task가 완료되지 않았으면 smoke 기준을 고정하지 않는다.

### 범위 결정 근거

이 plan은 smoke 문서/테스트 기준을 정리하고 필요한 작은 test grouping을 보강한다. lifecycle/state/action 자체 구현은 선행 split task에서 끝난 상태를 전제로 한다.

### 빌드 등급

`cloud-G07`: smoke 기준이 이후 agent 작업의 완료 판정을 좌우한다. 문서와 실제 명령이 어긋나면 Milestone 전체가 잘못 완료될 수 있어 전체 local smoke 명령을 요구한다.

## 구현 체크리스트

- [ ] 선행 `02+01_dispatch_state`, `03+01,02_runner_actions`, `04+01_compat_boundary` PASS complete evidence를 확인한다.
- [ ] [API-1] `agent-test/local/agent-smoke.md`와 Makefile/test grouping을 socket-first 기준으로 갱신한다. 검증: `cd apps/runner && dart analyze`
- [ ] [API-2] runner socket smoke가 lifecycle/dispatch/action/compat boundary evidence를 대표하도록 보강한다. 검증: `cd apps/runner && dart test test/oto_server_connection_smoke_test.dart`
- [ ] [API-3] full local smoke 명령을 실행하고 결과를 기록한다. 검증: Go full test와 runner required test list
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] smoke 문서와 Makefile/test grouping 갱신

문제: [agent-smoke.md](/config/workspace/oto/agent-test/local/agent-smoke.md:50)의 agent smoke 기준과 [Makefile](/config/workspace/oto/Makefile:7)의 runner test list가 socket-transport hardening의 pass criteria를 충분히 드러내지 않는다.

해결 방법:

`agent-test/local/agent-smoke.md`에 runner transport hardening 기준을 추가하거나 기존 agent smoke 명령 설명을 조정한다. Makefile test list가 이미 필요한 runner tests를 포함하면 변경하지 않고 evidence만 명시한다. 문서 변경은 사람이 실행할 수 있는 실제 명령과 일치해야 한다.

수정 파일 및 체크리스트:

- [ ] agent smoke 문서에 socket-first lifecycle/dispatch/action/compatibility evidence 기준 추가
- [ ] Makefile runner test list가 smoke 문서와 어긋나지 않는지 확인
- [ ] 불필요한 test command duplication은 피함

중간 검증:

```bash
cd apps/runner && dart analyze
```

기대 결과: analyzer issue 없음.

### [API-2] runner socket smoke 대표성 보강

문제: [oto_server_connection_smoke_test.dart](/config/workspace/oto/apps/runner/test/oto_server_connection_smoke_test.dart:1)는 server connection smoke를 포함하지만 HTTP registration/polling evidence와 socket evidence가 섞여 있다. Milestone 완료 evidence로는 socket-first scenario가 명확해야 한다.

해결 방법:

socket registration, server-assigned runner id, pushed `RunRequest`, report result, cancel/action or explicit excluded compatibility evidence가 한눈에 보이도록 smoke test names/groups를 정리한다. `_startCore`의 socket listener env를 계속 사용한다.

수정 파일 및 체크리스트:

- [ ] socket smoke group을 대표 evidence로 배치
- [ ] HTTP compatibility smoke는 fallback group으로 분리
- [ ] lifecycle/dispatch/action 선행 tests를 중복하지 않고 smoke-level assertion만 유지

중간 검증:

```bash
cd apps/runner && dart test test/oto_server_connection_smoke_test.dart
```

기대 결과: smoke test 통과.

### [API-3] full local smoke 기록

문제: Milestone 완료는 단일 Dart smoke만으로 충분하지 않다. core socket server/state tests와 runner required tests가 함께 통과해야 한다.

해결 방법:

최종 검증에서 core Go 전체, Dart analyzer, agent-smoke에 명시된 runner tests를 실행하고 CODE_REVIEW에 stdout/stderr를 붙인다.

중간 검증:

```bash
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
```

기대 결과: 모든 명령 통과.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `agent-test/local/agent-smoke.md` | API-1 |
| `Makefile` | API-1 |
| `apps/runner/test/oto_server_connection_smoke_test.dart` | API-2 |
| `apps/runner/test/oto_agent_registration_test.dart` | API-2 |
| `agent-roadmap/sdd/control-plane-product-surface/runner-proto-socket-transport-hardening/SDD.md` | API-1, API-3 |

## 최종 검증

```bash
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
```

기대 결과: core Go full test 통과, Dart analyzer 통과, agent required tests 통과. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
