feat: dockerCompose() sandbox provider (#471)

[OdinIversen]

Closes #471.

Adds a dockerCompose() sandbox provider that delegates container
configuration to a user-managed docker-compose.yml. Sandcastle invokes
docker compose run -d against a service (default agent) and injects
only the per-run worktree bind mount, workdir, and env vars. Image,
networks, GPU reservations, resource limits, and dependent services live
in the compose file — meaning every Docker option is reachable today
without sandcastle adding a flag for each.

import { dockerCompose } from "@ai-hero/sandcastle/sandboxes/docker-compose";

await run({
  agent: claudeCode("claude-opus-4-6"),
  sandbox: dockerCompose({ composeFile: ".sandcastle/docker-compose.yml" }),
  prompt: "...",
});

Notes for review

• --deps not passed. The issue body suggested docker compose run --deps …; in compose v2 dependent services run by default and only --no-deps opts out, so the flag is omitted.
• serviceName shipped. The issue listed an explicit service-name option as a "natural follow-up". Including it now keeps the API symmetric with docker() and avoids a follow-up release; happy to drop if you'd rather defer.
• projectName shipped as the lower-level primitive. The issue's isolateDeps: true follow-up can be built on top of this. Per-session isolation itself is left for that follow-up.
• No UID pre-flight. Compose users own UID via build args, so the docker provider's pre-flight check is intentionally skipped.
• Compose file path verified at construction. Misconfiguration fails fast, before a worktree is created.

Tests

• src/DockerComposeLifecycle.test.ts (13 tests) covers the docker-compose CLI shape: argv layout, -v mounts (incl. Windows drive-letter colons), :ro suffix, -f/-p/--project-directory/--workdir/-e flags, no --user, pre-existing-container guard, best-effort cleanup.
• src/sandboxes/docker-compose.test.ts (18 tests) covers dockerCompose(): provider tag/name, mount validation, compose-file existence check, worktree volume, default workdir, serviceName override, projectName/projectDirectory/composeFile propagation, copyFileIn/copyFileOut.
• npm run typecheck and npm run build both green.
• End-to-end smoke run against a real compose file with NVIDIA GPU reservation: docker compose run -d started a real container, nvidia-smi -L from handle.exec() listed the host GPU inside the container, workdir and close() cleanup behaved as expected.

Out of scope (per issue)

• sandcastle init scaffolding for a starter compose file
• dockerCompose({ isolateDeps: true }) per-session project isolation

Changeset attached.

[vercel]

Someone is attempting to deploy a commit to the Matt Pocock's projects Team on Vercel.

A member of the Team first needs to authorize it.