feat: add Boat (boat.dev) remote execution environment provider

[zozo123]

Summary

Adds a Boat (boat.dev) remote execution-environment provider on top of mecatl's existing placement / durable EnvironmentRef seam, in internal/adapter/boatenv.

• provisions a fresh sandbox for the deployment-default placement and reattaches the exact persisted sandbox by opaque ID
• keeps model/provider/GitHub/SSH account secrets out of guests by forcing noEnv: true on every create and resume
• binds Workspace and CommandRunner to the same sandbox namespace and exposes the server affinity proof
• implements the full versioned Workspace + WorkspaceNamespace contract and passes both shared fsconformance tables (30/30, offline and live)
• implements tool.AuthorityResourceResolver, so authority-bound sessions can use the file tools
• implements the side-effect-free server.PlacementValidator, so daemon startup never provisions a billable sandbox
• preserves the no-FS attenuation without provisioning remote compute
• uses a non-secret configuration fingerprint as EnvironmentRef.Revision; the API credential never enters refs, logs, metadata, or source

Naming

The vendor formerly known as Ascii Box now ships as boat.dev. This PR targets the current API (https://boat.dev/api/v1, the /sandboxes resource family); the old ascii.dev/api/box/v1 endpoint sunsets 2026-10-31. EnvironmentKind is "boat".

How it matches the sibling backends

The adapter is held to osfs's behavior, not just the interface:

• Glob runs doublestar.GlobWalk with osfs's exact options (WithNoFollow, symlink leaves dropped, leading / and ./ stripped). It walks a guest listing that never follows symlinks and is fetched in one round trip, bounded to the pattern's depth.
• Grep compiles with Go's regexp (RE2, the syntax the tool advertises). It translates the parsed pattern into an equivalent Python pattern, with every class and case fold expanded to explicit ranges, and runs it next to the files. Lines split on \n, binary files are skipped, and osfs's budgets and 201-match cap apply.
• Symlinks: Remove/Rename act on the link itself, ReadDir uses lstat and reports fs.ModeSymlink, and a write through an escaping link returns ErrPathEscape.
• CAS: a guest-side lock plus SHA-256 versions. A zero FileVersion is never a wildcard. New files are published atomically.

These are tested against an osfs workspace on the same directory, so osfs itself is the oracle.

Composition, and coordination with #1614

The adapter is composed through the real app.Build with app.Config.PlacementProvider set to the Boat provider, and driven by scripted sessions (offline and live). That surfaced three composition gaps:

1. Startup preflight provisioned a sandbox. This PR adds server.PlacementValidator with the same name, signature and call site as feat: draft native Kubernetes execution provider #1614, so the two merge cleanly whichever lands first. Boat implements it as one GET /me. A non-sentinel validator error keeps its cause and is classified as ErrPlacementUnavailable.
2. Authority-bound file tools were denied. Fixed by AuthorityResourceResolver (above), resolved in the guest under the same confinement as file access.
3. Shell needs a local workspace and shell even when the placement supplies the runner. feat: draft native Kubernetes execution provider #1614's RemoteExecution posture (runner != nil || remote) removes that gate, and this PR does not duplicate it. Until feat: draft native Kubernetes execution provider #1614 lands, the Shell composition test switches Shell on with a throwaway host workspace and asserts nothing is written there.

This PR adds no operator flag or config grammar while #580 and #1614 settle that surface.

Lifecycle and limits (measured against boat.dev)

Fact (live)	How the adapter handles it
A command string over ~128 KiB fails with E2BIG	File content never rides the command line. Large requests are staged through the files API.
Files API writes are capped at 5 MiB per call	Staging is chunked.
Command stdout is capped at 8 MiB, with stdoutTruncated set	Large helper output spills to a guest snapshot fetched in ranges. Truncation is reported, never passed off as complete.
timeoutSeconds runs 1–600; a 75s command is honored	The limit follows the caller's deadline. There is no client-wide HTTP timeout.
A signal-killed command returns exitCode: null plus a signal	Reported as exit −1, with the signal named.
A missing cwd is rejected	A non-default Workdir is created on first use.
PATCH ttlSeconds re-arms archival relative to now	Close schedules archival after a 5-minute grace instead of archiving at once, so the run that follows CreateSession finds the sandbox warm. Readiness re-arms the full TTL.

Reattach costs one GET. The resume, if needed, happens on the first operation. A 409 from a command, or from a concurrent resume, is retried once after readiness, and the command never runs twice. Redirects are refused, so the bearer credential is never replayed. The helper runs as python3 -I, so workspace files cannot shadow its imports.

Tests

The offline fake enforces the live limits above (argv size, files-API size, missing cwd, stream caps, signals, timeouts, 409). An adapter that only works against a lenient fake fails here first. Coverage:

• both fsconformance tables
• osfs parity for Glob and Grep (13 glob and 20 grep patterns on one tree) and for symlink semantics
• 300 KiB and 6 MiB round trips
• timeout derivation, signal mapping, redirect refusal, error-envelope reasons
• lazy reattach, a sandbox archived behind the adapter's back, and a concurrent resume race
• app.Build composition
• the server PlacementValidator seam

The regression tests were mutation-checked: reintroducing any of four original defects fails them.

go test passes for ./internal/adapter/boatenv/, ./internal/adapter/server/..., ./internal/app/..., ./cmd/mecated/, ./cmd/mecak8s/ and ./docs/lint. -race passes on the changed packages, the pinned golangci-lint v2.13.1 reports 0 issues, and matlatl check --strict is clean. The cloud-native inventory (ADR 0027, List 1) gains row 76 for the provider's client, handles and guest staging.

Live verification

Opt-in, under the repo's e2e build tag and driven only by BOAT_API_KEY:

BOAT_API_KEY=... go test -tags e2e ./internal/adapter/boatenv/ -run TestLive -v -timeout 45m

Run against boat.dev on 2026-09-23:

Test	Covers	Result
TestLiveBoat	create → versioned write/read → stale-CAS rejection → replace → grep → Shell/Workspace agreement → archive → exact reattach with the filesystem intact. Plus a 70s command under a 150s deadline, a signal-kill, a 6 MiB round trip, Remove on a symlink, a brace glob, a POSIX-class grep, and stale-revision rejection	PASS, 107.6s
TestLiveBoatConformance	both shared conformance tables on one sandbox, one directory per case	30/30 PASS, 31.6s
TestLiveBoatComposition	real app.Build: GET /me preflight, exactly one sandbox, authority-checked Write/Edit/Grep/Read plus Shell, nothing on the host	PASS, 4.2s

Observed lifecycle: provisioning -> idle -> archiving -> archived -> provisioned -> ready.

🤖 Generated with Claude Code

[jhrozek]

@zozo123 thanks for the PR! I think this is exciting in the sense that the PR does show how the harness can be decoupled from the execution environment.

I'm not familiar with Box but checking the wiring with mecatl I think this is missing a builder composition (something like boxenv.New?) to be testable? Also, check out PR #1614 that adds a native k8s execution environment - I would suggest to coordinate e.g. internal/adapter/executioncontroller/podexec.go is a good place to look there for inspiration.

Thanks again for the contribution! Feel free to jump on Discord or GH discussions if you want to discuss anything!

[zozo123]

@jhrozek to answer your question on #1604: this is the current PR. I've closed #1604; #1598 and #1603 were already closed.

New since your review (6a22253): the vendor rebranded from Ascii Box to boat.dev, so the adapter now lives at internal/adapter/boatenv and uses EnvironmentKind "boat". It targets the current API at https://boat.dev/api/v1, where the resource is /sandboxes. The old ascii.dev/api/box/v1 endpoint shuts down on 2026-10-31.

On the live API, the opt-in contract smoke TestLiveBoat passes in 84.7s. It creates a sandbox, archives it, reattaches the exact same sandbox and checks the file is still there. It also confirms that a stale version is rejected on write and that a stale revision is rejected on reattach. The offline suite and the pinned golangci-lint v2.13.1 both pass locally.

Your builder-composition point and lining this up with the k8s environment in #1614 (podexec.go) are next. I'll follow up here.

🤖 Generated with Claude Code

[zozo123]

@jhrozek following up on your two points (d4c006b):

Builder composition. The adapter is now composed through the real app.Build, with app.Config.PlacementProvider set to the Boat provider, and driven by scripted sessions (internal/adapter/boatenv/composition_test.go, plus a live variant). Composing it end to end found three gaps that the library-level tests missed:

1. Startup preflight bound the default placement, so every daemon start provisioned and archived a billable sandbox.
2. Authority-bound file tools were denied because the workspace couldn't derive a resource identity.
3. Shell only appears when the deployment has a local workspace and shell.

Coordinating with #1614.

• For (1) I took feat: draft native Kubernetes execution provider #1614's server.PlacementValidator seam with the same name, signature and call site, so whichever PR lands first, the other rebases cleanly. Boat implements it as a single GET /me.
• (3) is exactly what feat: draft native Kubernetes execution provider #1614's RemoteExecution posture fixes (runner != nil || remote), so I did not duplicate it here. Until feat: draft native Kubernetes execution provider #1614 lands, the Shell test switches Shell on with a throwaway host workspace and asserts nothing is written there.
• Once feat: draft native Kubernetes execution provider #1614 lands, a Boat deployment should just set RemoteExecution: true.

The workspace now also passes the shared fsconformance tables, 30/30 live. That caught a real contract bug: a zero-version ReplaceFile on a missing path returned a version mismatch instead of fs.ErrNotExist. It's fixed.

All three live suites pass against boat.dev; the numbers are in the updated description.

🤖 Generated with Claude Code

[zozo123]

Update (c7f3a0a): before asking for review, I ran an adversarial review of this PR and fixed what it found. Each fix has a regression test, and the tests were mutation-checked.

• Shell timeouts now follow the caller's deadline (Boat allows 1–600s). There was a hard 60s cap plus a 70s HTTP client timeout.
• A signal-killed command reports exit −1 and names the signal. It used to decode Boat's exitCode: null as exit 0.
• Large files: content no longer goes on the command line. The live API rejects any command string over about 128 KiB, so writes are staged through the files API and large reads are paged. 6 MiB round trips pass live.
• osfs parity: Glob uses doublestar with osfs's exact options. Grep compiles RE2 and translates it faithfully, instead of passing the pattern to Python re. Symlink Remove/Rename/ReadDir follow osfs. These are tested against an osfs workspace on the same directory.
• Lifecycle: Reattach is a single GET and readiness happens lazily. A non-default Workdir is now created. Close sets a 5-minute grace TTL instead of archiving immediately, so a new session's first run finds its sandbox warm. The live app.Build composition went from 46.8s to 4.2s.

Live against boat.dev: TestLiveBoat, TestLiveBoatConformance (30/30) and TestLiveBoatComposition all pass. They now build under the repo's e2e tag.

CI: pull-request workflows on this PR are still waiting for approval because it comes from a fork. The same workflows ran on my fork at this exact commit: CI run, with 29 jobs passing and 1 skipped (race partitions, lint, analysis, docs, domain model, api-compat and vuln all green). Deslop also passed. Details are in the updated description.

🤖 Generated with Claude Code

[JAORMX]

Hey! Thanks a lot for pushing this. I'm working on refining the definitions for execution environments. I'll get to this tomorrow and hopefully it'll be in better shape then. Super excited to see this!