Harden coding A2A workspace bootstrap

docs/CODING_A2A_AGENT_CREATE_AND_INVOKE.md

@@ -292,6 +292,8 @@ GET /.well-known/agent.json
 - `X-Agent-Access-Token` 负责“谁有权访问这个 agent”
 - A2A body 里的 `api_key` 负责“本次请求用谁的模型额度”
 - 两者职责分离，不互相替代
+- 未绑定代码仓库时，runtime 会自动创建空的 `workspace.root_dir`，不再因为远端缺少 `/workspace` 而直接崩溃
+- 绑定 git 资源时，runtime 会先自动准备工作区；如果 clone / branch / repo 本身失败，会返回结构化 JSON-RPC error，而不是直接冒成 uvicorn 500
 
 ### 7.1 同步调用
 

docs/HEICODE_TEMPLATE_AGENT_RUNTIME_CONTRACT.md

@@ -265,3 +265,33 @@ X-Agent-Access-Token == AGENT_ACCESS_TOKEN
 2. 排障时再看 `GET /agents/{agent_name}/status`。
 3. 客户端直连前，先确认 HM 已拿到 `subdomain` 和 `access_token`。
 4. 若模板 Agent 对外公网暴露，建议始终注入 `AGENT_ACCESS_TOKEN`，不要依赖兼容放行。
+
+## 8. 运行时健壮性说明
+
+当前 `coding_a2a_agent` 已补充以下健壮性行为：
+
+- 未绑定 git 资源时，如果远端工作区目录不存在，runtime 会先创建空的 `workspace.root_dir`
+- 绑定 git 资源时，runtime 会在真正执行任务前自动准备工作区
+- 如果 git clone、目标目录状态或分支切换失败，`POST /message/send` 会返回结构化 JSON-RPC error，而不是直接返回 uvicorn 500
+
+典型错误形态：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req-1",
+  "error": {
+    "code": -32010,
+    "message": "git workspace preparation failed",
+    "data": {
+      "code": "git_prepare_failed",
+      "stage": "git_prepare_workspace",
+      "repo_url": "https://example.com/acme/demo.git",
+      "branch": "main",
+      "workspace_root": "/workspace",
+      "returncode": 128,
+      "stderr": "fatal: repository not found"
+    }
+  }
+}
+```