<!-- task=m-iop-hot-path-one-shot-execution/13+12_outer_turn_integration plan=2 tag=REVIEW_API milestone-task=terminal-control -->

# Code Review Reference - REVIEW_API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields.
> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state.
> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.

## Overview

date=2026-08-03
task=m-iop-hot-path-one-shot-execution/13+12_outer_turn_integration, plan=2, tag=REVIEW_API

## Archive Evidence Snapshot

- `code_review_cloud_G09_1.log` records the first review verdict: FAIL with two Required findings covering the non-authoritative cap/compatibility path and missing handler-level evidence.
- `plan_cloud_G08_1.log` is the superseded integration plan. This follow-up is limited to the unclosed findings recorded in the review log.

## For the Review Agent

> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section.

Compare implementation of each item against source files and verify that output in `Verification Results` matches code.
Review completion means the following steps are finished:

1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals.
2. Archive `CODE_REVIEW-cloud-G09.md` → `code_review_cloud_G09_2.log` and `PLAN-cloud-G09.md` → `plan_cloud_G09_2.log`.
3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-hot-path-one-shot-execution/13+12_outer_turn_integration/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
4. If PASS, preserve `milestone-task=terminal-control` in `complete.log` and report it for the runtime aggregation event. Roadmap state evaluation belongs to `sync-milestone-workstate`.
5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting.

---

## Implementation Item Completion

| Item | Status |
|------|---------|
| REVIEW_API-1 Authoritative cap, response, and terminal flow | [x] |
| REVIEW_API-2 Handler-level transition and compatibility evidence | [x] |

## Implementation Checklist

- [x] [REVIEW_API-1] Make the caller cap and outer accumulator authoritative for dispatch, frontier registration, compatibility rendering, and terminal cleanup.
- [x] [REVIEW_API-2] Add real Chat/Messages handler evidence for every required transition and compatibility row with exact dispatch counts.
- [x] Fill all implementation-owned sections in `CODE_REVIEW-cloud-G09.md` with actual changes and fresh command output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent.
> Implementing agents must not modify or check this section.

- [x] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`.
- [x] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match.
- [x] Archive active `CODE_REVIEW-cloud-G09.md` to `code_review_cloud_G09_2.log`.
- [x] Archive active `PLAN-cloud-G09.md` to `plan_cloud_G09_2.log`.
- [x] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`.
- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files.
- [ ] If PASS, move active task directory `agent-task/m-iop-hot-path-one-shot-execution/13+12_outer_turn_integration/` to `agent-task/archive/YYYY/MM/m-iop-hot-path-one-shot-execution/13+12_outer_turn_integration/` and update this checklist at the final archive path.
- [ ] If PASS, preserve and report `milestone-task=terminal-control` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`.
- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-hot-path-one-shot-execution/` or verify it was kept due to remaining siblings/files.
- [x] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`.

## Deviations from Plan

- The planned verification commands were executed without changes.
- `hot_path_cleanup.go` and `hot_path_cleanup_test.go` were updated in addition to the primary implementation files because a cleanup frontier must be built from the authoritative outer accumulator before lineage hashing and registration. Projecting the accumulated response only after registration produced a different lineage from the caller-visible response.

## Key Design Decisions

- Parse the endpoint caller cap once at handler ingress, remove spoofed cap metadata, and carry the validated value through preset dispatch metadata into a request-local outer turn.
- Keep provider output-token accounting separate from the conservative public rune ceiling, and reserve the same remaining token budget in normalized runs and Chat/Messages tunnel bodies. A limited zero budget terminates before another provider acquisition or submission.
- Accumulate content, reasoning, tools, usage, and terminal intent once. Assign public tool IDs before frontier hashing while retaining provider IDs for coordinator correlation, then render direct, artifact, light, review, cleanup, cap, and error responses from the same compatibility projection.
- Preserve provider response identity and unknown usage fields while aggregating endpoint-native usage and translating terminal reasons at the OpenAI and Anthropic boundaries.
- Exercise real Chat and Messages handlers with scripted provider services so transition tests assert exact per-request and total submission counts, including zero post-terminal work.

## Reviewer Checkpoints

- Confirm the initial selector result is fed into the request-local outer turn exactly once and is never redispatched.
- Confirm caller cap metadata constructs the outer turn, normalized and tunnel requests receive the same non-overridable remaining value, and exhaustion prevents acquisition or submission of another local/review stage.
- Confirm direct, ordinary-tool, artifact, light, error, cap, and cancellation branches commit before writing and use one compatibility output for frontier IDs and caller-visible content/reasoning/tools, aggregate usage, and endpoint-native terminal reason.
- Confirm real `TestHotPathOuterTurnIntegration` and `TestHotPathOuterTurnCompatibility` handler tests cover Chat and Messages with exact per-request provider submission counts, including local-review and repair transitions and no post-terminal work.
- Confirm existing direct/light/cleanup behavior, artifact correlation, and race safety remain intact.

## Verification Results

### Targeted outer-turn handlers

Command: `go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(OuterTurnIntegration|OuterTurnCompatibility|Direct|Light|Cleanup)'`

Exit status: 0

```text
ok  	iop/apps/edge/internal/openai	4.449s
```

### Package race regression

Command: `go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service`

Exit status: 0

```text
ok  	iop/packages/go/streamgate	2.292s
ok  	iop/packages/go/config	2.306s
ok  	iop/apps/edge/internal/openai	12.988s
ok  	iop/apps/edge/internal/service	7.739s
```

### Edge vet

Command: `go vet ./apps/edge/...`

Exit status: 0

```text
(no output)
```

### Diff

Command: `git diff --check`

Exit status: 0

```text
(no output)
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) |
| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required |
| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only |
| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section |
| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content |
| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan |
| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry |
| Code Review Result | Review agent appends | Not included in stub |

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Fail
  - Completeness: Fail
  - Test coverage: Fail
  - API contract: Fail
  - Code quality: Pass
  - Implementation deviation: Fail
  - Verification trust: Pass
  - Spec conformance: Fail
- Findings:
  - Required — `apps/edge/internal/openai/hot_path_direct.go:46` and `apps/edge/internal/openai/hot_path_light.go:812`: cap exhaustion is resolved before the emitted terminal/tool shape. A focused real-handler reproducer used `max_tokens=4` with a small `read_file` tool call and provider-reported output usage of 4; both OpenAI and Anthropic responses published the remapped public tool id, then `terminalPresetRequest` removed the logical request (`logical request count=0`), so the caller-visible tool had no continuation frontier. The no-usage fallback at `apps/edge/internal/openai/hot_path_terminal_control.go:439` is also not conservative across Unicode/provider tokenizers because it assumes four runes per token and can admit a later internal stage after the caller budget is already consumed. Resolve terminal/tool ownership before destructive cap cleanup, never publish a tool without a live expected-result frontier, and replace the optimistic no-usage estimate with a conservative model-independent bound or exact route tokenizer accounting. Add OpenAI and Anthropic handler regressions for cap-at-tool-terminal continuity plus a usage-less multistage Unicode cap row.
- Routing Signals: `review_rework_count=2`, `evidence_integrity_failure=false`
- Next Step: Prepare and materialize a freshly routed follow-up PLAN/CODE_REVIEW pair for the cap-terminal ownership and no-usage budget findings; do not write `complete.log`.
