<!-- task=m-iop-hot-path-one-shot-execution/16+14,15_terminal_disposition plan=1 tag=API milestone-task=error-cancel -->

# Hot Path common terminal disposition

## For the Implementing Agent

구현 후 `CODE_REVIEW-cloud-G10.md`의 구현 담당 섹션과 실제 출력을 채우고 active 파일을 유지한다. 차단 시 blocker/명령/출력/재개 조건만 기록하며 사용자 질문, archive, `complete.log` 작성은 금지한다.

## Background

Outer stream은 cleanup primary-error precedence와 endpoint codec을 함께 사용하지만 terminal/cancel/length outcome을 결정하는 공통 ownership과 active-stage cancellation이 아직 닫히지 않았다. 이 child는 wire mapping과 분리된 typed disposition과 exactly-once arbiter를 만든다.

## Analysis

### Files Read

- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-hot-path-one-shot-execution/SDD.md`
- `apps/edge/internal/openai/hot_path_cleanup.go`
- `apps/edge/internal/openai/hot_path_terminal_control.go`
- `apps/edge/internal/openai/hot_path_dispatch.go`
- `apps/edge/internal/openai/hot_path_light.go`
- `apps/edge/internal/openai/hot_path_cleanup_test.go`
- `apps/edge/internal/openai/cancellation_routes_test.go`
- `agent-test/local/rules.md`

### SDD Criteria

- 승인 SDD, `milestone-task=error-cancel`, S13.
- primary error 보존, cleanup best effort, abort 후 no hidden call, output-cap length disposition, exactly-one terminal owner가 이 child의 oracle이다.

### Verification Context

- fault fixtures와 fresh race tests로 닫으며 외부 runtime은 필요하지 않다.

### Test Coverage Gaps

- exact active stage cancel handle, concurrent cancel/complete winner, post-terminal dispatch suppression을 함께 검증하는 common fixture가 없다.

### Symbol References

- public rename/remove 없음. internal disposition과 arbiter만 추가한다.

### Split Judgment

- stable contract: failure/cancel/output-cap source → common typed disposition and terminal ownership.
- endpoint pre/post-commit wire matrix는 child 17로 분리한다.
- endpoint codec predecessors 14/15가 모두 필요하다.

### Scope Rationale

- endpoint-specific bytes/status table, observability, smoke는 제외한다.

### Final Routing

- evaluation_mode=isolated-reassessment, finalizer=`finalize-task-policy.sh pair`.
- build closures 모두 true, scores=2/2/2/1/2, G09, grade-boundary → `PLAN-cloud-G09.md`.
- review closures 모두 true, scores=2/2/2/2/2, G10, official-review → `CODE_REVIEW-cloud-G10.md`.
- risks=`temporal_state,concurrent_consistency,boundary_contract,variant_product`(4), `large_indivisible_context=false`, recovery=0/false, capability gap 없음.

## Implementation Checklist

- [ ] [API-1] Centralize typed Hot Path terminal disposition and exactly-once ownership so current work is canceled precisely and no hidden stage runs after terminal.
- [ ] [API-2] Add common disposition, cleanup precedence, and concurrent cancel/complete regressions and run the child verification commands.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-1] Typed disposition and terminal arbiter

**Problem:** cleanup returns terminal intent while handler errors and progressive streams can independently race to finish or cancel.

**Solution:** Introduce internal dispositions `success`, `tool_turn`, `length`, `provider_error`, `validation_error`, `timeout`, and `caller_cancel`. Propagate the exact active dispatch/cancel handle from `submitHotPathStage`; atomically select one terminal owner, cancel only active dispatched work, preserve primary error through cleanup, reject post-terminal events, and stop later review/repair/cleanup dispatch after ownership is lost.

**Modified Files and Checklist:**

- [ ] Modify `apps/edge/internal/openai/hot_path_cleanup.go` to produce typed dispositions and preserve primary-error/cleanup ordering.
- [ ] Modify `apps/edge/internal/openai/hot_path_terminal_control.go` to arbitrate terminal ownership and current-stage cancellation.
- [ ] Modify `apps/edge/internal/openai/hot_path_dispatch.go` and `apps/edge/internal/openai/hot_path_light.go` to retain exact active handles and stop hidden follow-up work.

**Test Strategy:** API-2 covers disposition and race behavior independent of endpoint wire bytes.

**Verification:** `go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(CancelCompleteRace|Cleanup|TerminalDisposition)'` exits 0.

### [API-2] Common terminal evidence

**Problem:** existing cleanup tests do not prove the common terminal winner and cancellation cardinality.

**Solution:** Use barrier-controlled cancellation/completion and failure-source rows. Assert primary error precedence, one `CancelRun` when warranted, no post-terminal emission or follow-up stage, cleanup best effort, and native length disposition without wire-specific assertions.

**Modified Files and Checklist:**

- [ ] Add `apps/edge/internal/openai/hot_path_error_cancel_test.go` with `TestHotPathTerminalDisposition` and `TestHotPathCancelCompleteRace`.
- [ ] Fill `agent-task/m-iop-hot-path-one-shot-execution/16+14,15_terminal_disposition/CODE_REVIEW-cloud-G10.md`.

**Test Strategy:** new race rows plus existing cleanup/cancellation regressions are mandatory.

**Verification:** run Final Verification; all commands exit 0 and race detector passes.

## Dependencies and Execution Order

1. `14+13_anthropic_gate` must produce its active `complete.log`.
2. `15+13_chat_gate` must produce its active `complete.log`.
3. Implement API-1, then API-2.

## Modified Files Summary

| File | Item |
|---|---|
| `apps/edge/internal/openai/hot_path_cleanup.go` | API-1 |
| `apps/edge/internal/openai/hot_path_terminal_control.go` | API-1 |
| `apps/edge/internal/openai/hot_path_dispatch.go` | API-1 |
| `apps/edge/internal/openai/hot_path_light.go` | API-1 |
| `apps/edge/internal/openai/hot_path_error_cancel_test.go` | API-2 |
| `agent-task/m-iop-hot-path-one-shot-execution/16+14,15_terminal_disposition/CODE_REVIEW-cloud-G10.md` | API-2 |

## Final Verification

```bash
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(CancelCompleteRace|Cleanup|TerminalDisposition)'
go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service
git diff --check
```

Expected: exit 0, exactly one terminal owner, precise active-work cancellation, no hidden follow-up, no race, empty diff check. Cached output is not acceptable.

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
