Bug: SAM CLI Finch Detection Fails on Linux with Rootless Containerd

AWS SAM CLI versions 1.151.0 and 1.154.0 fail to detect Finch on Ubuntu Linux (arm64) when using rootless containerd, despite Finch being properly installed and functional. The error message is:

```
Error: Running AWS SAM projects locally requires a container runtime. Do you have Docker or Finch installed and running?
```

## Environment

- **OS**: Ubuntu 24.04.3 LTS
- **Architecture**: aarch64 (ARM64)
- **SAM CLI Version**: 1.151.0 and 1.154.0 (both tested)
- **Finch Version**: v1.14.1
- **Finch Installation Method**: Ubuntu apt repository (`runfinch-finch` package)
- **Containerd**: Rootless mode with nerdctl backend
- **Python**: 3.11.10

## Finch Configuration

Finch is installed via the official Ubuntu apt repository and configured with rootless containerd:

```bash
# Finch installation
curl -fsSL https://artifact.runfinch.com/deb/GPG_KEY.pub | sudo gpg --dearmor -o /usr/share/keyrings/runfinch-finch-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/runfinch-finch-archive-keyring.gpg arch=$(dpkg --print-architecture)] https://artifact.runfinch.com/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/runfinch-finch.list
apt-get update
apt-get install -y runfinch-finch containerd

# Rootless containerd setup
loginctl enable-linger participant
mkdir -p /run/user/$(id -u participant)
export XDG_RUNTIME_DIR=/run/user/$(id -u)
containerd-rootless-setuptool.sh install
```

## Finch Works Correctly

Finch itself is fully functional:

```bash
$ finch --version
finch version v1.14.1

$ finch info
Client:
Namespace: finch
Debug Mode: false
Server:
Server Version: 1.7.28
Storage Driver: overlayfs
Logging Driver: json-file
Cgroup Driver: systemd
Cgroup Version: 2
...

$ finch ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6fa08d27c593 docker.io/amazon/dynamodb-local:latest "java -jar DynamoDBL…" 51 seconds ago Up 0.0.0.0:8000->8000/tcp hotel-app-dynamodb-local
```

## SAM CLI Detection Behavior

### Debug Output from SAM CLI 1.151.0

```
2026-02-12 20:03:08,098 | ContainerClientFactory.create_client() called
2026-02-12 20:03:08,098 | Admin preference: None
2026-02-12 20:03:08,099 | Using auto-detected client creation
2026-02-12 20:03:08,099 | Trying Docker client creation
2026-02-12 20:03:08,099 | Creating Docker container client from environment variable.
2026-02-12 20:03:08,100 | Creating container client with parameters: {'version': '1.35'}
2026-02-12 20:03:08,100 | DockerContainerClient created successfully
2026-02-12 20:03:08,101 | Fall back docker api version to 1.44: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2026-02-12 20:03:08,103 | Docker daemon availability check failed with fallback: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2026-02-12 20:03:08,103 | Docker client not created, trying creating Finch client.
2026-02-12 20:03:08,103 | Creating Finch container client with base_url=unix:///var/run/finch.sock
2026-02-12 20:03:08,104 | Creating container client with parameters: {'base_url': 'unix:///var/run/finch.sock', 'version': '1.35'}
2026-02-12 20:03:08,104 | FinchContainerClient created successfully
2026-02-12 20:03:08,105 | Finch daemon availability check failed: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
2026-02-12 20:03:08,106 | No container runtime available
```

### Analysis

SAM CLI is looking for Finch at `unix:///var/run/finch.sock`, but on Linux with rootless containerd, the socket is at:
- `$XDG_RUNTIME_DIR/containerd/containerd.sock` (typically `/run/user/1001/containerd/containerd.sock`)

Additionally, the containerd socket uses a different API protocol than Docker's socket, so even when pointed to the correct location, SAM CLI's Docker Python library cannot communicate with it.

## Workarounds Attempted (All Failed)

### 1. Environment Variables
```bash
export XDG_RUNTIME_DIR=/run/user/$(id -u)
export AWS_SAM_CONTAINER_RUNTIME=finch
```
**Result**: No effect on detection

### 2. SAM CLI Metadata File
```bash
mkdir -p ~/.aws-sam
cat > ~/.aws-sam/metadata.json < Starting with AWS SAM CLI version 1.145.0, AWS SAM CLI supports Finch as an alternative container runtime to Docker.
>
> After you install Finch, the AWS SAM CLI automatically detects and uses Finch as a container runtime when Docker does not run.

SAM CLI should:
1. Detect that Finch is installed and available via the `finch` command
2. Use Finch's CLI interface instead of trying to connect to a socket
3. Fall back to using the `finch` command when socket detection fails

## Root Cause

The SAM CLI Finch detection logic appears to be designed primarily for macOS, where Finch uses a VM with a Docker-compatible socket. On Linux:

1. Finch uses nerdctl + rootless containerd directly (no VM)
2. The containerd socket location is user-specific (`$XDG_RUNTIME_DIR/containerd/containerd.sock`)
3. The containerd socket uses a different API than Docker's socket
4. SAM CLI should fall back to using the `finch` CLI command, but this fallback never triggers

## Proposed Solution

SAM CLI should:

1. **Check for `finch` command availability** before attempting socket connections
2. **Use CLI-based container operations** when the `finch` command is available, similar to how it would use the `docker` command
3. **Support `$XDG_RUNTIME_DIR`** for socket detection on Linux
4. **Provide a `--container-runtime` flag** to explicitly specify finch/docker (currently doesn't exist in 1.151.0 or 1.154.0)
5. **Honor the `AWS_SAM_CONTAINER_RUNTIME` environment variable** more reliably

## Workaround for Users

Currently, the only reliable workaround is to install Docker, which defeats the purpose of using Finch.

## Additional Context

- This issue affects workshop and tutorial environments where Docker cannot be installed
- Finch on Linux is officially supported as of October 2024
- The issue exists in both SAM CLI 1.151.0 and 1.154.0
- The `--container-runtime` flag mentioned in some documentation does not exist in these versions

## Related Issues

- #4584 - Original feature request for Finch support
- AWS Documentation: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-finch.html