<!-- task=m-iop-owned-single-request-agent-execution/21+20_single_request_executor plan=0 tag=API milestone-task=review-stage -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> Complete the fixed checklists and evidence fields, leave both active files in place, and report ready for review. Only the official review agent may append a verdict, archive files, write `complete.log`, or classify the next state. If blocked, record the blocker, attempted commands/output, and resume condition here; do not change owner or scope.

## Overview

date=2026-08-07
task=m-iop-owned-single-request-agent-execution/21+20_single_request_executor, plan=0, tag=API

## For the Review Agent

Compare every item with source and freshly rerun recorded verification. Then append the official verdict and routing signals. On PASS, archive this file as `code_review_cloud_G08_0.log`, archive the plan as `plan_local_G08_0.log`, write `complete.log` preserving `milestone-task=review-stage`, and move the task directory to the dated archive. On WARN/FAIL, write only the next state prescribed by the code-review skill. The implementing agent must not perform these steps.

## Archive Evidence Snapshot

- Pre-refine parent plan: checkpoint `f4dad6ba88ae442e08ab67f49a5b1a65dd4719e9`, `agent-task/m-iop-owned-single-request-agent-execution/20+19_review_stage/PLAN-cloud-G09.md`.
- Pre-refine parent review: checkpoint `f4dad6ba88ae442e08ab67f49a5b1a65dd4719e9`, `agent-task/m-iop-owned-single-request-agent-execution/20+19_review_stage/CODE_REVIEW-cloud-G09.md`.
- The checkpoint pair contains no implementation evidence or official verdict; refinement split it once into three scope-preserving children. No active-log path is required after predecessor archival.

## Implementation Item Completion

| Item | Status |
|------|---------|
| API-1 Compose the three private stages | [x] |

## Implementation Checklist

- [x] Add a concurrent request-safe composite executor that drives Plan → Work → Review through one controller, reuses the completed continuation bridge, and returns only reviewer-approved output.
- [x] Add pass, inspection, repair, concurrent isolation, cancellation, stage failure, final-output provenance, and waiter-cleanup fixtures under `-race`.
- [x] Run dependency, focused race, service compatibility, OpenAI vet/regression, constructor search, and diff checks without production activation.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** Implementing agents must not modify this section.

- [x] Append one `PASS`, `WARN`, or `FAIL` verdict with verified `review_rework_count` and `evidence_integrity_failure`.
- [x] Verify verdict, dimension assessment, and Required/Suggested/Nit classifications agree.
- [x] Archive this file to `code_review_cloud_G08_0.log` and the plan to `plan_local_G08_0.log`.
- [x] Verify `.gitignore` unignores task Markdown/log files and ignores `agent-roadmap/current.md`.
- [ ] On PASS, write template-compliant `complete.log`, preserve/report `milestone-task=review-stage`, move the task directory to the dated archive, and remove the active parent only if empty.
- [x] On WARN/FAIL, write the exact next filesystem state and do not write `complete.log`.

## Deviations from Plan

None.

## Key Design Decisions

- `SingleRequestExecutor` composes the private `singleRequestPlanStage`, `singleRequestWorkStage`, and `singleRequestReviewStage` behind `edgeservice.SingleRequestExecutor` and `edgeservice.SingleRequestToolContinuation`.
- Per-request sequence numbers are monotonically tracked and incremented via `singleRequestSequenceController` so stage transitions (`planning` -> `working` -> `reviewing`/`repairing` -> `internal_tool` -> `finalizing`) maintain strict monotonic sequence invariants without gaps.
- Correlated workspace tool calls are registered in `singleRequestWorkToolBridge` and automatically cleared on request completion or cancellation via `clearRequest(requestID)` to guarantee waiter cleanup and concurrent request isolation under `-race`.
- Terminal output is strictly reviewer-approved: only `review.run` produces the `finalizing` envelope with output, ensuring unapproved Work output candidates cannot become terminal.

## Reviewer Checkpoints

- Verify one controller and immutable binding span Plan, Work, and Review, and no Work candidate bypasses Review.
- Verify continuation results are delegated through the request-safe bridge with exact identity and no retained waiter on success, failure, timeout, or cancellation.
- Verify only reviewer-approved output is returned, concurrent requests remain isolated, and production installation is still absent from this child.

## Verification Results

Paste actual stdout/stderr for every command. Any replacement requires a matching `Deviations from Plan` entry.

### 1. Dependency evidence

`bash -c 'set -euo pipefail; shopt -s nullglob; candidates=(agent-task/m-iop-owned-single-request-agent-execution/20_*/complete.log agent-task/m-iop-owned-single-request-agent-execution/20+*/complete.log agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/20_*/complete.log agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/20+*/complete.log); printf "%s\n" "${candidates[@]}"; ((${#candidates[@]} == 1))'`

Expected: exactly one predecessor completion path and exit zero.

```text
agent-task/archive/2026/08/m-iop-owned-single-request-agent-execution/20+19_review_repair/complete.log
```

### 2. Focused composite race tests

`go test -race ./apps/edge/internal/openai -run 'TestSingleRequestExecutor' -count=1`

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

### 3. Service state and cleanup compatibility

`go test ./apps/edge/internal/service -run 'TestSingleRequest(InternalToolLoop|Cleanup|EnvelopeOrdering)' -count=1`

```text
ok  	iop/apps/edge/internal/service	0.089s
```

### 4. Changed-path vet and regression

`go vet ./apps/edge/internal/openai && go test ./apps/edge/internal/service ./apps/edge/internal/openai -count=1`

```text
ok  	iop/apps/edge/internal/service	6.510s
ok  	iop/apps/edge/internal/openai	8.067s
```

### 5. Constructor and ownership evidence

`rg --sort path -n 'NewSingleRequestExecutor|SingleRequestExecutor|SingleRequestToolContinuation' apps/edge/internal/openai/single_request_executor.go apps/edge/internal/openai/single_request_executor_test.go`

```text
apps/edge/internal/openai/single_request_executor.go:11:var errSingleRequestExecutor = errors.New("single-request executor: failed")
apps/edge/internal/openai/single_request_executor.go:13:// SingleRequestExecutor is the concurrent, request-safe composite executor
apps/edge/internal/openai/single_request_executor.go:15:type SingleRequestExecutor struct {
apps/edge/internal/openai/single_request_executor.go:23:// NewSingleRequestExecutor constructs a production composite single-request executor
apps/edge/internal/openai/single_request_executor.go:25:func NewSingleRequestExecutor(service edgeserviceRunner) *SingleRequestExecutor {
apps/edge/internal/openai/single_request_executor.go:28:	return &SingleRequestExecutor{
apps/edge/internal/openai/single_request_executor.go:39:func (s *SingleRequestExecutor) ExecuteSingleRequest(ctx context.Context, req edgeservice.SingleRequestRequest, ctrl edgeservice.SingleRequestController) error {
apps/edge/internal/openai/single_request_executor.go:41:		return edgeservice.ErrSingleRequestExecutorUnavailable
apps/edge/internal/openai/single_request_executor.go:116:func (s *SingleRequestExecutor) ContinueInternalTool(ctx context.Context, result edgeservice.InternalWorkspaceToolResult) error {
apps/edge/internal/openai/single_request_executor.go:118:		return edgeservice.ErrSingleRequestExecutorUnavailable
apps/edge/internal/openai/single_request_executor_test.go:21:func newTestServiceHarness(t *testing.T, executor *SingleRequestExecutor) (*edgeservice.Service, *edgeservice.SingleRequestBinding, *workNodeHarness) {
apps/edge/internal/openai/single_request_executor_test.go:65:	service.SetSingleRequestExecutor(executor)
apps/edge/internal/openai/single_request_executor_test.go:106:func TestSingleRequestExecutorInterface(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:107:	executor := NewSingleRequestExecutor(&mockService{})
apps/edge/internal/openai/single_request_executor_test.go:108:	var _ edgeservice.SingleRequestExecutor = executor
apps/edge/internal/openai/single_request_executor_test.go:109:	var _ edgeservice.SingleRequestToolContinuation = executor
apps/edge/internal/openai/single_request_executor_test.go:112:func TestSingleRequestExecutorPass(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:134:	executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:162:func TestSingleRequestExecutorInspection(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:185:	executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:209:func TestSingleRequestExecutorRepair(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:232:	executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:256:func TestSingleRequestExecutorConcurrentIsolation(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:279:	executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:322:func TestSingleRequestExecutorCancellation(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:331:	executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:354:func TestSingleRequestExecutorStageFailures(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:366:		executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:401:		executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:443:		executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:459:func TestSingleRequestExecutorFinalOutputProvenance(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:478:	executor := NewSingleRequestExecutor(mockSvc)
apps/edge/internal/openai/single_request_executor_test.go:497:func TestSingleRequestExecutorWaiterCleanup(t *testing.T) {
apps/edge/internal/openai/single_request_executor_test.go:498:	executor := NewSingleRequestExecutor(&mockService{})
```

### 6. Production activation remains deferred

`bash -c 'set -euo pipefail; if rg --sort path -n "NewSingleRequestExecutor|SetSingleRequestExecutor" apps/edge/internal/input/manager.go; then exit 1; else test $? -eq 1; fi'`

```text
```

### 7. Diff hygiene

`git diff --check`

```text
```

External qualification remains S12 `claude-smoke`.

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**
> Leave review-agent-only sections unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Header, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not change finalization metadata |
| Archive Evidence Snapshot | Fixed at stub creation | Read only cited prior evidence when needed |
| Implementation Item Completion and Checklist text/order | Fixed at stub creation | Implementing agent changes only `[ ]` to `[x]` |
| Review-Only Checklist | Review agent | Implementing agent must not modify it |
| Deviations, Key Design Decisions | Implementing agent | Replace placeholders with actual evidence |
| Reviewer Checkpoints and verification commands | Fixed at stub creation | Implementing agent fills output only; command changes require a deviation |
| Code Review Result | Review agent appends | Not present in this stub |

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Pass
  - Completeness: Fail
  - Test coverage: Fail
  - API contract: Pass
  - Code quality: Pass
  - Implementation deviation: Pass
  - Verification trust: Fail
  - Spec conformance: Fail
- Findings:
  - Required R1 — `apps/edge/internal/openai/single_request_executor_test.go:256`: the composite concurrency fixture never enters an internal workspace tool and expects the same final output for every request, so swapped request continuations or cross-request artifact/result leakage would still pass. `apps/edge/internal/openai/single_request_executor_test.go:497` also invokes `clearRequest` directly instead of cancelling or failing a live composite request with a registered waiter. Replace these with service-backed composite fixtures that use colliding tool-call IDs across request-specific tasks/results, assert per-request final output and artifact ownership, cancel one request while its real waiter is registered, and prove the peer completes with `pendingCount()==0` after success, failure, and cancellation.
  - Nit (repaired) — `apps/edge/internal/openai/single_request_executor.go:3`: removed the unused package-level executor error sentinel and its now-unused import.
- Routing Signals:
  - `review_rework_count=1`
  - `evidence_integrity_failure=true`
- Next Step: Invoke the plan skill in `prepare-follow-up` mode with Required R1 and materialize the routed follow-up pair after archiving this active pair.
