<!-- task=m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct plan=2 tag=REVIEW_API milestone-task=route-selector,direct-flow -->

# 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/07+02,04,06_route_selector_direct, plan=2, tag=REVIEW_API

## Archive Evidence Snapshot

- Prior plan: `agent-task/m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct/plan_cloud_G10_1.log`.
- Prior review: `agent-task/m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct/code_review_cloud_G10_1.log`.
- Verdict: FAIL with 3 Required, 0 Suggested, and 0 Nit findings.
- Required closure: activate direct-only presets without workspace tools; compare the complete mapped control path with the issued path; keep IOP run/frame correlation separate from provider response ID/timestamp.
- Affected files: hot-path activation/collection, structural path classification, and focused handler/classifier tests.
- Verification evidence: all planned focused, race, full Edge, vet, formatting, and diff commands passed, but reviewer probes left a direct-only request `active`, admitted `prefix/.iop/job/<request_id>/plan.md` as `light_exact_pair`, and emitted `run-pool-tunnel` as the public ID for a provider body with no ID.
- Roadmap carryover: `route-selector,direct-flow`; SDD S03 requires exact structural controls and S07 requires real direct completion with no reserved artifact path.

## 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-G08.md` → `code_review_cloud_G08_2.log` and `PLAN-cloud-G08.md` → `plan_cloud_G08_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/07+02,04,06_route_selector_direct/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
4. If PASS and task group is `m-<milestone-slug>`, preserve the first-line `milestone-task` metadata 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 Activate direct-only presets | [x] |
| REVIEW_API-2 Enforce exact issued control paths | [x] |
| REVIEW_API-3 Separate provider metadata from transport correlation | [x] |

## Implementation Checklist

- [x] Route valid direct-only presets without workspace tools through production structural selection and exactly-once direct terminal handling for Chat and Messages.
- [x] Require the complete normalized mapped control path to equal the exact issued job/plan/review path and reject substring, absolute, suffixed, and multi-source variants.
- [x] Preserve only provider-reported public response identity/timing on tunnel direct output, keep IOP run/frame metadata internal, and fail missing required provider identity through endpoint-standard errors.
- [ ] Add the focused regressions and run fresh focused, race, full Edge, vet, formatting, deterministic reference, and diff verification.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification 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-*-G??.md` to `code_review_cloud_G08_2.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G08_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/07+02,04,06_route_selector_direct/` to `agent-task/archive/YYYY/MM/m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct/` and update this checklist at the final archive path.
- [ ] If PASS and task group is `m-<milestone-slug>`, preserve and report `milestone-task` metadata 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 focused and focused-race commands pass. The final common-race and full-Edge commands are blocked by existing virtual-preset identity tests outside this plan's target files: those tests still assert raw provider-tunnel behavior for direct-only presets, while REVIEW_API-1 intentionally sends such presets through the direct terminal path. No out-of-scope test files were changed.

## Key Design Decisions

- Hot-path admission depends only on an admitted preset and its selector binding. Workspace alternatives remain relevant only when structural classification encounters a reserved control.
- A mapped control path is the cleaned complete mapped argument. Reserved-path scanning remains independent and treats extra reserved sources as malformed without double-counting `RawArgs` when it serializes the already-decoded arguments.
- Tunnel frame run IDs and timestamps remain transport correlation only. Tunnel-derived direct output requires a provider ID for both protocols before any direct response is committed; a missing provider creation time is preserved as absent rather than synthesized from a frame timestamp.

## Reviewer Checkpoints

- Direct-only presets without `workspace_tools` cross the same real Chat/Messages selector collection and direct runner as other direct presets.
- Every mapped canonical control path equals the complete issued path; substring extraction cannot authorize a different target.
- Provider tunnel body/SSE metadata, not IOP run IDs or frame timestamps, supplies public response identity/timing.
- Positive direct text/reasoning/tool cases preserve provider usage, virtual model identity, one tool frontier or terminal, and no `.iop/job/` output.

## Verification Results

Fill actual stdout/stderr for every command. Do not summarize reconstructed output. Any changed command requires a `Deviations from Plan` entry.

### REVIEW_API-1 direct-only handler verification

```bash
go test -count=1 ./apps/edge/internal/openai -run 'TestHotPathPresetHandlersDirect'
```

_Actual stdout/stderr:_

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

### REVIEW_API-2 exact selector-path verification

```bash
go test -count=1 ./apps/edge/internal/openai -run 'TestHotPathSelectorDecisionMatrix'
```

_Actual stdout/stderr:_

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

### REVIEW_API-3 provider metadata verification

```bash
go test -count=1 ./apps/edge/internal/openai -run 'TestHotPathPresetHandlersDirect'
```

_Actual stdout/stderr:_

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

### Final verification

```bash
test -f agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/02+01_preset_generation/complete.log
test -f agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/04+02,03_preset_model_authorization/complete.log
test -f agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/06+04,05_request_identity_ingress/complete.log
rg --sort path -n 'presetHotPathEnabled|mappedControlPath|collectPresetTunnelResult|classifyHotPathOutput' apps/edge/internal/openai --glob '*.go'
go test -count=1 ./apps/edge/internal/openai -run 'TestHotPath(SelectorDecisionMatrix|PresetHandlersDirect|Direct)'
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Selector|PresetHandlers|Direct)'
go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service
route_selector_followup_tmp_dir="$(mktemp -d /config/.tmp-iop-route-selector-followup.XXXXXX)"
TMPDIR="$route_selector_followup_tmp_dir" go test -count=1 ./apps/edge/...
rmdir "$route_selector_followup_tmp_dir"
go vet ./apps/edge/...
gofmt -d apps/edge/internal/openai/hot_path_dispatch.go apps/edge/internal/openai/hot_path_selector.go apps/edge/internal/openai/hot_path_selector_test.go apps/edge/internal/openai/hot_path_direct_test.go
git diff --check
```

_Actual stdout/stderr:_

```text
apps/edge/internal/openai/anthropic_handler.go:66:	if presetHotPathEnabled(dispatch) {
apps/edge/internal/openai/chat_handler.go:352:	if presetHotPathEnabled(dc.route) {
apps/edge/internal/openai/hot_path_dispatch.go:31:func presetHotPathEnabled(dispatch routeDispatch) bool {
apps/edge/internal/openai/hot_path_dispatch.go:75:		stage, err = collectPresetTunnelResult(ctx, result.Tunnel, selected, protocol)
apps/edge/internal/openai/hot_path_dispatch.go:183:func collectPresetTunnelResult(ctx context.Context, handle edgeservice.ProviderTunnelResult, selected edgeservice.RunDispatch, protocol string) (normalizedStageOutput, error) {
apps/edge/internal/openai/hot_path_dispatch.go:793:	decision, err := classifyHotPathOutput(preset, issued, output, gate)
apps/edge/internal/openai/hot_path_selector.go:97:func classifyHotPathOutput(preset config.ExecutionPreset, issuedPaths reservedPaths, output normalizedStageOutput, gate hotPathSelectorGate) (hotPathDecision, error) {
apps/edge/internal/openai/hot_path_selector.go:210:			mappedPath, ok := mappedControlPath(tc, op)
apps/edge/internal/openai/hot_path_selector.go:248:func mappedControlPath(tc normalizedToolCall, op config.ExecutionWorkspaceOperation) (string, bool) {
apps/edge/internal/openai/hot_path_selector_test.go:111:			decision, err := classifyHotPathOutput(test.preset, issued, test.output, test.gate)
apps/edge/internal/openai/hot_path_selector_test.go:113:				t.Fatalf("classifyHotPathOutput() error = %v, wantErr %v", err, test.wantErr)
ok  	iop/apps/edge/internal/openai	0.039s
ok  	iop/apps/edge/internal/openai	1.172s
ok  	iop/packages/go/streamgate	2.006s
ok  	iop/packages/go/config	1.598s
ok  	iop/apps/edge/cmd/edge	1.693s
ok  	iop/apps/edge/internal/authprojection	0.166s
ok  	iop/apps/edge/internal/bootstrap	12.715s
ok  	iop/apps/edge/internal/configrefresh	1.443s
ok  	iop/apps/edge/internal/controlplane	6.819s
ok  	iop/apps/edge/internal/edgecmd	0.765s
ok  	iop/apps/edge/internal/edgevalidate	0.202s
ok  	iop/apps/edge/internal/events	0.146s
ok  	iop/apps/edge/internal/input	0.267s
ok  	iop/apps/edge/internal/input/a2a	0.141s
ok  	iop/apps/edge/internal/node	0.131s
```

The rerun after the raw/decoded source regression passed the focused tests but the final common-race and full-Edge block failed:

```text
--- FAIL: TestAnthropicNativeVirtualPresetPreservesPublicModelIdentity (0.01s)
    --- FAIL: TestAnthropicNativeVirtualPresetPreservesPublicModelIdentity/fragmented_SSE (0.00s)
    --- FAIL: TestAnthropicNativeVirtualPresetPreservesPublicModelIdentity/END_before_response_start_returns_provider_error (0.00s)
    --- FAIL: TestAnthropicNativeVirtualPresetPreservesPublicModelIdentity/BODY_before_response_start_preserves_raw_baseline (0.00s)
--- FAIL: TestVirtualPresetModelHandlersPreservePublicIdentity (0.00s)
FAIL	iop/apps/edge/internal/openai	7.956s
FAIL
FAIL	iop/apps/edge/internal/openai	7.702s
FAIL
```

The same block passed `go vet ./apps/edge/...`, `gofmt -d ...`, and `git diff --check` with no stdout/stderr before reporting the test failures.

---

> **[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 — `agent-contract/outer/anthropic-compatible-api.md:160`, `agent-contract/outer/anthropic-compatible-api.md:195`, `agent-contract/outer/anthropic-compatible-api.md:286`, and `agent-spec/input/openai-compatible-surface.md:139`: the new direct-only preset path now buffers and re-encodes selector tunnel output according to the caller `stream` flag, rejects a missing provider response ID, and fail-closes BODY/END frames that arrive before `RESPONSE_START`, but the active API contract and living spec still promise raw native tunnel relay and an Anthropic `msg_iop` identity fallback. The fresh common-race/full-Edge runs expose this drift in three `TestAnthropicNativeVirtualPresetPreservesPublicModelIdentity` cases. Define the virtual-preset Hot Path exception in the OpenAI/Anthropic contracts and living spec, then migrate those tests to assert caller-requested stream shape, provider identity, and fail-closed pre-start handling while retaining raw relay assertions for ordinary routes.
  - Required — `apps/edge/internal/openai/principal_routes_test.go:1227`: the existing Chat virtual-preset handler fixture omits the profile driver and capabilities now required by the immutable selector gate, so the required common-race/full-Edge commands fail with `unhealthy_route` instead of proving public identity through the direct terminal path. Supply complete pinned dispatch evidence and assert the virtual model, provider response ID, and terminal coordinator state under the production direct path.
  - Required — `apps/edge/internal/openai/hot_path_direct_test.go:137`: the plan requires missing-provider-identity regressions across provider JSON/SSE decoding for both public protocols, but the table covers Chat JSON/SSE and Messages JSON only. Add a Messages SSE fixture without `message_start.message.id`, require an endpoint-standard `api_error`, prove transport run/frame metadata is absent from the public response, and rerun every required focused, race, full Edge, vet, formatting, and diff command to exit zero.
- Routing Signals:
  - review_rework_count=3
  - evidence_integrity_failure=false
- Next Step: Invoke the plan skill in `prepare-follow-up` mode with these raw findings, rerun isolated task routing, archive this pair, and materialize the routed follow-up pair. Do not write `complete.log`.
