# Milestone: IOP Agent Run Bridge

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/agent-shell-iop-execution/PHASE.md`

## 목표

`../iop` backend/runtime이 수행한 agent run을 Gito의 workspace operation과 Git revision event로 수렴시키는 계약을 만든다. `../agent-shell`은 host UI/package로 남고, 실제 backend 실행과 IOP CLI/Edge/Node orchestration은 IOP 프로젝트가 소유한다. Gito와 IOP의 외부 연결은 HTTP dispatch/callback 경계로 두며, proto-socket은 사용하지 않는다. 성공 기준은 구조화 응답이 아니라 workspace의 실제 Git 상태와 push 결과로 확인한다.

## 상태

[계획]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 확인 필요 - production worker/runtime 연결 보완에서 durable agent_run input source 또는 외부 IOP adapter 계약이 기존 contract note 범위를 넘으면 SDD gate를 먼저 재확인한다.
- 결정 필요: 없음
- 해소 근거:
  - IOP CLI 실행 명령, profile/model 선택, 입력 파일 또는 stdin 계약은 Gito가 직접 확정하지 않고 IOP backend/runtime 소유로 둔다.
  - IOP credential과 workspace별 secret 주입 방식은 raw secret이 아니라 `credential_ref`/`secret_ref` 경계로만 연결하며, 세부 주입은 IOP 소유 또는 후속 provider/credential Milestone에서 다룬다.
  - Gito와 IOP의 외부 연결은 HTTP dispatch/callback 모델을 따른다. proto-socket은 외부 연결 규약이나 보조 transport로 사용하지 않는다.

## 범위

- IOP backend invocation/result contract
- IOP HTTP dispatch/callback boundary
- workspace path, repo context, operation instruction 전달 경계
- agent run state model
- IOP run success/failure 판정
- run 이후 Git status/diff/commit/push와 revision scan 연결

## 기능

### Epic: [iop-run] IOP execution

IOP backend를 workspace operation 실행 통로로 연결한다.

- [x] [input] repo, branch, workspace path, user instruction, policy context를 IOP 입력으로 전달하는 형식을 정한다.
- [x] [invoke] Gito가 직접 IOP CLI를 실행하지 않고 IOP backend invocation/result 계약을 호출하거나 수신하는 형식을 정한다. 검증: fake IOP backend result가 operation log를 남긴다.
- [ ] [production-worker] production worker가 durable agent_run input source에서 실행 입력을 로드하고, agent_run만 안전하게 pick해 IOP adapter/result path를 실제 runtime 의존성으로 연결한다. 검증: `cd services/core && go test -count=1 ./internal/worker ./internal/storage` 및 `cd services/core && go test ./...`
- [x] [state] `queued`, `running`, `succeeded`, `failed`, `cancelled` run state를 operation lifecycle에 매핑한다.
- [x] [result] run 이후 Git status와 revision diff로 성공 여부를 확인한다.

### Epic: [git-result] Git result convergence

agent run 결과를 Git revision과 operation event로 수렴한다.

- [x] [dirty-guard] run 종료 후 dirty workspace 정책을 적용한다.
- [x] [commit-push] policy가 허용한 경우 commit/push operation으로 연결한다.
- [x] [revision-event] push 이후 revision scan event를 발행한다.
- [ ] [revision-scan-seed] cursor 없는 agent_run push도 known before/after revision으로 `branch.updated` 이벤트를 emit/retry한다. 검증: `cd services/core && go test -count=1 ./internal/controlplane ./internal/worker`

## 완료 리뷰

- 상태: 보완 필요
- 요청일: 2026-06-16
- 보완 판정일: 2026-06-17
- 완료 근거: `revision-event`까지 PASS되어 모든 기능 Task가 충족됐다. 최종 근거는 `agent-task/archive/2026/06/m-iop-agent-run-bridge/04+03_revision_scan_event/complete.log`의 Roadmap Completion이며, 검증은 `cd services/core && go test ./...`, 계약 keyword scan, `git diff --check` PASS다.
- 코드 레벨 보완 필요:
  - production worker entrypoint가 picker/input loader/invoker를 nil로 구성해 실제 queued operation을 처리하지 못한다.
  - generic queued picker를 그대로 연결하면 비-agent operation이 running으로 전이된 뒤 runner가 no-op 처리할 수 있다.
  - agent_run revision scan이 known before/after revision을 전달하지 않아 cursor 없는 첫 push의 `branch.updated` 이벤트를 놓칠 수 있다.
- 리뷰 코멘트: 종료 전 `production-worker`, `revision-scan-seed` 후속 task를 완료해야 한다.

## 범위 제외

- IOP 내부 모델 라우팅
- IOP CLI 실행 명령, profile/model 선택, 입력 파일 또는 stdin 세부
- IOP credential과 workspace별 raw secret 주입 세부
- `../agent-shell` package 내부 UI/domain 구현
- provider PR/MR 생성
- Plane/Jira work item lifecycle
- Flutter UI

## 작업 컨텍스트

- 관련 경로: `services/core/internal/worker/`, `services/core/internal/gitengine/`, `services/core/internal/events/`, `packages/contracts/notes/gito-control-plane.md`
- 표준선(선택): IOP run 결과는 Git 상태와 operation event로 검증한다. Gito는 IOP CLI/secret 주입 세부를 직접 소유하지 않고 HTTP dispatch/callback과 `credential_ref`/`secret_ref` 경계만 다룬다.
- 선행 작업: Agent Shell Package and IOP Backend Boundary
- 후속 작업: Command Policy and Cancellation
- 확인 필요: NomadCode webhook 대응 후 production worker/runtime 연결 보완, 완료 리뷰, archive 승인
- 우선순위 조정: 2026-06-17 NomadCode webhook 요청 대응을 최우선 작업으로 올리면서 이 Milestone은 `[계획]`으로 되돌렸다.
- 방향성 정리: 외부 연결 규약에서 proto-socket을 제거하고 GitHub webhook과 유사한 HTTP webhook/callback 모델로 정렬했다.
- 완료 근거: `[input]`과 `[state]`는 `packages/contracts/notes/gito-control-plane.md`의 `IOP Agent Run Bridge` 섹션에서 transport-independent `AgentRunInput`과 run state mapping으로 정리했다. `[invoke]`는 `agent-task/archive/2026/06/m-iop-agent-run-bridge/01_iop_invocation_contract/complete.log`의 PASS Roadmap Completion으로 확인했다. `[result]`는 `agent-task/archive/2026/06/m-iop-agent-run-bridge/02+01_git_result_convergence/complete.log`의 PASS Roadmap Completion으로 확인했다. `[dirty-guard]`는 `services/core/internal/worker/runner.go`의 dirty workspace failure policy와 `TestRunnerRunOnceAgentRunFailsWhenGitEvidenceIsDirty` 통과로 확인했다. `[commit-push]`는 `agent-task/archive/2026/06/m-iop-agent-run-bridge/03_commit_push_policy/complete.log`의 PASS Roadmap Completion으로 확인했다. `[revision-event]`는 `agent-task/archive/2026/06/m-iop-agent-run-bridge/04+03_revision_scan_event/complete.log`의 PASS Roadmap Completion과 `TestRuntimeScanAgentRunRevisionPublishFailureDoesNotAdvanceDurableState`, `TestScanOperationEventAllowsNullOperationID`, `cd services/core && go test ./...` 통과로 확인했다.
