<!-- task=m-iop-owned-single-request-agent-execution/10+09_workspace_files plan=2 tag=REVIEW_API milestone-task=tool-executor -->

# 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.
> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt.
> 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-06
task=m-iop-owned-single-request-agent-execution/10+09_workspace_files, plan=2, tag=REVIEW_API

## Archive Evidence Snapshot

- Plan 1 and its FAIL review are preserved at `agent-task/m-iop-owned-single-request-agent-execution/10+09_workspace_files/plan_cloud_G08_1.log` and `agent-task/m-iop-owned-single-request-agent-execution/10+09_workspace_files/code_review_cloud_G09_1.log`.
- The review recorded Required findings R1–R7: unrepresentable typed writes; missing immutable request capabilities/limits and operation-aware catalog validation; symlink-parent mutation before rejection; unbounded list allocation; Go 1.24-incompatible `os.Root` methods; raw startup-path disclosure; and missing bootstrap/lifecycle/adversarial proof.
- Fresh focused race and package tests passed, but required vet failed on the Go 1.25-only `os.Root.MkdirAll` and `os.Root.Rename` calls. Darwin arm64 compile, documentation search, and whitespace checks passed. A temporary focused test proved that a rejected write can create a directory through an in-root symlink; the reproducer was removed after confirmation.
- The prior no-verdict pass remains preserved as `plan_cloud_G08_0.log` and `code_review_cloud_G09_0.log`. The unique predecessor completion evidence is `agent-task/archive/2026/08/m-iop-owned-single-request-agent-execution/09+08_workspace_wire/complete.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-G10.md` and `PLAN-cloud-G10.md` to the next collision-free suffix logs.
3. If PASS, write `complete.log` and move the active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/10+09_workspace_files/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
4. If PASS, preserve the first-line `milestone-task=tool-executor` metadata in `complete.log` and report it for runtime aggregation. 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 Repair the wire and freeze request authority | [x] |
| REVIEW_API-2 Enforce no-follow effects and bounded listing at Go 1.24 | [x] |
| REVIEW_API-3 Prove startup redaction and lifecycle ordering | [x] |

## Implementation Checklist

- [x] Repair typed write and immutable request capability/limit wire semantics, regenerate bindings, and enforce Edge-to-Node narrowing with operation-aware catalog validation.
- [x] Replace pre-effect, unbounded, and Go 1.25-only filesystem paths with Go 1.24 descriptor-relative no-follow bounded operations and permanent regression tests.
- [x] Prove raw-free startup, before-ready validation, workspace-first teardown, adversarial guarantees, and synchronize contract/spec only after verification passes.
- [x] Fill implementation-owned sections in `CODE_REVIEW-cloud-G10.md` with actual decisions, deviations, and uncached command output.

## Review-Only Checklist

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

- [x] Append PASS/WARN/FAIL, routing signals, dimensions, and findings.
- [x] Archive the routed active pair to the next collision-free suffix logs.
- [x] Verify managed `.gitignore` entries.
- [x] On PASS write `complete.log`, preserve/report Milestone metadata, move this directory, and keep the active parent while siblings remain.
- [ ] On WARN/FAIL create only the required next loop state.

## Deviations from Plan

None.

## Key Design Decisions

- Preserved `WorkspaceToolRequest` fields 1-9, added structured `WorkspaceWriteInput` on oneof field 10, and retained legacy `write_content` as an explicitly rejected incomplete WRITE shape. Edge constructs a new open message from the frozen binding, and Node normalizes, validates, and defensively copies the complete request authority.
- Request admission is operation-aware: operations and command ids must be catalog subsets, effective limits must be positive and no larger only when consumed, disabled-operation limits are zero on the outbound wire, and duplicate open is idempotent only for identical normalized authority.
- Replaced write-path resolution with Go 1.24 descriptor-relative `openat`/`mkdirat`/`renameat` primitives. Every parent is opened no-follow and checked for the admitted device before an effect; temp creation and rename use the same descriptor, with parent and target identity revalidated before replacement.
- LIST reads fixed-size batches, retains at most the lexical result cap in a max-heap, and applies deterministic ordering and encoded-output bounds without allocation proportional to the directory size.
- Workspace startup errors are stable and path-free. Test-only composition/close seams prove handler installation before ready and `registry -> workspace -> session -> store` teardown for direct close and reconnect replacement. Command execution, cancellation behavior, and cleanup remain deferred.

## Reviewer Checkpoints

- Confirm the Edge builds open authority only from the frozen request binding and the Node rejects every widening, unknown command id, over-limit value, conflicting duplicate, and legacy/incomplete WRITE.
- Confirm structured WRITE reaches `Runtime.Write`, existing protobuf field numbers remain stable, and generated Go/Dart bindings are synchronized.
- Confirm every write parent component is validated no-follow before mutation; the temp and rename stay relative to the same validated directory descriptor; rejected symlink/mount/replaced-parent/special-file paths have zero effects.
- Confirm LIST consumes fixed-size batches, retains no more than the explicit result cap, preserves deterministic ordering, and truncates at entry or encoded-byte bounds.
- Confirm no Go 1.25-only API remains and both declared-baseline vet and Darwin arm64 compile pass.
- Confirm catalog failures never expose a root sentinel in returned errors or logs, invalid catalogs fail before `SignalReady`, the handler is installed before successful ready, and teardown closes workspace before session/store.
- Confirm contract/spec claims match passing file-operation evidence while command, cancel, and cleanup remain deferred.

## Verification Results

Paste actual stdout/stderr for every command; record replacements under deviations.

### 1. Dependency

`test -f agent-task/m-iop-owned-single-request-agent-execution/09+08_workspace_wire/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/09+08_workspace_wire/complete.log' | wc -l)" -eq 1`

```text
no stdout/stderr
exit 0
```

### 2. Protobuf generation

`make proto && make proto-dart`

```text
protoc \
	--go_out=. \
	--go_opt=module=iop \
	--proto_path=. \
	proto/iop/runtime.proto \
	proto/iop/node.proto \
	proto/iop/control.proto \
	proto/iop/job.proto
mkdir -p apps/client/lib/gen
protoc \
	--plugin=protoc-gen-dart=/config/.local/bin/protoc-gen-dart \
	--dart_out=apps/client/lib/gen \
	--proto_path=. \
	--proto_path=/config/.local/include \
	proto/iop/runtime.proto \
	proto/iop/node.proto \
	proto/iop/control.proto \
	proto/iop/job.proto
exit 0
```

### 3. Workspace race tests

`go test -race ./apps/node/internal/workspace -run 'Test(Runtime|FileExecutor)' -count=1`

```text
ok  	iop/apps/node/internal/workspace	1.063s
exit 0
```

### 4. Wire/handler/bootstrap/parser race tests

`go test -race ./apps/edge/internal/service ./apps/node/internal/node ./apps/node/internal/bootstrap ./apps/node/internal/transport -run 'Test(WorkspaceWire|NodeWorkspace|WorkspaceRuntime|NodeParserMapWorkspace)' -count=1`

```text
ok  	iop/apps/edge/internal/service	1.220s
ok  	iop/apps/node/internal/node	1.073s
ok  	iop/apps/node/internal/bootstrap	1.072s
ok  	iop/apps/node/internal/transport	1.041s
exit 0
```

### 5. Package regression

`go test ./apps/edge/internal/service ./apps/node/internal/workspace ./apps/node/internal/node ./apps/node/internal/bootstrap ./apps/node/internal/transport -count=1`

```text
ok  	iop/apps/edge/internal/service	6.195s
ok  	iop/apps/node/internal/workspace	0.069s
ok  	iop/apps/node/internal/node	0.875s
ok  	iop/apps/node/internal/bootstrap	1.381s
ok  	iop/apps/node/internal/transport	5.581s
exit 0
```

### 6. Vet

`go vet ./apps/edge/internal/service ./apps/node/internal/workspace ./apps/node/internal/node ./apps/node/internal/bootstrap ./apps/node/internal/transport`

```text
no stdout/stderr
exit 0
```

### 7. Darwin compile

`GOOS=darwin GOARCH=arm64 go test -c -o /tmp/iop-workspace-files-darwin-followup.test ./apps/node/internal/workspace`

```text
no stdout/stderr
exit 0
```

### 8. Client bindings

`make client-test`

```text
cd apps/client && flutter test
Resolving dependencies...
Downloading packages...
  _flutterfire_internals 1.3.59 (1.3.76 available)
  firebase_core 3.15.2 (4.13.0 available)
  firebase_core_platform_interface 6.0.3 (8.1.0 available)
  firebase_core_web 2.24.1 (3.10.0 available)
  firebase_messaging 15.2.10 (16.5.0 available)
  firebase_messaging_platform_interface 4.6.10 (4.9.3 available)
  firebase_messaging_web 3.10.10 (4.2.4 available)
  matcher 0.12.19 (0.12.20 available)
  meta 1.17.0 (1.19.0 available)
  test_api 0.7.10 (0.7.13 available)
  url_launcher_android 6.3.30 (6.3.32 available)
  vector_math 2.2.0 (2.4.2 available)
Got dependencies!
12 packages have newer versions incompatible with dependency constraints.
Try `flutter pub outdated` for more information.
00:00 +0: loading /config/workspace/iop-s0/apps/client/test/app_shell_test.dart
00:03 +44: All tests passed!
exit 0
```

### 9. Contract/spec search

`rg --sort path -n 'structured write|request authority|Go 1\.24|no-follow|bounded list|before ready|workspace.*before.*session|command.*defer|cleanup.*defer' agent-contract/inner/edge-node-runtime-wire.md agent-spec/runtime/edge-node-execution.md`

```text
agent-contract/inner/edge-node-runtime-wire.md:64:- workspace wire: `NodeConfigPayload.workspaces` delivers the operator-approved Node-private catalog. Edge constructs `WorkspaceOpenRequest` from the frozen request authority and sends every workspace request only to the exact admitted Node id and dispatch-ready connection generation; Node returns the paired typed response. This boundary is independent of provider `RunRequest`, provider execution, and `NodeCommand`.
agent-contract/inner/edge-node-runtime-wire.md:88:- `WorkspaceOpenRequest`: carries the immutable request authority copied from Edge admission: closed operations, allowed command ids, and effective read/write/output/command-timeout limits. Node admits only catalog subsets and equal-or-lower positive limits; disabled operations use zero for their operation-specific limits.
agent-contract/inner/edge-node-runtime-wire.md:89:- `WorkspaceToolRequest`: permits only the closed operation enum and typed input. A structured write carries `relative_path` plus bounded `content`; legacy `write_content` remains wire-compatible but is incomplete and rejected for WRITE. The request contains no caller-selected Node, root, executable, argv, or arbitrary environment.
agent-contract/inner/edge-node-runtime-wire.md:120:- The Node-private executor validates a non-empty Darwin catalog before ready, retains opened root/directory handles as filesystem authority, and copies the complete immutable request authority. Caller paths are canonical relative paths and cannot name `.iop`; only the runtime derives `.iop/job/<request_id>`, and sibling request namespaces are rejected.
agent-contract/inner/edge-node-runtime-wire.md:121:- File execution is Go 1.24 compatible. Write parent components are opened or created descriptor-relatively with no-follow validation before each effect; the temporary file and atomic rename stay relative to the same validated parent descriptor, and parent/target identity is revalidated before replacement. Rejected symlink, mount/foreign-device, replaced-parent, and special-file paths leave no target or temporary artifact.
agent-contract/inner/edge-node-runtime-wire.md:122:- Implemented file semantics are bounded `read`, bounded list processing in fixed-size batches with a fixed retained-entry cap and deterministic lexical truncation, structured write, and non-recursive `delete`. Returned errors and logs use stable text without configured roots, paths, contents, or raw OS errors.
agent-contract/inner/edge-node-runtime-wire.md:123:- Runtime composition installs the workspace handler before ready. Teardown stops the registry, closes workspace resources before session and store resources, and applies the same order during reconnect replacement. Command execution and cancellation remain deferred; request artifact cleanup remains deferred.
agent-spec/runtime/edge-node-execution.md:89:    notes: Capability-gated bounded batch listing, descriptor-relative structured write, and non-recursive delete
agent-spec/runtime/edge-node-execution.md:92:    notes: Reserved namespace, no-effect symlink/parent/device rejection, bounded listing, atomicity, special-file, and concurrency regressions
agent-spec/runtime/edge-node-execution.md:138:| workspace runtime wire | The dedicated `WorkspaceOpen`/`Tool`/`Cancel`/`Cleanup` request-response families carry immutable coordinator identities and closed status/error codes. Edge overwrites open capabilities with frozen request authority; Node copies only catalog-subset operations/command ids and equal-or-lower effective limits. |
agent-spec/runtime/edge-node-execution.md:139:| workspace file executor | A validated Darwin Node catalog owns opened root and directory handles. Go 1.24-compatible no-follow file primitives provide bounded read, bounded list, structured write, and non-recursive delete with stable typed results; command execution, cancellation, and cleanup remain deferred. |
agent-spec/runtime/edge-node-execution.md:159:- The Node-private workspace request/result wire is implemented, including catalog delivery, parser registration, optional handler behavior, stable typed failures, generation-fenced dispatch, and context-cancel propagation. The Node validates the Darwin catalog before ready, installs the workspace handler before ready, and closes workspace authority before session/store teardown. Request authority is immutable and request-local. File operations reserve `.iop`, reject symlink/mount/replaced-parent/special-file paths before effects, process bounded list batches with deterministic truncation, and use a same-parent structured write. Command/process execution and cancellation are deferred; artifact cleanup is deferred.
agent-spec/runtime/edge-node-execution.md:227:- Workspace admission and the private wire both fence the exact ready connection generation. The wire never exposes workspace fields through provider `RunRequest`, `NodeCommand`, or public API output. The executor exposes no caller access to `.iop`; only request-owned internal runtime code can derive `.iop/job/<request_id>`. Structured write input is required for WRITE, while legacy content-only input remains rejected. Command execution/cancellation and cleanup are deferred to their scheduled packets.
agent-spec/runtime/edge-node-execution.md:241:- 2026-08-06: Completed the reviewed workspace file boundary repair. Edge now sends only frozen request authority, Node admits immutable catalog subsets/lower limits, and structured write reaches the file executor while legacy incomplete input remains rejected. The Go 1.24-compatible descriptor-relative no-follow write path validates before effects, bounded list processing retains fixed state, startup errors are path-free, and composition proves handler-before-ready plus workspace-before-session/store teardown. Command execution/cancellation and cleanup remain deferred.
exit 0
```

### 10. Formatting and whitespace

`gofmt -d apps/edge/internal/service/workspace_wire.go apps/edge/internal/service/workspace_wire_test.go apps/node/internal/workspace/runtime.go apps/node/internal/workspace/runtime_test.go apps/node/internal/workspace/path.go apps/node/internal/workspace/identity_unix.go apps/node/internal/workspace/identity_other.go apps/node/internal/workspace/file_executor.go apps/node/internal/workspace/file_executor_test.go apps/node/internal/node/workspace_handler.go apps/node/internal/node/workspace_handler_test.go apps/node/internal/transport/parser_test.go apps/node/internal/bootstrap/module.go apps/node/internal/bootstrap/workspace_runtime_test.go && git diff --check`

```text
no stdout/stderr
exit 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) |
| 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

PASS

### Dimension Assessment

| Dimension | Result | Evidence |
|-----------|--------|----------|
| Correctness | Pass | Structured WRITE reaches `Runtime.Write`; Edge overwrites caller authority from the frozen workspace binding; Node admits only catalog subsets/lower limits; descriptor-relative writes reject unsafe parents before effects; and LIST retains fixed bounded state. |
| Completeness | Pass | REVIEW_API-1 through REVIEW_API-3 and every implementation-owned checklist item are complete, including generated bindings, lifecycle composition, contract/spec synchronization, and recorded verification. |
| Test coverage | Pass | Permanent tests cover structured and legacy WRITE shapes, authority widening and immutable copies, unsafe parent/no-effect behavior, bounded deterministic listing, atomic failure, special files, concurrent requests, startup redaction, readiness, and teardown order. |
| API contract | Pass | Existing `WorkspaceToolRequest` fields 1-9 remain stable, structured WRITE uses field 10, open authority uses additive fields, and regenerated Go/Dart bindings match the protobuf source. |
| Code quality | Pass | The implementation is focused, formatted, free of Go 1.25-only APIs, and keeps stable raw-free failure projection with command/cancel/cleanup deferrals explicit. |
| Implementation deviation | Pass | No implementation deviation or unplanned behavioral expansion was found. |
| Verification trust | Pass | All ten declared commands were rerun successfully from the current checkout; focused race, package, vet, Darwin compile, Flutter, documentation, formatting, and whitespace evidence matches the source. |
| Spec conformance | Pass | The implemented file-operation contribution satisfies the applicable S04/S05 containment, typed wire, bounded-output, and lifecycle evidence while preserving the scheduled command/cancel/cleanup deferrals. |

### Findings

None.

### Routing Signals

- `review_rework_count=1`
- `evidence_integrity_failure=false`

### Fresh Verification Summary

- The unique packet 09 dependency check passed.
- `make proto && make proto-dart` completed successfully and regenerated matching Go/Dart bindings.
- Both declared focused race commands and the declared package regression command passed with fresh execution.
- The declared targeted vet command and supplemental `go vet ./apps/node/...` passed at the Go 1.24 module language baseline.
- Darwin arm64 workspace compilation, `make client-test`, contract/spec search, `gofmt -d`, and `git diff --check` passed.
- Supplemental `go test -count=1 ./apps/node/...` passed.

### Next Step

PASS: archive the active pair, write `complete.log`, and move this completed subtask under the August 2026 task archive while preserving `milestone-task=tool-executor` completion metadata.
