refactor(runtime): establish platform-aware build profiles

[innomentats]

Summary

• introduce explicit compiled runtime-driver capabilities and reject unavailable drivers before persistence or runtime side effects
• unify Darwin Docker-only and Linux full binary/image build profiles, including native artifact preflight and observable build metadata
• split the base Docker Compose topology from the KVM overlay, persist installer selection, and add deterministic deployment/image smoke contracts
• add Darwin/Linux binary CI, full-image Docker lifecycle CI, and synchronize the maintained runtime design documentation

Testing

• task lint
• CGO_ENABLED=0 ./scripts/with-go-toolchain.sh go test ./cmd/... ./pkg/... -count=1
• task test:deploy

[monkeyscan]

PR Title: refactor(runtime): establish platform-aware build ...

Commit: 8efc0f4

本次PR是一个大规模的平台构建与运行时能力边界重构，主要变更包括：

1. 运行时驱动编译边界：新增 pkg/driver/runtime_driver_compiled*.go 系列文件，通过 build tag（boxlitecgo、microsandboxcgo）将 BoxLite 和 Microsandbox 驱动变为可选编译。引入 ValidateCompiledRuntimeDriver 和 RuntimeDriverNotCompiledError，在 RPC 桥接层、Session 启动、Agent Definition 写入、Project 校验等关键路径上，确保未编译的驱动在持久化前被拒绝，并返回规范的 CodeUnimplemented / ErrUnsupported 错误。

2. Docker Daemon Pull Policy：将 applyDockerDaemonPullPolicy 从 docker_image.go 迁移到独立的 docker_native_pull_policy.go，并添加 linux && cgo && (boxlitecgo || microsandboxcgo) 构建标签，确保只有需要本地 docker daemon 作为 rootfs 来源的驱动才编译该逻辑。

3. 安装脚本原子性与 KVM 支持：deploy/install.sh 进行了重大重构，引入基于 $WORK_DIR 的候选文件预构建、原子文件提升（atomic_install_file）、失败自动回滚（restore_installation），以及通过 .installer-state.env 实现的托管镜像引用升级语义（install / set-missing / upgrade）。同时新增 docker-compose.kvm.yml overlay，安装器根据 /dev/kvm 可用性自动选择 Compose 文件组合。

4. CI 二进制矩阵：.github/workflows/ci.yml 新增 Darwin 交叉编译、Darwin 原生 smoke、Linux full 二进制构建任务，覆盖 amd64/arm64 架构，并引入 scripts/build-agent-compose-binary.sh 统一构建配置。

5. 测试覆盖：新增大量契约测试（build_info_contract_test.go、runtime_driver_compiled_boundary_test.go、install_test.sh 等），确保编译边界、Compose KVM overlay、安装器行为在 CI 中被持续验证。

整体评估：设计合理，边界清晰，安装器的原子性和回滚机制显著提升了可靠性。测试覆盖充分，CI 矩阵完整。未发现引入的高置信度安全或功能性缺陷。

[monkeyscan]

PR Title: refactor(runtime): establish platform-aware build ...

Commit: 0456981

本次变更规模较大（115文件，+7921/-485），核心目标是完善跨平台构建矩阵（Darwin/Linux × amd64/arm64）、引入运行时驱动编译边界控制、修复 Docker 守护进程镜像拉取策略漏洞，并增加 KVM 部署叠加层支持。关键改动包括：

1. 构建系统：新增 build-agent-compose-binary.sh 统一 Darwin-docker（CGO禁用）与 Linux-full（CGO启用，boxlite+microsandbox）两种构建剖面；CI 新增 binary-matrix、binary-darwin、binary-linux 等 job；Taskfile 重构 GOOS/GOARCH 变量。
2. Docker 拉取策略：新增 applyDockerDaemonPullPolicy，在 boxlite/microsandbox 通过本地 docker daemon 解析镜像前，根据 pullPolicy 强制重新拉取（always）或拒绝（never），解决此前本地缓存导致策略失效的问题。
3. 编译边界：引入 CompiledRuntimeDrivers()、IsRuntimeDriverCompiled()、ErrRuntimeDriverNotCompiled，在 API/Adapter/Project 层对未编译驱动提前返回 Unimplemented，避免落到无实现代码路径。
4. KVM 部署：新增 docker-compose.kvm.yml 叠加层，仅注入 privileged=true 与 /dev/kvm 设备映射；install.sh 增加 KVM 自动检测与 --upgrade 改进；新增大量安装脚本测试。
5. 构建元数据：version/status 接口返回 os/arch/compiled_drivers；CLI --json version 输出结构化构建信息。
6. 测试与验证：新增 E2E 镜像生命周期测试、安装脚本 bats 测试、Compose KVM 叠加契约测试、binary/image CI 契约脚本等。

整体架构设计合理，边界清晰，测试覆盖较充分。审查发现两处问题：applyDockerDaemonPullPolicy 在 never 策略下丢失原始 Docker 解析错误（功能回归），以及同一包内混用 resolveRuntimeDriver/ResolveRuntimeDriver（可维护性风险）。

[monkeyscan]

PR Title: refactor(runtime): establish platform-aware build ...

Commit: 5d7f6a3

本次 PR 将 test/e2e/image_docker_lifecycle_test.go 中的 E2E 测试从 v1 Session API 迁移到 v2 Project/Run/Sandbox API。

主要变更点：

1. 移除了 agentcomposev1 相关导入，全面使用 agentcomposev2 客户端。
2. 用 ProjectService.ApplyProject + RunService.RunAgent 替代了原来的 SessionService.CreateSession，显式定义了 ProjectSpec、AgentSpec 和 DriverSpec。
3. 用 SandboxService.StopSandbox/ResumeSandbox/GetSandbox/RemoveSandbox 替代了 v1 的 Session 生命周期操作。
4. 增加了独立的 GetSandbox 校验步骤，验证 sandbox 创建后的 driver 和运行状态。
5. RunAgent 使用 Command: "true" 配合 KEEP_RUNNING cleanup policy，保持 sandbox 运行以便后续 exec 和生命周期操作。
6. 测试末尾将 GetSession 的 not-found 校验更新为 GetSandbox。

整体评估：迁移逻辑等价且更为显式，错误处理完整，新增的 GetSandbox 验证步骤增强了状态校验的可靠性。未发现正确性、安全性或回归风险。

[monkeyscan]

PR Title: refactor(runtime): establish platform-aware build ...

Commit: 29fa858

本次变更将 ensureDockerImage 与 applyDockerDaemonPullPolicy 中重复的 never 拉取策略逻辑提取为共享辅助函数 requireLocalDockerImage，并在 docker_image_test.go 中补充了针对该辅助函数的单元测试（覆盖镜像存在、缺失、以及 inspect 错误三种分支）。

关键设计决策：

1. 统一错误处理路径：旧代码在 docker_native_pull_policy.go 的 never 分支中，若 resolveLocalDockerImageRef 返回错误，会直接落入 "not found locally" 的错误分支，导致原始 Docker daemon 错误（如通信异常）被吞掉。新实现通过 requireLocalDockerImage 优先检查并包装 resolveErr，保留了原始错误上下文。
2. 行为一致性：docker_image.go 的旧实现原本已正确处理 inspect 错误，本次重构将其与 docker_native_pull_policy.go 统一为同一辅助函数，消除重复代码并避免未来再次产生行为漂移。

总体评估：该变更是正确的缺陷修复与代码重构，测试覆盖充分，没有引入新的行为回归。

[monkeyscan]

PR Title: refactor(runtime): establish platform-aware build ...

Commit: 47fc838

本次 PR 包含 5 个文件的修改，主要做了两件事：

1. 将测试 fixture 中的驱动从 boxlite 迁移到 docker：在多个测试文件中将 RuntimeDriverBoxlite/"boxlite" 替换为 RuntimeDriverDocker/"docker"，以适配编译后的驱动并统一测试环境。

2. 补齐构造函数参数并补充 Images 依赖：

   • 在 loader_session_runner_coverage_test.go 中，为 NewLoaderSandboxRunner 调用补上了缺失的 bridge.workspaceEnsurer 参数，使其与同文件其他调用保持一致。
   • 在 project_workspace_resume_integration_test.go 中，为 ProjectWorkspaceControllerDeps 新增了 Images: projectWorkspaceImages{} 字段，并添加了对应的 projectWorkspaceImages 测试桩实现，同时引入了 images 包。

整体评估：修改机械且一致，没有发现引入行为回归、安全漏洞或数据完整性问题的迹象。构造函数参数的补齐是合理的 bugfix。

[monkeyscan]

PR Title: refactor(runtime): establish platform-aware build ...

Commit: 6af1d17

本次变更仅修改了一个 E2E 测试文件 test/e2e/docker_workspace_resume_host_daemon_test.go，去除了 RemoveProjectRequest 中不再受支持的 RemoveHistory: true 字段。根据提交信息，这是为了使用受支持的项目清理方式。变更范围极小（+1/-2），属于测试代码对上游 API 变更的适配，不存在行为回归、安全或稳定性风险。