oto/agent-task/m-runner-proto-socket-transport-hardening/05+02,03,04_socket_smoke/PLAN-cloud-G07.md

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의 agent smoke 기준과 Makefile의 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은 피함

중간 검증:

cd apps/runner && dart analyze

기대 결과: analyzer issue 없음.

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

문제: oto_server_connection_smoke_test.dart는 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만 유지

중간 검증:

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를 붙인다.

중간 검증:

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

최종 검증

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의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.