feat(snapshot): finalize artifacts and direct archives

[appcypher]

TL;DR

Finalize schema-1 snapshot artifacts and add direct stopped-sandbox archive capture and archive-to-child creation without installing an intermediate snapshot directory.

Description

• represent file snapshots as an ordered layer closure with stable snapshot and layer identities, a separate descriptor digest, and mutable metadata sidecars
• read and translate released v0.6.6 through v0.6.16 snapshot layouts while retaining representable downgrade paths
• stream stopped or crashed sandbox state directly to plain tar or zstd archives, with optional pinned image closure
• create a child sandbox directly from an archive through the Rust, Python, TypeScript, and Go SDK surfaces and the CLI
• validate archive paths, limits, sparse extents, ownership bindings, transport integrity, and failure cleanup before publication
• document the finalized snapshot shape and direct archive workflows

Test Plan

• cargo fmt --all -- --check
• cargo test --locked --offline -p microsandbox-image --lib (211 passed, 4 ignored)
• cargo test --locked --offline -p microsandbox --test snapshot_artifact (43 passed)
• Live macOS ARM64/HVF matrix: tar and zstd, image included and omitted, direct capture, direct child creation, corruption rejection, and v0.6.6 compatibility
• Live Linux x86_64/KVM matrix: tar and zstd, image included and omitted, direct capture, direct child creation, and restart persistence

[greptile-apps]

Sequence Diagram

sequenceDiagram
    participant Client as CLI / SDK
    participant Builder as Snapshot or Sandbox Builder
    participant Runtime as Local Runtime
    participant Archive as Tar / Zstd Archive
    participant Child as Child Sandbox
    Client->>Builder: Capture stopped sandbox directly
    Builder->>Runtime: Validate state and assemble closure
    Runtime->>Archive: Stream descriptor, layers, and optional image
    Runtime-->>Client: Stable snapshot ID and descriptor digest
    Client->>Builder: Create child from archive
    Builder->>Runtime: Validate and stage archive
    Runtime->>Child: Materialize upper and pinned image closure
    Runtime-->>Client: Return child sandbox handle

Loading

Prompt To Fix All With AI

### Issue 1
crates/cli/lib/commands/snapshot.rs:231-239
**Archive errors leave spinner active**

When direct archive creation fails, `?` returns without clearing the active spinner, leaving stale or malformed terminal output instead of following the adjacent snapshot-creation error path.

```suggestion
    if let Some(archive_path) = args.archive.as_ref() {
        return match builder.create_archive(archive_path, args.plain_tar).await {
            Ok(archive) => {
                spinner.finish_success("Snapshotted");
                if !args.quiet {
                    println!("{}", archive.id());
                    println!("{}", archive.path().display());
                }
                Ok(())
            }
            Err(e) => {
                spinner.finish_clear();
                Err(e.into())
            }
        };
    }
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix(snapshot): harden direct archive com..." | Re-trigger Greptile}

[greptile-apps]

Archive errors leave spinner active

When direct archive creation fails, ? returns without clearing the active spinner, leaving stale or malformed terminal output instead of following the adjacent snapshot-creation error path.

Suggested change

	if let Some(archive_path) = args.archive.as_ref() {
	let archive = builder.create_archive(archive_path, args.plain_tar).await?;
	spinner.finish_success("Snapshotted");
	if !args.quiet {
	println!("{}", archive.id());
	println!("{}", archive.path().display());
	}
	return Ok(());
	}
	if let Some(archive_path) = args.archive.as_ref() {
	return match builder.create_archive(archive_path, args.plain_tar).await {
	Ok(archive) => {
	spinner.finish_success("Snapshotted");
	if !args.quiet {
	println!("{}", archive.id());
	println!("{}", archive.path().display());
	}
	Ok(())
	}
	Err(e) => {
	spinner.finish_clear();
	Err(e.into())
	}
	};
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: crates/cli/lib/commands/snapshot.rs
Line: 231-239

Comment:
**Archive errors leave spinner active**

When direct archive creation fails, `?` returns without clearing the active spinner, leaving stale or malformed terminal output instead of following the adjacent snapshot-creation error path.

```suggestion
    if let Some(archive_path) = args.archive.as_ref() {
        return match builder.create_archive(archive_path, args.plain_tar).await {
            Ok(archive) => {
                spinner.finish_success("Snapshotted");
                if !args.quiet {
                    println!("{}", archive.id());
                    println!("{}", archive.path().display());
                }
                Ok(())
            }
            Err(e) => {
                spinner.finish_clear();
                Err(e.into())
            }
        };
    }
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.