<!-- task=m-iop-agent-cli-runtime/11+06_workspace_overlay plan=0 tag=API -->

# Workspace Overlay Isolation Backend

## For the Implementing Agent

`06+05_config_registry/complete.log`를 확인한다. implementation evidence를 `CODE_REVIEW-cloud-G09.md`에 실제 명령 출력과 함께 기록한다.

## Background

`agentguard`는 이미 prepared isolation descriptor를 검증하지만 overlay를 생성하지 않는다. 동일 pinned dirty base의 task별 writable layer와 temp/cache isolation backend가 필요하다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md)
- Task ids:
  - `overlay-workspace`: pinned base and task writable layer
- Completion mode: check-on-pass

## Analysis

### Files Read

- `packages/go/agentguard/types.go`
- `packages/go/agentguard/canonical.go`
- `packages/go/agentguard/gitmeta.go`
- `packages/go/agentguard/permit.go`
- `packages/go/agentguard/admission_integration_test.go`
- `packages/go/agenttask/ports.go`
- `packages/go/agenttask/dispatch.go`
- `packages/go/agenttask/scheduler_test.go`
- `agent-contract/inner/agent-runtime.md`
- `agent-roadmap/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md`

### SDD Criteria

S18/Evidence Map S18 requires tracked/untracked/dirty/mode/symlink fingerprint, identical base across concurrent tasks, canonical absolute path denial and isolated temp/cache/Git metadata.

### Test Environment Rules

local rules were read. Unix filesystem fixture behavior must be skipped explicitly on unsupported platforms; package tests run fresh locally.

### Test Coverage Gaps

Guard tests validate a supplied descriptor only. No test creates layers or proves two task views retain the same dirty base without cross-write.

### Split Judgment

config registry supplies root/retention policy. Prepare/cleanup and snapshot fingerprint are one filesystem integrity boundary; change-set application is independently planned in `12`.

### Scope Rationale

worktree/full clone fallback may be exposed as descriptors but their backend implementation is not required unless needed by a real Git task. Canonical base mutation is forbidden.

### Final Routing

`first-pass`; cloud G09. concurrent-consistency and boundary-contract risk. official cloud G09 review.

## Implementation Checklist

- [ ] Capture deterministic tracked/untracked/dirty/mode/symlink base fingerprint.
- [ ] Create task-owned layer, merged read view, writable roots and temp/cache under local runtime root.
- [ ] Enforce no canonical base, sibling layer or shared Git metadata writes before `agentguard.Admit`.
- [ ] Preserve overlay locator/retention state for later change-set validation.
- [ ] Add same-file/disjoint, dirty/untracked, absolute-path denial and temp/cache isolation tests.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-1] strict overlay `IsolationBackend`를 구현한다

**Problem:** `agenttask.IsolationBackend.Prepare` is a strict port, while current test fake only fabricates descriptors.

**Solution:** add `packages/go/agentworkspace` backend that snapshots the canonical root before any task invocation and creates per-task layer/read view. Return `agentguard.IsolationDescriptor` only when writable-root enforcement is demonstrable.

**Test Strategy:** filesystem fixtures assert same pinned snapshot, no canonical/sibling mutation, temp/cache separation, dirty and untracked preservation, mode/symlink fingerprints, and retained overlay on failure.

**Verification:** `agentworkspace`, guard and agenttask tests PASS.

## Modified Files Summary

| File | Item |
|---|---|
| `packages/go/agentworkspace/overlay.go` | API-1 |
| `packages/go/agentworkspace/snapshot.go` | API-1 |
| `packages/go/agentworkspace/overlay_test.go` | API-1 |
| `packages/go/agenttask/ports.go` | API-1 |
| `packages/go/agenttask/scheduler_test.go` | API-1 |

## Dependencies and Execution Order

`06+05_config_registry` PASS 후 시작한다.

## Final Verification

```bash
go test -count=1 ./packages/go/agentworkspace ./packages/go/agentguard ./packages/go/agenttask
git diff --check
```

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
