feat: add code agent sandbox skeleton

docs/reference/code-agent-sandbox.md

@@ -0,0 +1,34 @@
+# Code Agent Sandbox
+
+Code Agent Sandbox 是独立于 Code Queue 的沙箱微服务骨架。它负责统一记录 Codex/OpenCode/未来 agent 的运行态、适配器契约、状态恢复边界和凭证语义边界。
+
+## Boundary
+
+- Code Agent Sandbox 不依赖 Code Queue 作为前置条件。
+- Code Queue 只在后续契约接入时读取这里定义的状态机和 adapter 语义。
+- 不承诺 live migration；只承诺任务状态可恢复、未开始任务可重调度、中断 attempt 可 retry/resume、结果不丢。
+
+## Runtime Modes
+
+- `full-isolation`：允许 sandbox 管理自己的 `config.toml`、`auth.json`、环境变量和 token provider 切换。
+- `half-isolation`：允许读取/写入边界由配置显式控制，适合本机调试和受限挂载。
+- `bridge`：只读宿主现状，不改写宿主配置，不切换 token provider。
+
+## Adapter Contract
+
+Sandbox 以 adapter 一等抽象统一下面的动作：
+
+- `start`
+- `attach`
+- `prompt`
+- `steer`
+- `interrupt`
+- `resume`
+- `fork`
+- `trace`
+- `terminal status`
+- `artifact summary`
+
+## Diagnostics
+
+`/health`、`/diagnostics`、`/trace` 和 `/logs` 是首批只读入口。它们用于验证模式、适配器状态、恢复边界和凭证边界，不承诺连接真实 Code Queue。

docs/reference/microservices.md

@@ -90,6 +90,16 @@ OA Event Flow 在 UniDesk 语境中按共享控制面基础设施管理：不得
 - 路由：CLI/WebUI 仍只访问 `/api/microservices/code-queue/proxy/...`；backend-core 在内部把控制/读取路径转到 `code-queue-mgr`，把 active run、judge、dev-container、执行面健康和 scheduler 相关路径转到 D601 执行面。
 - 行为兼容：提交与 queued prompt edit 必须保留 Code Queue 环境提示注入、`--reference-task-id`/引用输入解析和引用任务上下文注入，避免 master 控制面路径与 D601 原写服务语义分叉。
 
+### Code Agent Sandbox On Main Server
+
+`code-agent-sandbox` 是主 server Compose 内的独立 Code Agent Sandbox 骨架，登记为 `deployment.mode=internal-sidecar`，Provider 为 `main-server`，后端地址为 Compose 网络内 `http://code-agent-sandbox:4260`。它目前不依赖 Code Queue，也不承担 queue 产品逻辑。
+
+- 职责：统一 adapter 契约、模式边界、凭证边界、状态恢复表达和只读诊断入口。
+- 代理路径：允许 `/health`、`/diagnostics`、`/trace`、`/logs` 和 `/api/` 前缀；允许方法为 `GET`、`HEAD`、`POST`、`PUT`。
+- 模式：`full-isolation`、`half-isolation`、`bridge` 三种模式都必须在 health/diagnostics 中可见，bridge 模式只读宿主现状，不改写宿主配置。
+- 适配器契约：`start`、`attach`、`prompt`、`steer`、`interrupt`、`resume`、`fork`、`trace`、`terminal status` 和 `artifact summary` 统一由 adapter 层暴露。
+- 恢复边界：服务只承诺状态可恢复、未开始任务可重调度、中断 attempt 可 retry/resume、结果不丢，不承诺 live migration。
+
 ### Project Manager On Main Server
 
 当前 Project Manager 作为 `id=project-manager` 的用户服务登记在 `config.json`：