docs: 固化受管能力覆盖隔离合同

docs/reference/spec-v01-runtime-assembly.md

@@ -189,15 +189,25 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也
 - `commitId` 是可选 pin 或历史请求 hint；提供时必须是 full commit sha，但 HWLAB gitbundle 默认不得依赖 cloud-api/CI/CD rollout 注入的 commitId。
 - `bundles[]` 每一项只允许 `{ name?, repoUrl?, ref?, commitId?, subpath, target_path }`；缺省 repo/ref/commit 继承顶层解析结果。
 - Git mirror 是基础设施能力，不是 `ResourceBundleRef` 字段。调用方只声明 GitHub `repoUrl`，runner 在物化阶段自动改写到受控 mirror read URL；event/result 必须同时记录原始 `repoUrl`、实际 `fetchRepoUrl`、`mirrorUsed` 和 `mirrorBaseUrl`，不能只显示理论 repo。请求体中显式出现 `resourceBundleRef.gitMirror` 必须 schema-invalid，避免业务 spec 控制基础设施策略。
-- `subpath` 必须留在 checkout 内，`target_path` 必须留在 runner workspace 内；runner 按 `subpath -> target_path` 复制文件或目录。
+- `subpath` 必须留在 checkout 内，`target_path` 是受管能力装配根内的逻辑相对路径。
+  runner 把能力文件装配到 primary workspace 的 `.git/agentrun-managed-overlay/`，不得覆盖 primary source tree。
 - `credentialRef` 只用于拉取私有 Git repo，不等同于 backend API KEY。
 - 不支持上传文件、对象存储 artifact、任意 ConfigMap 文件袋、inline seed 或旧字段；旧 `toolAliases`、`skillRefs`、`workspaceFiles`、`subdir`、`sparsePaths` 输入必须直接 schema-invalid。
-- `requiredSkills[]` 只接受 `{ "name": "<skill-name>" }` 这类声明式元数据；runner 只能在 gitbundle 已复制的 `.agents/skills/<name>/SKILL.md` 中校验，不接受正文、host path、SecretRef、旧 `skillRefs` 或模型默认 skill fallback。
-- 面向 HWLAB 手动调度 canary，默认 bundle 把 repo 的 `tools/` 复制到 workspace `tools/`，把 `skills/` 复制到 workspace `.agents/skills/`；event/result 必须记录 repo、requested ref/commit、实际 materialized commit、checkout tree、bundle 列表、workspace 摘要、tools、skillDirs 和 requiredSkills 摘要。
+- `requiredSkills[]` 只接受 `{ "name": "<skill-name>" }` 这类声明式元数据。
+  runner 只能在 managed overlay 的 `.agents/skills/<name>/SKILL.md` 中校验，
+  不接受正文、host path、SecretRef、旧 `skillRefs` 或模型默认 skill fallback。
+- 面向 HWLAB 手动调度 canary，默认 bundle 把 repo 的 `tools/` 和 `skills/` 映射到 managed overlay 的逻辑 `tools/` 与 `.agents/skills/`。
+  event/result 必须记录 repo、requested ref/commit、实际 materialized commit、checkout tree、bundle 列表、workspace、managed overlay、tools、skillDirs 和 requiredSkills 摘要。
 
 #### tools 目录
 
-runner 对 workspace `tools/` 做统一装配：顶层带 shebang 的脚本会被 `chmod +x`，`tools/` 会暴露到 `PATH`。如果 runtime 配置了单独的 `AGENTRUN_RESOURCE_BIN_PATH`，runner 只能在该目录写入执行原始 workspace tool 的 shim，不能复制 tool 文件导致 `dirname "$0"`、相对 import 或辅助源码解析到 bin 目录。非 shebang 文件是随 bundle 复制的源码、测试或辅助文件，不作为可执行工具发现，也不触发 schema-invalid。短命令名称来自 repo 内真实文件，例如 `tools/hwpod`，repo tool 本身承担业务 wrapper 语义。
+runner 对 managed overlay 的逻辑 `tools/` 做统一装配：
+
+- 顶层带 shebang 的脚本会被 `chmod +x`，并通过 `PATH` 暴露；
+- runtime 配置 `AGENTRUN_RESOURCE_BIN_PATH` 时，只能在该目录写入执行原始 overlay tool 的 shim；
+- 禁止复制 tool 文件到 bin 目录后改变 `dirname "$0"`、相对 import 或辅助源码解析语义；
+- 非 shebang 文件只作为 bundle 源码、测试或辅助文件，不作为可执行工具发现；
+- 短命令名称来自 repo 内真实文件，例如 `tools/hwpod`，repo tool 本身承担业务 wrapper 语义。
 
 AgentRun 自身仓库必须提供 `tools/tran`、`tools/trans` 与 `tools/apply_patch`，用于承接 UniDesk frontend `/ws/ssh` 的 scoped client-token 透传。runner 只通过 `executionPolicy.secretScope.toolCredentials[]` 投影 `UNIDESK_SSH_CLIENT_TOKEN`，并通过调用方 `transientEnv` 或 manager 受控默认值注入非敏感 `UNIDESK_MAIN_SERVER_IP`、`UNIDESK_MAIN_SERVER_HOST` 或 `UNIDESK_FRONTEND_URL`；工具不得读取 provider token、主 server SSH key 或完整 frontend 登录态。`tran --help` 必须输出 JSON，并列出当前支持的最小开发面：host/host workspace `script`、`argv`、普通 ssh-like 命令、host workspace `apply-patch`、`k3s kubectl`、`k3s script`、k3s workload `argv/script` 和 k3s workload `apply-patch`。runner 侧 `apply-patch` 只把 stdin patch 和相邻 `tools/apply_patch` helper 传到目标 route 执行，不接触或回显 Secret 值；`upload`、`download` 和 Windows route 未实现时必须显式 `unsupported-operation`，不能静默改走不受控 shell 拼接或 token fallback。
 
@@ -227,9 +237,12 @@ AgentRun 自身仓库必须提供 `tools/tran`、`tools/trans` 与 `tools/apply_
 
 #### skill 目录
 
-skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.md`。runner 发现直接子目录中的 `SKILL.md` 后，把 `.agents/skills` 暴露给 backend，并在 initial prompt 中加入有界 skill facts。多文件 skill 的 `references/`、`scripts/` 和后续新增文件跟随目录一起复制；event/result 只输出 skill name、manifest path 摘要、hash、bytes、summary 和来源 bundle 摘要，不输出大段 manifest 正文。
+skill 只来自 gitbundle managed overlay 的 `.agents/skills/<name>/SKILL.md`。
+runner 发现直接子目录中的 `SKILL.md` 后，通过 `AGENTRUN_SKILLS_DIRS` 和业务方等价环境入口暴露给 backend，并在 initial prompt 中加入真实 registry path 与有界 skill facts。
+多文件 skill 的 `references/`、`scripts/` 和后续新增文件跟随目录一起装配；event/result 只输出 skill name、manifest path 摘要、hash、bytes、summary 和来源 bundle 摘要，不输出大段 manifest 正文。
 
-若调用方声明 `requiredSkills[]`，runner 必须在 backend 启动前逐项校验 `.agents/skills/<name>/SKILL.md` 已由 gitbundle 物化。缺失时 run/command blocked，failureKind 为 `required-skill-unavailable`，blocker details 至少包含 required、missing 和 available 摘要；不得读取镜像默认 skill、host path、ConfigMap、用户长 prompt 或旧 `skillRefs` 作为替代。
+若调用方声明 `requiredSkills[]`，runner 必须在 backend 启动前逐项校验 managed overlay 的 `.agents/skills/<name>/SKILL.md` 已由 gitbundle 物化。
+缺失时 run/command blocked，failureKind 为 `required-skill-unavailable`，blocker details 至少包含 required、missing 和 available 摘要；不得读取镜像默认 skill、host path、ConfigMap、用户长 prompt 或旧 `skillRefs` 作为替代。
 
 #### 初始 prompt 与 session 边界