UAT: `SandboxStrategy` enum missing `filesystem_copy` strategy — spec requires it for `fs-mount`/`fs-directory` resources #3492

New issue

Open

opened 2026-04-05 18:37:38 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 18:37:38 +00:00

Owner

Metadata

Branch: fix/sandbox-strategy-filesystem-copy
Commit Message: fix(resource): add filesystem_copy strategy to SandboxStrategy enum
Milestone: None (Backlog)
Parent Epic: #358

Background and Context

The SandboxStrategy enum in src/cleveragents/domain/models/core/resource.py is missing the filesystem_copy strategy that the specification explicitly defines as a distinct sandbox strategy for fs-mount and fs-directory resources.

Current Behavior

The SandboxStrategy enum does not include a filesystem_copy value:

# src/cleveragents/domain/models/core/resource.py
class SandboxStrategy(StrEnum):
    GIT_WORKTREE = "git_worktree"
    COPY_ON_WRITE = "copy_on_write"
    TRANSACTION_ROLLBACK = "transaction_rollback"
    SNAPSHOT = "snapshot"
    OVERLAY = "overlay"
    NONE = "none"
    # MISSING: FILESYSTEM_COPY = "filesystem_copy"

Additionally, the CopyOnWriteSandbox implementation in src/cleveragents/infrastructure/sandbox/copy_on_write.py actually implements filesystem copy semantics (using shutil.copytree), but reports "strategy": "copy_on_write" in its metadata. This conflates two distinct strategies that the spec treats separately.

Expected Behavior

The specification's "Resource Sandbox Strategy" table lists three filesystem sandbox strategies:

Strategy	Description
`copy_on_write`	Leverages the filesystem's native copy-on-write capability (e.g., BTRFS, ZFS). Only available on CoW-capable filesystems.
`filesystem_copy`	Performs an explicit full copy of the resource directory (e.g., via `cp`). Works on all writable filesystems regardless of CoW support.
`overlay`	Uses an overlay filesystem (e.g., OverlayFS) to layer changes on top of the original directory.

The spec explicitly states that fs-mount resources support copy_on_write, filesystem_copy, or overlay strategies. All three must be representable in the SandboxStrategy enum.

Impact

Users cannot configure filesystem_copy as a sandbox strategy for fs-mount or fs-directory resources
Resources on non-CoW filesystems cannot be properly sandboxed (they need filesystem_copy, not copy_on_write)
The SandboxFactory cannot route to a filesystem_copy-specific implementation

Subtasks

Add FILESYSTEM_COPY = "filesystem_copy" to the SandboxStrategy enum in src/cleveragents/domain/models/core/resource.py
Create a dedicated FilesystemCopySandbox class in src/cleveragents/infrastructure/sandbox/ implementing explicit directory copy semantics
Update SandboxFactory to route SandboxStrategy.FILESYSTEM_COPY to the new FilesystemCopySandbox implementation
Correct CopyOnWriteSandbox metadata to accurately report "strategy": "copy_on_write" only when native CoW is used (not shutil copy)
Update any resource type definitions or validators that enumerate valid strategies for fs-mount/fs-directory resources
Tests (unit): Add tests for FilesystemCopySandbox covering copy, restore, and cleanup
Tests (unit): Add tests verifying SandboxFactory correctly routes filesystem_copy strategy
Tests (Behave): Add scenario for configuring filesystem_copy strategy on an fs-mount resource
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(resource): add filesystem_copy strategy to SandboxStrategy enum), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/sandbox-strategy-filesystem-copy).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass
Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.3.0 (parent Epic #358). It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/sandbox-strategy-filesystem-copy` - **Commit Message**: `fix(resource): add filesystem_copy strategy to SandboxStrategy enum` - **Milestone**: None (Backlog) - **Parent Epic**: #358 ## Background and Context The `SandboxStrategy` enum in `src/cleveragents/domain/models/core/resource.py` is missing the `filesystem_copy` strategy that the specification explicitly defines as a distinct sandbox strategy for `fs-mount` and `fs-directory` resources. ## Current Behavior The `SandboxStrategy` enum does not include a `filesystem_copy` value: ```python # src/cleveragents/domain/models/core/resource.py class SandboxStrategy(StrEnum): GIT_WORKTREE = "git_worktree" COPY_ON_WRITE = "copy_on_write" TRANSACTION_ROLLBACK = "transaction_rollback" SNAPSHOT = "snapshot" OVERLAY = "overlay" NONE = "none" # MISSING: FILESYSTEM_COPY = "filesystem_copy" ``` Additionally, the `CopyOnWriteSandbox` implementation in `src/cleveragents/infrastructure/sandbox/copy_on_write.py` actually implements filesystem copy semantics (using `shutil.copytree`), but reports `"strategy": "copy_on_write"` in its metadata. This conflates two distinct strategies that the spec treats separately. ## Expected Behavior The specification's "Resource Sandbox Strategy" table lists three filesystem sandbox strategies: | Strategy | Description | |---|---| | `copy_on_write` | Leverages the filesystem's native copy-on-write capability (e.g., BTRFS, ZFS). Only available on CoW-capable filesystems. | | `filesystem_copy` | Performs an explicit full copy of the resource directory (e.g., via `cp`). Works on all writable filesystems regardless of CoW support. | | `overlay` | Uses an overlay filesystem (e.g., OverlayFS) to layer changes on top of the original directory. | The spec explicitly states that `fs-mount` resources support `copy_on_write`, `filesystem_copy`, or `overlay` strategies. All three must be representable in the `SandboxStrategy` enum. ## Impact - Users cannot configure `filesystem_copy` as a sandbox strategy for `fs-mount` or `fs-directory` resources - Resources on non-CoW filesystems cannot be properly sandboxed (they need `filesystem_copy`, not `copy_on_write`) - The `SandboxFactory` cannot route to a `filesystem_copy`-specific implementation ## Subtasks - [ ] Add `FILESYSTEM_COPY = "filesystem_copy"` to the `SandboxStrategy` enum in `src/cleveragents/domain/models/core/resource.py` - [ ] Create a dedicated `FilesystemCopySandbox` class in `src/cleveragents/infrastructure/sandbox/` implementing explicit directory copy semantics - [ ] Update `SandboxFactory` to route `SandboxStrategy.FILESYSTEM_COPY` to the new `FilesystemCopySandbox` implementation - [ ] Correct `CopyOnWriteSandbox` metadata to accurately report `"strategy": "copy_on_write"` only when native CoW is used (not shutil copy) - [ ] Update any resource type definitions or validators that enumerate valid strategies for `fs-mount`/`fs-directory` resources - [ ] Tests (unit): Add tests for `FilesystemCopySandbox` covering copy, restore, and cleanup - [ ] Tests (unit): Add tests verifying `SandboxFactory` correctly routes `filesystem_copy` strategy - [ ] Tests (Behave): Add scenario for configuring `filesystem_copy` strategy on an `fs-mount` resource - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(resource): add filesystem_copy strategy to SandboxStrategy enum`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/sandbox-strategy-filesystem-copy`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass - Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.3.0 (parent Epic #358). It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 18:37:53 +00:00

#358 Epic: Corrections + Subplans + Checkpoints (M4)

freemo referenced this issue

2026-04-05 18:46:37 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 18:52:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 19:05:02 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377