remo-cli 2.0.0rc2__tar.gz → 2.0.0rc4__tar.gz

{remo_cli-2.0.0rc2 → remo_cli-2.0.0rc4}/.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
     "name": "Python Agentic Development",
-    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
     "remoteUser": "vscode",
     "features": {
         "ghcr.io/devcontainers/features/python:1": {},

{remo_cli-2.0.0rc2 → remo_cli-2.0.0rc4}/.github/workflows/smoke-test.yml

@@ -139,9 +139,55 @@ jobs:
           echo "$OUT" | grep -q "EBS volume:"  || { echo "FAIL: missing EBS volume"; exit 1; }
           echo "aws info: PASS"
 
+      - name: Snapshot — create (async kickoff)
+        run: |
+          SNAP=ci-smoke-aws
+          echo "SNAP_NAME=$SNAP" >> "$GITHUB_ENV"
+          OUT=$(uv run remo aws snapshot create "$INSTANCE_NAME" --name "$SNAP" --description "smoke test")
+          echo "$OUT"
+          echo "$OUT" | grep -q "creation started" || { echo "FAIL: missing async-create hint"; exit 1; }
+          echo "$OUT" | grep -q "several minutes" || { echo "FAIL: missing duration hint"; exit 1; }
+          echo "aws snapshot create: PASS"
+
+      - name: Snapshot — list shows pending then available
+        run: |
+          # Initial list: pending (or already available if AWS is fast today)
+          uv run remo aws snapshot list "$INSTANCE_NAME" | tee /tmp/list-1.txt
+          grep -q "$SNAP_NAME" /tmp/list-1.txt || { echo "FAIL: snapshot missing from initial list"; exit 1; }
+          grep -q "STATUS" /tmp/list-1.txt || { echo "FAIL: AWS list missing STATUS column"; exit 1; }
+
+          # Poll up to 10 minutes for the snapshot to reach available state
+          for attempt in $(seq 1 60); do
+            OUT=$(uv run remo aws snapshot list "$INSTANCE_NAME")
+            if echo "$OUT" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" >/dev/null; then
+              echo "Snapshot $SNAP_NAME is available (attempt $attempt)"
+              break
+            fi
+            echo "Attempt $attempt: not yet available; sleeping 10s..."
+            sleep 10
+          done
+          uv run remo aws snapshot list "$INSTANCE_NAME" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" \
+            || { echo "FAIL: snapshot did not reach available within 10 min"; exit 1; }
+          echo "aws snapshot list: PASS"
+
+      - name: Snapshot — delete
+        run: |
+          uv run remo aws snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes
+          # Verify it's gone from list
+          OUT=$(uv run remo aws snapshot list "$INSTANCE_NAME")
+          if echo "$OUT" | grep -q "$SNAP_NAME"; then
+            echo "FAIL: snapshot still present after delete"; exit 1
+          fi
+          echo "aws snapshot delete: PASS"
+
       - name: Teardown
         if: always()
         run: |
+          # Best-effort cleanup of any leftover smoke snapshots (in case of
+          # mid-step failure) before tearing down the instance.
+          if [ -n "${SNAP_NAME:-}" ]; then
+            uv run remo aws snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes 2>/dev/null || true
+          fi
           uv run remo aws destroy --name "$INSTANCE_NAME" --yes --remove-storage || true
 
   # ===========================================================================
@@ -217,9 +263,51 @@ jobs:
           echo "$OUT" | grep -q "Volume:"      || { echo "FAIL: missing Volume"; exit 1; }
           echo "hetzner info: PASS"
 
+      - name: Snapshot — create (async kickoff)
+        run: |
+          SNAP=ci-smoke-hetzner
+          echo "SNAP_NAME=$SNAP" >> "$GITHUB_ENV"
+          OUT=$(uv run remo hetzner snapshot create "$INSTANCE_NAME" --name "$SNAP" --description "smoke test")
+          echo "$OUT"
+          echo "$OUT" | grep -q "creation started" || { echo "FAIL: missing async-create hint"; exit 1; }
+          echo "$OUT" | grep -q "several minutes" || { echo "FAIL: missing duration hint"; exit 1; }
+          echo "hetzner snapshot create: PASS"
+
+      - name: Snapshot — list shows pending then available
+        run: |
+          uv run remo hetzner snapshot list "$INSTANCE_NAME" | tee /tmp/list-1.txt
+          grep -q "$SNAP_NAME" /tmp/list-1.txt || { echo "FAIL: snapshot missing from initial list"; exit 1; }
+          grep -q "STATUS" /tmp/list-1.txt || { echo "FAIL: Hetzner list missing STATUS column"; exit 1; }
+
+          # Poll up to 5 minutes for the snapshot to become available
+          for attempt in $(seq 1 30); do
+            OUT=$(uv run remo hetzner snapshot list "$INSTANCE_NAME")
+            if echo "$OUT" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" >/dev/null; then
+              echo "Snapshot $SNAP_NAME is available (attempt $attempt)"
+              break
+            fi
+            echo "Attempt $attempt: not yet available; sleeping 10s..."
+            sleep 10
+          done
+          uv run remo hetzner snapshot list "$INSTANCE_NAME" | grep -E "^\s*$INSTANCE_NAME\s+$SNAP_NAME\s.*\savailable" \
+            || { echo "FAIL: snapshot did not reach available within 5 min"; exit 1; }
+          echo "hetzner snapshot list: PASS"
+
+      - name: Snapshot — delete
+        run: |
+          uv run remo hetzner snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes
+          OUT=$(uv run remo hetzner snapshot list "$INSTANCE_NAME")
+          if echo "$OUT" | grep -q "$SNAP_NAME"; then
+            echo "FAIL: snapshot still present after delete"; exit 1
+          fi
+          echo "hetzner snapshot delete: PASS"
+
       - name: Teardown
         if: always()
         run: |
+          if [ -n "${SNAP_NAME:-}" ]; then
+            uv run remo hetzner snapshot delete "$INSTANCE_NAME" "$SNAP_NAME" --yes 2>/dev/null || true
+          fi
           uv run remo hetzner destroy --name "$INSTANCE_NAME" --yes --remove-volume || true
 
   # ===========================================================================
@@ -365,6 +453,93 @@ jobs:
           verify_tools
           echo "Post-update dev tools verification: PASS"
 
+      - name: Snapshot — create
+        run: |
+          SNAP=ci-smoke-incus
+          echo "SNAP_NAME=$SNAP" >> "$GITHUB_ENV"
+          OUT=$(sg incus-admin -c "uv run remo incus snapshot create $CONTAINER_NAME --name $SNAP --description 'smoke test'")
+          echo "$OUT"
+          echo "$OUT" | grep -q "Created snapshot '$SNAP'" || { echo "FAIL: missing sync-create success message"; exit 1; }
+          echo "incus snapshot create: PASS"
+
+      - name: Snapshot — list shows the new snapshot
+        run: |
+          OUT=$(sg incus-admin -c "uv run remo incus snapshot list $CONTAINER_NAME")
+          echo "$OUT"
+          echo "$OUT" | grep -q "$SNAP_NAME" || { echo "FAIL: snapshot missing from list"; exit 1; }
+          # Incus list MUST NOT have a STATUS column (always AVAILABLE)
+          if echo "$OUT" | head -1 | grep -q "STATUS"; then
+            echo "FAIL: Incus list should not have a STATUS column"; exit 1
+          fi
+          echo "incus snapshot list: PASS"
+
+      - name: Snapshot — restore round-trip
+        run: |
+          SSH_CMD="ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+            -o ConnectTimeout=30 -o BatchMode=yes -i ~/.ssh/id_rsa remo@$HOST"
+
+          # Plant a marker file inside the container AFTER the snapshot was
+          # taken. If restore works, this marker must be gone afterwards.
+          $SSH_CMD "echo post-snapshot > /tmp/should-be-gone-after-restore.txt"
+          $SSH_CMD "test -f /tmp/should-be-gone-after-restore.txt"
+          echo "Marker file planted post-snapshot."
+
+          # Restore. -y to bypass the confirm. The provider stops the
+          # container, restores, and starts it again.
+          sg incus-admin -c "uv run remo incus snapshot restore $CONTAINER_NAME $SNAP_NAME -y"
+
+          # Container may take a few seconds to come back online after start.
+          for attempt in $(seq 1 12); do
+            if $SSH_CMD "echo connection-ok" 2>/dev/null | grep -q "connection-ok"; then
+              echo "SSH back after restore (attempt $attempt)"
+              break
+            fi
+            sleep 5
+          done
+
+          # The post-snapshot marker MUST be gone (SC-001).
+          if $SSH_CMD "test -f /tmp/should-be-gone-after-restore.txt" 2>/dev/null; then
+            echo "FAIL: marker file still present after restore — rollback didn't happen"
+            exit 1
+          fi
+          echo "Post-restore: marker file is gone — rollback PASS"
+          echo "incus snapshot restore: PASS"
+
+      - name: Snapshot — delete
+        run: |
+          sg incus-admin -c "uv run remo incus snapshot delete $CONTAINER_NAME $SNAP_NAME -y"
+          OUT=$(sg incus-admin -c "uv run remo incus snapshot list $CONTAINER_NAME")
+          if echo "$OUT" | grep -q "$SNAP_NAME"; then
+            echo "FAIL: snapshot still present after delete"
+            echo "$OUT"
+            exit 1
+          fi
+          echo "incus snapshot delete: PASS"
+
+      - name: Snapshot — destroy-time cleanup prompt
+        run: |
+          # Create two snapshots, then destroy with -y. The destroy-time prompt
+          # is bypassed by -y, defaulting to KEEP snapshots (safer default).
+          # The destroy output must mention the snapshots and the keep-warning.
+          # We re-create the container after so the rest of the suite (cp tests)
+          # has a clean target.
+          sg incus-admin -c "uv run remo incus snapshot create $CONTAINER_NAME --name keep-1"
+          sg incus-admin -c "uv run remo incus snapshot create $CONTAINER_NAME --name keep-2"
+
+          # Capture destroy output to verify the prompt path fires
+          OUT=$(sg incus-admin -c "uv run remo incus destroy --name $CONTAINER_NAME --yes" 2>&1 || true)
+          echo "$OUT"
+          echo "$OUT" | grep -q "has 2 snapshot" || { echo "FAIL: destroy did not mention snapshots"; exit 1; }
+          echo "$OUT" | grep -q "keeping the 2 snapshot" || { echo "FAIL: destroy did not print --yes keep warning"; exit 1; }
+          echo "incus destroy snapshot-prompt: PASS"
+
+          # Re-create the container for downstream steps (cp tests etc.)
+          sg incus-admin -c "uv run remo incus create --name $CONTAINER_NAME"
+          # Refresh $HOST since the container was rebuilt
+          HOST=$(sudo incus list $CONTAINER_NAME --format=json | \
+            python3 -c "import sys,json; d=json.load(sys.stdin)[0]['state']['network']['eth0']['addresses']; print([a['address'] for a in d if a['family']=='inet'][0])")
+          echo "HOST=$HOST" >> "$GITHUB_ENV"
+
       - name: Prepare for remo cp tests
         run: |
           # Make container name resolvable (remo stores name, not IP, for Incus)

{remo_cli-2.0.0rc2 → remo_cli-2.0.0rc4}/CLAUDE.md

@@ -11,6 +11,7 @@ See `.specify/memory/constitution.md` for project principles and non-negotiable
 - N/A (Incus storage pools already configured by 001-bootstrap-incus-host) (002-incus-container-support)
 - Python 3.11+ + Click (CLI framework), InquirerPy (interactive picker), boto3 (AWS, optional), hcloud (Hetzner, optional) (003-python-cli-rewrite)
 - Flat file (`~/.config/remo/known_hosts`, colon-delimited) (003-python-cli-rewrite)
+- Cross-provider snapshot model (`models/snapshot.py`) + shared helpers in `core/snapshot.py` (name generator, validator, table formatter, destroy-time cleanup hook). No new runtime deps. (005-provider-snapshots)
 
 - Ansible 2.14+ / YAML + `ansible.builtin`, `community.general` (for zypper module) (001-bootstrap-incus-host)
 
@@ -131,10 +132,10 @@ Provider SDKs (boto3, hcloud) are lazy-imported with clear error messages if mis
 - Ansible 2.14+ / YAML: Follow standard conventions plus Constitution principles
 
 ## Recent Changes
+- 005-provider-snapshots: Added cross-provider snapshot CLI (`remo <P> snapshot {create,list,restore,delete}`) + destroy-time cleanup hook across Incus / Proxmox / AWS / Hetzner.
 - 003-python-cli-rewrite: Added Python 3.11+ + Click (CLI framework), InquirerPy (interactive picker), boto3 (AWS, optional), hcloud (Hetzner, optional)
 - 002-incus-container-support: Added Ansible 2.14+ / YAML + `ansible.builtin`, `community.general` (existing), Incus CLI (local)
 
-- 001-bootstrap-incus-host: Added Ansible 2.14+ / YAML + `ansible.builtin`, `community.general` (for zypper module)
 
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

{remo_cli-2.0.0rc2 → remo_cli-2.0.0rc4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remo-cli
-Version: 2.0.0rc2
+Version: 2.0.0rc4
 Summary: Remote development environment CLI
 License-Expression: MIT
 License-File: LICENSE
@@ -160,6 +160,34 @@ Every remo environment includes:
 
 ---
 
+## Snapshots
+
+Capture a point-in-time copy of an instance before a risky change, then roll
+back if it breaks. Available on every provider, with the same command surface:
+
+```bash
+remo <provider> snapshot create <instance> [--name NAME] [--description TEXT]
+remo <provider> snapshot list    [INSTANCE]
+remo <provider> snapshot restore <instance> <snapshot> [-y]
+remo <provider> snapshot delete  <instance> <snapshot> [-y]
+```
+
+`--name` defaults to `remo-YYYYMMDD-HHMMSS`. `-y` / `--yes` bypasses the
+confirm prompt on destructive operations.
+
+| Provider | Create | Restore | Notes |
+|---|---|---|---|
+| **Incus**   | seconds | in-place rollback (container stopped briefly) | Free; uses native `incus snapshot`. |
+| **Proxmox** | seconds | in-place rollback (container stopped briefly) | Free; requires snapshot-capable rootfs storage (ZFS, LVM-thin, Btrfs, Ceph, NFS, CIFS). `dir` storage is rejected pre-flight. |
+| **AWS**     | async — several minutes | in-place EBS volume swap; stops the instance, swaps the root volume, restarts. Typically 2-5 min downtime. | Costs $ per GB-month in EBS. Pre-restore root volume is preserved as a tagged orphan — delete it manually once you've verified the restore. |
+| **Hetzner** | async — several minutes | server rebuild from the snapshot image, in-place. Typically 1-2 min downtime. | Costs € per GB-month. |
+
+`remo` does not estimate storage cost — check your provider's billing console.
+
+The `destroy` command on each provider checks for existing snapshots first and
+offers to clean them up. Decline and the snapshots remain (you'll be warned
+they continue to incur storage costs on AWS/Hetzner).
+
 ## CLI Reference
 
 ```bash
@@ -223,6 +251,15 @@ remo proxmox update --name <n> --volume-size 40 --cores 4 --memory 4096
 remo proxmox destroy --name <n> [--yes] [--purge]   # Destroy container
 remo proxmox bootstrap --host <node>  # Verify node + download LXC template
 
+# Snapshots (all four providers)
+remo <provider> snapshot create <instance>                       # Auto-named
+remo <provider> snapshot create <instance> --name pre-x --description "before upgrade"
+remo <provider> snapshot list                                    # All instances
+remo <provider> snapshot list <instance>                         # One instance
+remo <provider> snapshot restore <instance> <snap-name> [-y]     # In-place rollback
+remo <provider> snapshot delete <instance> <snap-name> [-y]      # Remove
+# `<provider> destroy` will list existing snapshots and offer to clean them up first.
+
 # Updates
 uv tool upgrade remo-cli            # Update CLI to latest version
 remo <platform> update              # Update dev tools on remote

{remo_cli-2.0.0rc2 → remo_cli-2.0.0rc4}/README.md

@@ -141,6 +141,34 @@ Every remo environment includes:
 
 ---
 
+## Snapshots
+
+Capture a point-in-time copy of an instance before a risky change, then roll
+back if it breaks. Available on every provider, with the same command surface:
+
+```bash
+remo <provider> snapshot create <instance> [--name NAME] [--description TEXT]
+remo <provider> snapshot list    [INSTANCE]
+remo <provider> snapshot restore <instance> <snapshot> [-y]
+remo <provider> snapshot delete  <instance> <snapshot> [-y]
+```
+
+`--name` defaults to `remo-YYYYMMDD-HHMMSS`. `-y` / `--yes` bypasses the
+confirm prompt on destructive operations.
+
+| Provider | Create | Restore | Notes |
+|---|---|---|---|
+| **Incus**   | seconds | in-place rollback (container stopped briefly) | Free; uses native `incus snapshot`. |
+| **Proxmox** | seconds | in-place rollback (container stopped briefly) | Free; requires snapshot-capable rootfs storage (ZFS, LVM-thin, Btrfs, Ceph, NFS, CIFS). `dir` storage is rejected pre-flight. |
+| **AWS**     | async — several minutes | in-place EBS volume swap; stops the instance, swaps the root volume, restarts. Typically 2-5 min downtime. | Costs $ per GB-month in EBS. Pre-restore root volume is preserved as a tagged orphan — delete it manually once you've verified the restore. |
+| **Hetzner** | async — several minutes | server rebuild from the snapshot image, in-place. Typically 1-2 min downtime. | Costs € per GB-month. |
+
+`remo` does not estimate storage cost — check your provider's billing console.
+
+The `destroy` command on each provider checks for existing snapshots first and
+offers to clean them up. Decline and the snapshots remain (you'll be warned
+they continue to incur storage costs on AWS/Hetzner).
+
 ## CLI Reference
 
 ```bash
@@ -204,6 +232,15 @@ remo proxmox update --name <n> --volume-size 40 --cores 4 --memory 4096
 remo proxmox destroy --name <n> [--yes] [--purge]   # Destroy container
 remo proxmox bootstrap --host <node>  # Verify node + download LXC template
 
+# Snapshots (all four providers)
+remo <provider> snapshot create <instance>                       # Auto-named
+remo <provider> snapshot create <instance> --name pre-x --description "before upgrade"
+remo <provider> snapshot list                                    # All instances
+remo <provider> snapshot list <instance>                         # One instance
+remo <provider> snapshot restore <instance> <snap-name> [-y]     # In-place rollback
+remo <provider> snapshot delete <instance> <snap-name> [-y]      # Remove
+# `<provider> destroy` will list existing snapshots and offer to clean them up first.
+
 # Updates
 uv tool upgrade remo-cli            # Update CLI to latest version
 remo <platform> update              # Update dev tools on remote

{remo_cli-2.0.0rc2 → remo_cli-2.0.0rc4}/docs/aws.md

@@ -85,6 +85,14 @@ remo aws destroy --yes
 
 # Destroy instance AND EBS (removes all data)
 remo aws destroy --yes --remove-storage
+
+# Snapshots
+remo aws snapshot create <instance>                 # Auto-named (remo-YYYYMMDD-HHMMSS)
+remo aws snapshot create <instance> --name pre-x --description "before upgrade"
+remo aws snapshot list <instance>                   # Single instance
+remo aws snapshot list                              # All registered AWS instances
+remo aws snapshot restore <instance> <snap-name> [-y]   # In-place EBS volume swap
+remo aws snapshot delete <instance> <snap-name> [-y]    # Remove snapshot
 ```
 
 ### Create Options
@@ -129,6 +137,25 @@ Available tools: `docker`, `user_setup`, `nodejs`, `devcontainers`, `github_cli`
 |--------|-------------|
 | `--name <name>` | Resource namespace (default: `$USER`) |
 
+### Snapshot Options
+
+| Option | Applies to | Description |
+|--------|------------|-------------|
+| `--name <snap>` | `create` | Snapshot name. Defaults to `remo-YYYYMMDD-HHMMSS`. Validated client-side: 1–40 chars, `^[A-Za-z0-9][A-Za-z0-9_-]*$`. |
+| `--description <text>` | `create` | Free-text description stored on the EBS snapshot and shown in `list`. |
+| `--region <region>` | all | AWS region. Defaults to the registered instance's region. |
+| `--yes`, `-y` | `restore`, `delete` | Bypass the confirmation prompt. |
+
+### Snapshot Behavior
+
+* **Create is asynchronous.** The command returns within a few seconds with a "creation started; will take several minutes" hint. Use `snapshot list` to watch the `STATUS` column transition from `pending` to `available`. Restore and delete refuse to operate on pending snapshots.
+* **Restore is an in-place volume swap.** The instance is stopped, the root EBS volume is detached, a new volume is created from the snapshot, attached as root, and the instance is restarted. Typical downtime: 2-5 minutes.
+* **Restored volume preserves current size.** If you grew the EBS volume after taking the snapshot, the restored volume is created at the current (larger) size. The filesystem inside stays at the snapshot's recorded size until you run `sudo resize2fs $(findmnt -no SOURCE /)` inside the instance — `remo` prints this hint on restore.
+* **Pre-restore volume is preserved as an orphan.** After a successful restore, the pre-restore root volume is *not* deleted; it stays in the AZ tagged `remo-restore-orphan=<ISO-8601-timestamp>` as a safety net. Once you've verified the restore is healthy, delete it manually with `aws ec2 delete-volume --volume-id <id>`. `remo` prints the exact command on restore.
+* **Snapshots are scoped by volume ID.** Snapshots are listed by filtering on the *current* root volume ID, so if you destroy an instance and create a new one with the same name, the old snapshots will not appear in `list` (they become orphans, invisible to `remo`, manageable only via the AWS console).
+* **No cost estimation.** `remo` does not estimate monthly EBS snapshot storage cost — check your AWS billing console.
+* **Destroy-time cleanup.** `remo aws destroy` lists existing snapshots and offers to delete them as part of teardown. Declining (or passing `-y`) keeps the snapshots, which will continue to incur storage cost.
+
 ## Features
 
 | Feature | Description |
@@ -180,6 +207,89 @@ df -h /home/remo
 
 All instances use SSM Session Manager — no inbound ports are opened.
 
+### IAM Permissions
+
+The principal `remo` uses (your local IAM user, SSO session, or assumed role) needs the following EC2 actions. If you scoped your `remo` policy tightly, you'll see `UnauthorizedOperation` errors the first time you try a subcommand whose actions aren't in your policy.
+
+| Subcommand | Required EC2 actions |
+|---|---|
+| `create` | `RunInstances`, `DescribeInstances`, `DescribeImages`, `DescribeVolumes`, `CreateTags`, `CreateVolume`, `DescribeSecurityGroups`, `CreateSecurityGroup`, `AuthorizeSecurityGroupIngress`, `CreateKeyPair`, `ImportKeyPair`, `DescribeKeyPairs`, `RunInstances`, `iam:PassRole`, `iam:GetRole`, `iam:CreateRole`, `iam:AttachRolePolicy`, `iam:GetInstanceProfile`, `iam:CreateInstanceProfile`, `iam:AddRoleToInstanceProfile` |
+| `destroy` | `DescribeInstances`, `TerminateInstances`, `DescribeVolumes`, `DeleteVolume`, `DescribeSecurityGroups`, `DeleteSecurityGroup`, `DescribeKeyPairs`, `DeleteKeyPair`, plus the IAM cleanup mirror of `create` |
+| `update`, `info`, `list`, `sync` | `DescribeInstances`, `DescribeVolumes` (+ `ModifyVolume` and `DescribeVolumesModifications` for `update --volume-size`) |
+| `stop`, `start`, `reboot` | `DescribeInstances`, `StopInstances` / `StartInstances` / `RebootInstances` |
+| `snapshot create` | `DescribeInstances`, `DescribeVolumes`, `DescribeSnapshots`, `CreateSnapshot`, `CreateTags` |
+| `snapshot list` | `DescribeInstances`, `DescribeVolumes`, `DescribeSnapshots` |
+| `snapshot delete` | `DescribeInstances`, `DescribeVolumes`, `DescribeSnapshots`, `DeleteSnapshot` |
+| `snapshot restore` | Everything in `snapshot list` **plus** `StopInstances`, `DetachVolume`, `CreateVolume`, `AttachVolume`, `StartInstances`, `CreateTags` |
+| `destroy` (with existing snapshots, `-y` declined cleanup) | Adds `DescribeSnapshots` (to enumerate) and `DeleteSnapshot` (if cleanup accepted) on top of the regular `destroy` set |
+
+> **Two AWS constraints to know.** First: `Describe*` actions can't be ARN- or tag-scoped — `Resource: "*"` is the only allowed form (read-side metadata leaks broader than mutation does). Second: snapshot ARNs are auto-generated (`snap-xxxxxx`) at create time, so prefix-on-the-ARN scoping doesn't help. Tag-based scoping is the practical path.
+
+#### Snapshot-only policy with tag-locked mutations (attach as an inline policy to your `remo` role)
+
+This is the recommended minimum. Reads stay broad (AWS limitation); mutations are locked to resources tagged `remo=true`, which is exactly what `remo` creates and never touches what it doesn't own.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "CreateSnapshotRequiresRemoTag",
+      "Effect": "Allow",
+      "Action": "ec2:CreateSnapshot",
+      "Resource": "arn:aws:ec2:*:*:snapshot/*",
+      "Condition": {
+        "StringEquals": {"aws:RequestTag/remo": "true"}
+      }
+    },
+    {
+      "Sid": "CreateSnapshotFromAnyVolume",
+      "Effect": "Allow",
+      "Action": "ec2:CreateSnapshot",
+      "Resource": "arn:aws:ec2:*:*:volume/*"
+    },
+    {
+      "Sid": "TagSnapshotOnCreate",
+      "Effect": "Allow",
+      "Action": "ec2:CreateTags",
+      "Resource": "arn:aws:ec2:*:*:snapshot/*",
+      "Condition": {
+        "StringEquals": {"ec2:CreateAction": "CreateSnapshot"}
+      }
+    },
+    {
+      "Sid": "DeleteOnlyRemoSnapshots",
+      "Effect": "Allow",
+      "Action": "ec2:DeleteSnapshot",
+      "Resource": "arn:aws:ec2:*:*:snapshot/*",
+      "Condition": {
+        "StringEquals": {"ec2:ResourceTag/remo": "true"}
+      }
+    },
+    {
+      "Sid": "DescribeSnapshotsUnscopable",
+      "Effect": "Allow",
+      "Action": "ec2:DescribeSnapshots",
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+What each `Sid` enforces:
+
+| Sid | Enforces |
+|---|---|
+| `CreateSnapshotRequiresRemoTag` | The CreateSnapshot call must include `remo=true` in `TagSpecifications` (`remo` always does this). |
+| `CreateSnapshotFromAnyVolume` | Companion — `CreateSnapshot` evaluates against both source-volume and new-snapshot ARNs; both have to be allowed. |
+| `TagSnapshotOnCreate` | `CreateTags` is only allowed as part of a `CreateSnapshot` request — prevents the role from re-tagging arbitrary resources. |
+| `DeleteOnlyRemoSnapshots` | Can only delete snapshots tagged `remo=true`. Manual snapshots someone took via the console with no tag stay safe. |
+| `DescribeSnapshotsUnscopable` | Unavoidable — AWS doesn't allow Describe* scoping; this lets `list` work. |
+
+For `snapshot restore`, also add `ec2:StopInstances`, `ec2:DetachVolume`, `ec2:CreateVolume`, `ec2:AttachVolume`, `ec2:StartInstances`. Those can be tag-scoped on the instance / volume too — e.g., `Condition: {"StringLike": {"ec2:ResourceTag/Name": "remo-*"}}` to constrain to `remo`-named instances.
+
+If you want a looser starting point and don't need the tag-locking (e.g., you fully trust who can assume the role), `Resource: "*"` on `ec2:CreateSnapshot`, `ec2:DescribeSnapshots`, `ec2:DeleteSnapshot`, `ec2:CreateTags` is a one-statement minimal version.
+
 ### What's Created
 
 | Resource | Name Pattern | Description |

{remo_cli-2.0.0rc2 → remo_cli-2.0.0rc4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "remo-cli"
-version = "2.0.0rc2"
+version = "2.0.0rc4"
 description = "Remote development environment CLI"
 readme = "README.md"
 license = "MIT"

remo_cli-2.0.0rc4/specs/005-provider-snapshots/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Provider Snapshots
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-24
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+- The spec mentions provider names (Incus, Proxmox, AWS, Hetzner) and provider-specific concepts (EBS, hcloud, pct, `--vmstate`, `dir` storage). These are kept because they describe the *user-facing scope* of the feature (which backends are covered) and the *user-visible behavioral differences* (latency, cost, downtime), not implementation choices. They are not framework or library references.
+- Cost numbers and rate-per-GB figures are intentionally left as "estimated" with a 10% tolerance in SC-003, so the spec doesn't pin a specific provider price that will drift over time.