Sandbox Trail lane execution with managed Colima/Lima

[forhappy]

Summary

• provision pinned Colima, Lima, and Docker CLI tools during explicit setup on supported macOS hosts, so users do not need a separate Colima/Homebrew/Docker Desktop install
• add a compatibility-default host and optional colima managed-execution backend for lane exec, tests, evals, and agent-driven commands
• project a deterministic bounded lane view into an execution-scoped Lima guest namespace without host mounts, execute direct argv, validate/export candidate state, and import only source changes before Trail checkpointing
• add durable, cooperative cancellation through Rust, CLI, HTTP/OpenAPI, and MCP, terminating only the recorded guest process group and acknowledging success only after owned namespace cleanup
• preserve typed lifecycle, sandbox, checkpoint, cleanup, session/turn/trace, validation-failure, infrastructure-failure, cancellation, and recovery evidence

Main use cases and agent workflow

• let an AI agent run repository tests, formatters, generators, builds, and other potentially untrusted project commands behind a VM boundary
• run readiness test/eval gates through the same guest data plane used by agent commands
• connect commands to lane-private services inside the same Colima VM without exposing the Docker socket or host paths
• preserve validated source results while keeping generated/dependency/scratch output disposable
• cancel a stuck or unwanted command from another CLI process, HTTP request, or Trail MCP session without stopping the VM or unrelated guest processes
• retain projection, command, checkpoint, cleanup, session, turn, trace, and cancellation evidence for review, handoff, and crash recovery

The agent/provider process and Trail database remain the contained host control plane; managed commands are the Colima guest data plane. The PR does not claim arbitrary agent binaries execute inside the VM.

Usage

trail env runtime setup colima --execution-backend colima
trail lane exec <LANE> --timeout-secs 900 -- cargo test
trail lane exec <LANE> --turn <OPEN_TURN_ID> -- cargo test

# From another process while the command is active:
trail lane exec-cancel <LANE> [--execution-id exec_...]

trail config set runtime.execution_backend host

HTTP exposes POST /v1/lanes/{lane}/exec and /exec/cancel. MCP exposes trail.lane_exec and trail.lane_exec_cancel; because one stdio connection is ordered, cancel a blocking MCP call through a second Trail MCP session or CLI/HTTP client. Existing workspaces remain on host execution.

Security and lifecycle

• no host mounts, SSH-agent forwarding, generated host SSH config, bridged address, Kubernetes, Docker socket, real Git state, .trail, home directory, or ambient credentials in the guest
• explicit verified limactl, isolated Colima/Lima/Docker state, and direct user argv without shell interpolation
• bounded duration, stdout/stderr, projection/archive/file/entry sizes, diagnostics, manifests, cancellation waits, and concurrent executions
• atomic admission fence prevents concurrent callers from bypassing the four-execution workspace limit
• normalized contained paths, case-collision detection, portable mode/symlink validation, private/secret/ignored path exclusion, and concurrent-host-edit rejection
• cancellation uses a durable request, exact process-group receipt, TERM/KILL of only the negative group ID, pre-import fencing, terminal receipt, and bounded cleanup
• source-only import followed by normal Trail checkpoint and managed disposal/unmount lifecycle
• ownership-checked recovery without stopping or deleting the Colima profile; ambiguous import/checkpoint states fail closed
• distinct machine outcomes: EXECUTION_CANCELLED (CLI 17 / HTTP 409), EXECUTION_VALIDATION_FAILED (CLI 18 / HTTP 422), and EXECUTION_INFRASTRUCTURE_FAILED (CLI 19 / HTTP 503)

Colima owns and downloads its guest image. Trail provisions the pinned CLI toolchain, not a VM image. File-secret OCI mounts remain unsupported until a VM-safe broker exists.

Validation

• openspec validate integrate-colima-runtime --strict
• cargo fmt --all -- --check
• CARGO_TARGET_DIR=/Volumes/Workspace/crabbuild-target/trail-main cargo check --workspace --locked
• CARGO_TARGET_DIR=/Volumes/Workspace/crabbuild-target/trail-main cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
• all 966 Trail library tests exercised; 961 passed and four existing ignored tests in the broad run, with the one load-sensitive schema timing test passing on exact rerun
• all integration binaries exercised through the broad run plus explicit continuation after fixture correction
• Colima runtime: 7/7; guest execution unit suite: 17/17; managed execution: 7/7; e2e: 232/232
• changed-path ledger: activation 9/9, producer inventory 24/24, recovery 30/30, macOS native 11/11, plus API/commands/daemon/Git/materialized/reconcile/view suites
• lane environment inheritance 2/2; initialization 18/18; initialization faults 28/28; retirement 10/10; schema v1 18/18; terminal output guard 1/1
• ACP capture timing test passed on exact clean-load rerun; conformance, faults, interoperability, transport, transform, session, turn, update, and workspace-mapping suites passed

The broad workspace commands initially hit two pre-existing wall-clock budgets while the host was under unrelated Rust compilation load. Both timing tests passed on isolated reruns; the rest of the suite was rerun with those two omitted and then continued explicitly after a reviewed mutation-inventory fixture correction.

Post-qualification socket-fix verification

• cargo fmt --all -- --check, workspace cargo check --locked, and all-target/all-feature Clippy with -D warnings passed
• the targeted macOS socket-path regression and all 7 Colima runtime integration tests passed
• the full Trail library run passed 963 tests with four existing ignored tests
• the latest full-workspace baseline reached one reproducible unrelated e2e failure in environment_resolve_cli_executes_and_reuses_a_real_cargo_snapshot: its offline cargo generate-lockfile subprocess exited 101; the exact test rerun reproduced it, while the Colima, library, check, and Clippy gates above remained green

Real-host Colima and Claude Code qualification (2026-08-13)

• ran the PR binary on macOS arm64 against a disposable clone of claw-code at commit d621f5d5d858b30de12234c424e5f657a59e021e
• configured a dedicated workspace profile with provider=colima, execution_backend=colima, and containment receipt trail_no_host_mounts_v1
• discovered and fixed a real macOS startup defect: the original Application Support LIMA_HOME produced a 123-byte SSH socket path above macOS's 104-byte AF_UNIX limit; Lima state now uses private ~/.trail-lima/ with regression coverage
• launched three Claude Code 2.1.177 agents into independent NFS copy-on-write Trail lanes, each based on the same immutable source root and each changing one disjoint Rust crate
• preserved the intended split: Claude ran in the macOS host control plane under sandbox-exec; test commands ran in isolated Linux/aarch64 Colima guest namespaces with no host mounts
• projected 2,101 repository entries (about 35.7 MB) per execution; the guest initially had no Rust or C toolchain, proving host tools and credentials were not inherited
• installed pinned Rust/Cargo 1.89 inside the dedicated qualification VM, then recorded one passing lane test gate per lane using cargo test --workspace --locked followed by a real CLI run
• commands lane: four added tests passed; dump-manifests printed 131 commands, 31 tools, and 12 bootstrap phases
• tools lane: four added unit tests and three doctests passed; dump-manifests ran successfully
• runtime lane: five added unit tests and one doctest passed; bootstrap-plan ran successfully
• all three lanes report ready=true, clean workdirs, no blockers, and exact one-file changed-path sets; the only readiness warning is that no separate eval gate was requested
• initial failed toolchain-path gate attempts remain visible in Trail history, followed by successful retries; a concurrent third gate hit the bounded schema/WAL retry guard and succeeded when retried sequentially
• the source checkout in /Users/haipingfu/Github remained unchanged; all qualification state stayed in the disposable workspace and Trail-owned Colima profile

Trail provisions Colima/Lima/Docker tooling, but it intentionally does not provision a project language toolchain. Repositories should declare or bootstrap the Rust/Node/Python toolchain they require inside the guest data plane.

Branch audit

• Install focused Trail skills across major coding agents #28 has merged and this five-commit Colima series is now rebased directly onto main
• the pre- and post-rebase diffs have the same stable patch ID (68d12e87691e5311bd9c2ad2c012199e7693765c)
• the reviewed scope remains exactly 66 files, 7,164 additions, and 113 deletions
• every OpenSpec task in sections 1 through 11 is checked complete; no tracked working-tree changes are omitted
• unrelated untracked local files remain excluded from the branch