<!-- task=m-iop-agent-cli-runtime/05_contract_boundary plan=1 tag=REVIEW_API -->

# 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-07-28
task=m-iop-agent-cli-runtime/05_contract_boundary, plan=1, tag=REVIEW_API

## Archive Evidence Snapshot

- Prior task: `agent-task/m-iop-agent-cli-runtime/05_contract_boundary`
- Archived plan: `agent-task/m-iop-agent-cli-runtime/05_contract_boundary/plan_local_G07_0.log`
- Archived review: `agent-task/m-iop-agent-cli-runtime/05_contract_boundary/code_review_cloud_G07_0.log`
- Verdict: `FAIL`
- Findings: 2 Required, 0 Suggested, 0 Nit.
- Required fixes:
  - Remove duplicate authoritative ownership of `packages/go/agenttask/**` and `packages/go/agentguard/**`; delegate shared manager, guardrail, review, and integration-port semantics to `iop.agent-runtime`.
  - Define the SDD-required versioned local proto-socket state/event/control/client-process contract and connect it to S11 and S15.
- Affected files: `agent-contract/index.md`, `agent-contract/inner/iop-agent-cli-runtime.md`.
- Verification evidence: the contract path search completed; fresh `go test -count=1 ./packages/go/agenttask ./packages/go/agentguard` and `git diff --check` passed. Fresh symbol search found no `IntegrationRecord` type under `packages/go`, contradicting the implementation note that every listed type was code-backed.
- Roadmap carryover: the approved SDD is unlocked. This preparatory contract task does not check a Milestone Task on PASS; it supplies contract anchors for later S05-S09, S11, S15, S18, and S19 implementation evidence.
- Read the two archived files above only if exact prior-loop wording is required; do not scan `agent-task/archive/**`.

## 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-G07.md` → `code_review_cloud_G07_1.log` and `PLAN-cloud-G07.md` → `plan_cloud_G07_1.log`.
3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-agent-cli-runtime/05_contract_boundary/`. 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>`, report completion event metadata. Roadmap state check and `update-roadmap` calls are runtime responsibilities.
5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting.

---

## Implementation Item Completion

| Item | Status |
|------|---------|
| REVIEW_API-1 Restore one authoritative owner for shared runtime semantics | COMPLETE |
| REVIEW_API-2 Define the local control and client-process protocol boundary | COMPLETE |

## Implementation Checklist

- [x] Delegate shared `agenttask`/`agentguard` ownership to `iop.agent-runtime` and remove duplicate authoritative source-path, read-condition, and core-rule claims from the CLI runtime contract and index row.
- [x] Define the versioned client-neutral local proto-socket state/event/control/client-process boundary, peer authorization, idempotency/replay/failure semantics, and S11/S15 evidence mappings.
- [x] Run deterministic contract searches, fresh targeted Go regression tests, and `git diff --check`, then record exact output.
- [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_G07_1.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G07_1.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-agent-cli-runtime/05_contract_boundary/` to `agent-task/archive/YYYY/MM/m-iop-agent-cli-runtime/05_contract_boundary/` and update this checklist at the final archive path.
- [ ] If PASS and task group is `m-<milestone-slug>`, report completion event metadata for runtime, without modifying roadmap or directly calling `update-roadmap`.
- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-agent-cli-runtime/` 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

None. The local test rule also required a Go environment preflight before the planned regression command; it reported `/config/.local/bin/go`, `/config/opt/go/bin/go`, `go version go1.26.2 linux/arm64`, and `GOROOT=/config/opt/go`.

## Key Design Decisions

- `iop.agent-runtime` remains the only authority for shared `agenttask` and `agentguard` semantics and implementation paths.
- The standalone contract is explicitly contract-first until an S05-S09/S11/S15/S18/S19 task adds a concrete host implementation path.
- Local control uses a versioned, client-neutral envelope with same-effective-OS-user peer-credential authorization, stable mutation command IDs, replay cursors, and snapshot-required recovery.
- Flutter and Unity remain daemon-owned clients; Unity detail requests route through `iop-agent` to Flutter start/focus rather than creating direct client-to-client control.

## Reviewer Checkpoints

- The `iop.agent-cli-runtime` index row no longer lists `packages/go/agenttask/**` or `packages/go/agentguard/**` as an implementation source.
- The CLI contract delegates shared manager/guardrail/review/integration-port semantics to `iop.agent-runtime` and retains only standalone host extensions.
- The CLI contract defines all five `LocalControl*` schema anchors, operations, same-user peer authorization, idempotency, replay/failure behavior, client-process ownership, and S11/S15 evidence rows.
- No Go, proto, config, SDD, roadmap, test, or dependent task file changed.

## Verification Results

Paste exact stdout/stderr for every command. Do not summarize or reconstruct output. If a command changes, record the replacement and reason under `Deviations from Plan`.

### Contract index ownership assertion

```bash
cli_row="$(rg '^\| `iop\.agent-cli-runtime`' agent-contract/index.md)"
printf '%s\n' "$cli_row"
! printf '%s\n' "$cli_row" | rg -q 'packages/go/agent(task|guard)'
```

```text
| `iop.agent-cli-runtime` | Standalone `iop-agent` host lifecycle, repo-global/user-local configuration, device process ownership, local state records, isolation/change-set extension points, and the client-neutral local control boundary: `LocalControlEnvelope`, `LocalControlRequest`, `LocalControlResponse`, `LocalControlEvent`, `LocalControlError`, peer authorization, replay, and Flutter/Unity client-process commands (S05-S09, S11, S15, S18-S19) | Contract-first standalone host boundary; shared runtime implementation and `agenttask`/`agentguard` semantics are owned by `iop.agent-runtime`. Standalone host implementation paths are added by S05-S09/S11/S15/S18-S19 implementation tasks. Design input: `agent-roadmap/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md` | `agent-contract/inner/iop-agent-cli-runtime.md` |
```

Exit status: 0

### Shared contract delegation search

```bash
rg --sort path -n 'iop\.agent-runtime|shared contract dependency|implementation source status' agent-contract/index.md agent-contract/inner/iop-agent-cli-runtime.md agent-contract/inner/agent-runtime.md
```

```text
agent-contract/index.md:26:| `iop.agent-runtime` | 공통 Agent Runtime, CLI Provider, AgentTaskManager manual start/auto-resume/explicit dependency/isolated dispatch/review/serial integration, workspace guardrail admission, agent provider catalog YAML, provider/model/profile discovery와 readiness, `Provider`, `ExecutionSpec`, `RuntimeEvent`, run/stream/resume/cancel, terminal exactly-once, status/quota, typed failure codec, Node runtime bridge | `packages/go/agentruntime/*`, `packages/go/agenttask/*`, `packages/go/agentguard/*`, `packages/go/agentconfig/*`, `packages/go/agentprovider/cli/*`, `packages/go/agentprovider/catalog/*`, `configs/iop-agent.providers.yaml`, `apps/node/internal/node/runtime_bridge.go` |
agent-contract/index.md:27:| `iop.agent-cli-runtime` | Standalone `iop-agent` host lifecycle, repo-global/user-local configuration, device process ownership, local state records, isolation/change-set extension points, and the client-neutral local control boundary: `LocalControlEnvelope`, `LocalControlRequest`, `LocalControlResponse`, `LocalControlEvent`, `LocalControlError`, peer authorization, replay, and Flutter/Unity client-process commands (S05-S09, S11, S15, S18-S19) | Contract-first standalone host boundary; shared runtime implementation and `agenttask`/`agentguard` semantics are owned by `iop.agent-runtime`. Standalone host implementation paths are added by S05-S09/S11/S15/S18-S19 implementation tasks. Design input: `agent-roadmap/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md` | `agent-contract/inner/iop-agent-cli-runtime.md` |
agent-contract/inner/iop-agent-cli-runtime.md:8:- shared contract dependency: `iop.agent-runtime`
agent-contract/inner/iop-agent-cli-runtime.md:9:- implementation source status: contract-first; standalone host source paths are added by the S05-S09, S11, S15, S18, and S19 implementation tasks.
agent-contract/inner/iop-agent-cli-runtime.md:15:- changing the host extension points for workspace isolation or change-set persistence while preserving the shared runtime ports owned by `iop.agent-runtime`;
agent-contract/inner/iop-agent-cli-runtime.md:23:`iop.agent-runtime` is the sole authoritative contract for common provider execution, `agenttask.Manager` lifecycle and state transitions, `agentguard` admission and Permit validation, review, integration ports, and their source paths. This contract may require the host to call those shared boundaries, but it does not restate their rules or claim their implementation sources.
agent-contract/inner/iop-agent-cli-runtime.md:46:- Host isolation and change-set implementations are extension points. Their preparation, admission, review, and integration semantics remain delegated to `iop.agent-runtime`; the host must preserve the returned immutable identities when persisting or presenting state.
agent-contract/inner/iop-agent-cli-runtime.md:63:| Project mutation | `project.start`, `project.stop`, `project.resume` | Require `command_id`; delegate shared lifecycle actions to `iop.agent-runtime`; persist only host-owned command presentation and recovery state. |
agent-contract/inner/agent-runtime.md:5:- id: `iop.agent-runtime`
```

Exit status: 0

### Local control contract search

```bash
rg --sort path -n 'LocalControl(Envelope|Request|Response|Event|Error)|command_id|peer credential|same OS user|replay|S11|S15' agent-contract/index.md agent-contract/inner/iop-agent-cli-runtime.md
```

```text
agent-contract/index.md:27:| `iop.agent-cli-runtime` | Standalone `iop-agent` host lifecycle, repo-global/user-local configuration, device process ownership, local state records, isolation/change-set extension points, and the client-neutral local control boundary: `LocalControlEnvelope`, `LocalControlRequest`, `LocalControlResponse`, `LocalControlEvent`, `LocalControlError`, peer authorization, replay, and Flutter/Unity client-process commands (S05-S09, S11, S15, S18-S19) | Contract-first standalone host boundary; shared runtime implementation and `agenttask`/`agentguard` semantics are owned by `iop.agent-runtime`. Standalone host implementation paths are added by S05-S09/S11/S15/S18/S19 implementation tasks. Design input: `agent-roadmap/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md` | `agent-contract/inner/iop-agent-cli-runtime.md` |
agent-contract/inner/iop-agent-cli-runtime.md:9:- implementation source status: contract-first; standalone host source paths are added by the S05-S09, S11, S15, S18, and S19 implementation tasks.
agent-contract/inner/iop-agent-cli-runtime.md:16:- changing `LocalControlEnvelope`, `LocalControlRequest`, `LocalControlResponse`, `LocalControlEvent`, or `LocalControlError`, including peer authorization, command idempotency, replay, or failure behavior;
agent-contract/inner/iop-agent-cli-runtime.md:36:| S11 | Same-user local-control authorization, state/event delivery, replay-gap, and denied-peer tests | `local-control` proves no app-token fallback, denied cross-user dispatch, and snapshot recovery. |
agent-contract/inner/iop-agent-cli-runtime.md:37:| S15 | Flutter/Unity singleton-process, disconnect/crash/reconnect, and Unity detail-routing tests | `client-process-manager` proves daemon-owned lifecycle and Flutter start/focus routing. |
agent-contract/inner/iop-agent-cli-runtime.md:51:- `LocalControlEnvelope` is the outer schema for every frame. It contains `protocol_version`, `kind`, `message_id`, `correlation_id`, optional `event_sequence`, optional `operation`, and a typed payload. `kind` is exactly `request`, `response`, `event`, or `error`.
agent-contract/inner/iop-agent-cli-runtime.md:52:- `LocalControlRequest` carries a request envelope, operation arguments, and an optional replay cursor. Every mutating request also carries a stable, caller-generated `command_id`.
agent-contract/inner/iop-agent-cli-runtime.md:53:- `LocalControlResponse` carries the correlated operation result, current state revision or snapshot marker when applicable, and the accepted `command_id` for a mutation.
agent-contract/inner/iop-agent-cli-runtime.md:54:- `LocalControlEvent` carries an ordered `event_sequence`, event type, subject identity, state revision, and a payload that is sufficient to update a current snapshot.
agent-contract/inner/iop-agent-cli-runtime.md:55:- `LocalControlError` carries a stable error code, safe message, retryability, correlation identifier, and recovery metadata such as the current replay floor or snapshot marker.
agent-contract/inner/iop-agent-cli-runtime.md:63:| Project mutation | `project.start`, `project.stop`, `project.resume` | Require `command_id`; delegate shared lifecycle actions to `iop.agent-runtime`; persist only host-owned command presentation and recovery state. |
agent-contract/inner/iop-agent-cli-runtime.md:64:| Client mutation | `client.start`, `client.stop`, `client.focus`, `client.detail` | Require `command_id`; execute only through daemon-owned client-process records. `client.detail` routes a supported Unity detail request to Flutter start/focus through the daemon. |
agent-contract/inner/iop-agent-cli-runtime.md:66:- The daemon authorizes a peer from local socket ownership and peer credential evidence. It accepts only a peer with the same effective OS user as the daemon; all other peers receive `permission_denied` before command dispatch.
agent-contract/inner/iop-agent-cli-runtime.md:67:- A client uses no app token for this boundary, and no app-token fallback may bypass peer credential or same OS user authorization.
agent-contract/inner/iop-agent-cli-runtime.md:68:- Repeating a mutation with the same `command_id`, operation, and immutable arguments returns the original accepted result without a second mutation. Reusing that `command_id` with different operation or arguments returns `command_id_conflict` and performs no mutation.
agent-contract/inner/iop-agent-cli-runtime.md:73:- Events are ordered by a monotonically increasing `event_sequence` within one daemon identity. Clients may reconnect with a replay cursor and must tolerate duplicate retained events by deduplicating their sequence.
agent-contract/inner/iop-agent-cli-runtime.md:74:- The daemon replays retained events after the requested cursor when the cursor is within retention. If the cursor predates the retention floor, belongs to another daemon identity, or cannot form a contiguous replay, it returns `replay_unavailable` with `snapshot_required` recovery metadata instead of silently omitting state changes.
agent-contract/inner/iop-agent-cli-runtime.md:75:- A snapshot response establishes the current state revision and replay cursor from which later events may resume. The daemon may coalesce non-essential progress events, but it must not claim a replay that hides a state transition represented by the current snapshot.
agent-contract/inner/iop-agent-cli-runtime.md:76:- `LocalControlError` uses typed codes at minimum: `malformed_frame`, `unsupported_version`, `unsupported_operation`, `invalid_state`, `permission_denied`, `command_id_conflict`, `replay_unavailable`, and `internal`.
agent-contract/inner/iop-agent-cli-runtime.md:83:- Crash restart and login launch follow user-local policy. A disconnect preserves daemon ownership, records the process outcome, and allows a same-user client to reconnect and replay or request a snapshot.
agent-contract/inner/iop-agent-cli-runtime.md:91:- Do not dispatch a mutating operation before peer authorization and `command_id` validation, or make rejected frames mutate host state.
agent-contract/inner/iop-agent-cli-runtime.md:92:- Do not silently discard a replay gap, fabricate a contiguous event sequence, or treat a stale cursor as a current snapshot.
agent-contract/inner/iop-agent-cli-runtime.md:99:- For local-control changes, update the operation matrix, authorization, idempotency, replay, failure, and client lifecycle rules together.
agent-contract/inner/iop-agent-cli-runtime.md:100:- For a concrete transport implementation, add its actual host source paths and focused tests in the implementing S11 or S15 task; do not backfill speculative paths here.
agent-contract/inner/iop-agent-cli-runtime.md:101:- Verify standalone contract changes with index ownership searches, S11/S15 anchor searches, the relevant future host tests when they exist, and `git diff --check`.
```

Exit status: 0

### Fresh shared runtime regression tests

```bash
go test -count=1 ./packages/go/agenttask ./packages/go/agentguard
```

```text
ok  	iop/packages/go/agenttask	0.140s
ok  	iop/packages/go/agentguard	0.014s
```

Exit status: 0

### Diff validation

```bash
git diff --check
```

```text
```

Exit status: 0

---

> **[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) |
| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS |
| 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 |
| Agent UI Completion | Mixed | Present only for plan-required agent-ui code work; implementing agent fills actual evidence, review agent applies the implemented status/evidence update on PASS and copies the section into `complete.log` |
| 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

| Dimension | Assessment | Evidence |
|---|---|---|
| Correctness | Fail | The repaired ownership boundary removes contract-first host schemas that later S05-S09/S18-S19 implementations need to interpret configuration, recovery, overlay, and change-set state consistently. |
| Completeness | Fail | The active plan required standalone host concerns to remain defined, but the contract now reduces them to four general rules and omits the SDD-assigned host schema anchors. |
| Test Coverage | Fail | The planned searches verify delegation and local control only; they do not detect removal of the standalone host schemas. A focused reviewer assertion found all ten required host anchors absent. |
| API Contract | Fail | `RuntimeConfig`, `ProjectRegistration`, `SelectionPolicy`, `PreviewRequest`, `WorkspaceSnapshot`, `OverlayWorkspace`, `ChangeSet`, `IntegrationRecord`, `ProjectLogRecord`, and `IntegrationStatus` no longer have contract definitions. |
| Code Quality | Pass | The retained delegation and local-control sections are structured and internally readable. |
| Implementation Deviation | Fail | The fix correctly removed shared manager/guard duplication but also removed standalone config, isolation-backend, change-set persistence, and versioned host-record semantics that the plan explicitly said to keep. |
| Verification Trust | Pass | Fresh reviewer runs reproduced the recorded ownership searches, local-control search, Go test results, Go environment preflight, and `git diff --check` result. |
| Spec Conformance | Fail | The approved SDD Interface Contract assigns these standalone host inputs, durable records, and outputs to the first contract task. |

### Findings

- **Required** — `agent-contract/inner/iop-agent-cli-runtime.md:41`: Restore the contract-first standalone host schemas and semantics that were removed while deduplicating shared ownership. The active plan requires repo/local configuration, concrete isolation-backend and change-set persistence, and versioned host failure records to remain here, while the approved SDD assigns `RuntimeConfig`, `ProjectRegistration`, `SelectionPolicy`, `PreviewRequest`, `WorkspaceSnapshot`, `OverlayWorkspace`, `ChangeSet`, `IntegrationRecord`, `ProjectLogRecord`, and `IntegrationStatus` to this boundary. Define those host-owned records, precedence/identity/versioning/failure behavior, and index read anchors without restating `agenttask.Manager`, `agentguard`, review, admission, or integration-port algorithms owned by `iop.agent-runtime`; add a deterministic anchor assertion so this omission cannot pass verification again.

### Routing Signals

review_rework_count=2
evidence_integrity_failure=false

### Next Step

Create the smallest freshly routed follow-up plan that restores the standalone host contract schemas without reintroducing shared runtime ownership, then repeat official review.
