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

docs/reference/spec-v01-agentrun-runner.md

@@ -30,7 +30,14 @@ Runner Secret 只能通过 Kubernetes Secret projection、ServiceAccount/RBAC
 
 Kubernetes Job runner 必须把 credential source 与 runtime home 分开：Secret volume 只读挂在 `/var/run/agentrun/secrets/...`，`/home/agentrun` 由 `emptyDir` 提供可写空间，`CODEX_HOME` 指向当前 run/profile 的 writable runtime home，`AGENTRUN_CODEX_SECRET_HOME` 指向当前 `backendProfile` 对应的只读 projection。runner/backend 在启动 provider 前只复制授权文件，不打印内容。`codex`、`deepseek` 与 `minimax-m3` profile 不得共享同一个可写 runtime home，除非它们运行在不同的 per-run Kubernetes Job 且该目录由 Job 独占 emptyDir 提供。
 
-RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 `kind="gitbundle"`；runner 已支持把 `repoUrl + ref/materialized commit + bundles[]` checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录，按 `subpath -> target_path` 复制到 workspace，并记录 requested ref/commit、actual commit、tree 和 bundles 摘要。工具来自 workspace `tools/`，skill 来自 workspace `.agents/skills`，不能把用户上传文件、inline seed、旧字段或 env dump 混入 gitbundle。
+RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。
+`ResourceBundleRef` P0 收敛为 `kind="gitbundle"`：
+
+- primary repo 物化为可写、原生 Git 可见的 source workspace；
+- `bundles[]` 按逻辑 `subpath -> target_path` 装配到 `.git/agentrun-managed-overlay/`；
+- 工具和 skill 从 managed overlay 发布，不覆盖或 ignore primary source；
+- event 记录 requested ref/commit、actual commit、tree、workspace、managed overlay 和 bundles 摘要；
+- 用户上传文件、inline seed、旧字段或 env dump 不得混入 gitbundle。
 
 ### v0.1.1 Session state 持久化（per-session RWO PVC 直接挂载）
 
@@ -66,18 +73,26 @@ volumeMounts:
 
 ### ResourceBundle gitbundle 装配
 
-Runner materialize `ResourceBundleRef.kind="gitbundle"` 后必须按固定顺序处理资源：先从 repo/ref 解析并 checkout 实际 commit，再按 `bundles[]` 复制文件或目录，再准备 workspace `tools/`，再发现 `.agents/skills`，最后读取 `promptRefs` 并生成当前 command 的 assembled initial prompt 摘要。旧字段输入必须由 schema 校验直接拒绝，不得在 runner 里兼容。
+Runner materialize `ResourceBundleRef.kind="gitbundle"` 后必须按固定顺序处理资源：
+
+1. 从 repo/ref 解析并 checkout 实际 commit；
+2. 原子物化 primary source workspace；
+3. 按 `bundles[]` 把能力文件装配进 `.git/agentrun-managed-overlay/`；
+4. 从 overlay 准备 `tools/`、发现 `.agents/skills` 并校验 `requiredSkills`；
+5. 读取 `promptRefs`，生成当前 command 的 assembled initial prompt 摘要。
+
+旧字段输入必须由 schema 校验直接拒绝，不得在 runner 里兼容。
 
 gitbundle skill 聚合规则：
 
-- 聚合目录固定在 materialized workspace 下的 `.agents/skills`，每个 skill 使用稳定目录名，例如 `.agents/skills/<name>/SKILL.md`。
+- 聚合目录固定在 materialized workspace 的 `.git/agentrun-managed-overlay/.agents/skills`，每个 skill 使用稳定目录名，例如 `.agents/skills/<name>/SKILL.md`。
 - Runner 必须把该聚合目录通过环境或 backend option 暴露给 Codex runtime；对于需要兼容 Codex skill discovery 的实现，应设置 `AGENTRUN_SKILLS_DIRS` 或等价字段，并可同步设置业务方约定的 `<PROJECT>_CODE_AGENT_SKILLS_DIRS`。
-- 聚合只允许 copy `bundles[]` 指定的 Git 子树，不允许引用 `/app/skills`、host path、Secret volume 或用户上传临时目录。
+- 聚合只允许装配 `bundles[]` 指定的 Git 子树，不允许引用 `/app/skills`、host path、Secret volume 或用户上传临时目录。
 - Event/result 只输出 skill name、manifest path 摘要、hash、bytes、summary 和 target。
 
-workspace `tools/` 装配规则：
+managed overlay `tools/` 装配规则：
 
-- runner 把 workspace `tools/` 暴露到 `PATH`；如 runtime 需要稳定 bin 目录，只能安装执行原始 workspace tool 的 shim，不能复制 tool 文件导致相对路径语义改变。repo 内的短命令文件本身承担 wrapper 语义。
+- runner 把 overlay `tools/` 暴露到 `PATH`；如 runtime 需要稳定 bin 目录，只能安装执行原始 overlay tool 的 shim，不能复制 tool 文件导致相对路径语义改变。repo 内的短命令文件本身承担 wrapper 语义。
 - `tools/` 顶层 `.ts` 脚本必须带 shebang；带 shebang 的脚本会被 `chmod +x`。
 - Event/result 只输出工具文件名、hash、bytes、shebang 摘要和 count，不输出脚本文本。
 

docs/reference/spec-v01-hwlab-manual-dispatch.md

@@ -148,7 +148,9 @@ AgentRun 需要提供 durable cancel 能力，建议形态为 `POST /api/v1/runs
 
 ### P1 ResourceBundleRef / bundle materialization
 
-`ResourceBundleRef` 必须按 `kind="gitbundle"` 模型落地：输入只依赖 `repoUrl`、ref/branch 和 `bundles[]`，runner 从 git mirror/repo 解析 actual commit 后形成内容身份。runner 只能 checkout 到允许 workspace 前缀，不能覆盖 `/app`、Secret projection、profile runtime home 或 session 目录。HWLAB canary 默认只复制 `tools -> tools` 和 `skills -> .agents/skills`；用户上传文件、inline seed、对象存储 artifact 和旧字段不进入 `v0.1`。
+`ResourceBundleRef` 必须按 `kind="gitbundle"` 模型落地：输入只依赖 `repoUrl`、ref/branch 和 `bundles[]`，runner 从 git mirror/repo 解析 actual commit 后形成内容身份。
+primary repo 只能 checkout 到允许 workspace 前缀；能力 bundle 按逻辑 `tools -> tools` 和 `skills -> .agents/skills` 装配到 workspace 的 `.git/agentrun-managed-overlay/`。
+不得覆盖 primary source、`/app`、Secret projection、profile runtime home 或 session 目录；用户上传文件、inline seed、对象存储 artifact 和旧字段不进入 `v0.1`。
 
 ### P1 Resource prompt/skill assembly
 
@@ -238,6 +240,6 @@ HWLAB 旧 Code Agent 的业务 prompt 和 skill 注入必须收敛为 `gitbundle
 | cancel | 已实现最小闭环 | 已提供 run/command cancel API；pending cancel 会阻止新 runner Job，running runner 通过轮询触发 backend abort，终态写入 event、command state 和 run status。 |
 | SessionRef | 已实现最小持久化 | run 可携带 `sessionRef`，manager 保存 session/thread，runner 会按 threadId resume，result envelope 暴露脱敏 session 摘要；TTL/GC 仍按后续运维策略细化。 |
 | SessionRef | v0.1.1 已实现/已通过 HWLAB v0.2 原入口复测 | 在「metadata-only 最小持久化」基础上把 session 真实持久化：每个 session 绑 RWO PVC（`agentrun-v01-session-<sessionId>`），runner Job 把 PVC 直接挂到 `${CODEX_HOME}/<codex_rollout_subdir>`，codex app-server 自己落盘；HWLAB 原入口已验证 runner pod 删除后同 session/thread/PVC 可以恢复，仍禁止 fake 续接。 |
-| ResourceBundleRef | 已实现 `kind="gitbundle"` materialization/promptRefs/tools/skillDirs/requiredSkills 装配 | run 可携带 `repoUrl + ref/branch + bundles[]`，runner checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录并记录 requested ref/commit、actual commit/tree/workspace/bundles 摘要；`tools/` PATH、`promptRefs` thread-start 注入、`.agents/skills` 目录发现和 required skill 校验已实现；上传文件、inline seed、inline skill manifest 和对象存储不进入 v0.1。 |
+| ResourceBundleRef | 已实现 `kind="gitbundle"` materialization/promptRefs/tools/skillDirs/requiredSkills 装配 | run 可携带 `repoUrl + ref/branch + bundles[]`；runner 原子物化 primary source workspace，把能力 bundle 隔离到 `.git/agentrun-managed-overlay/`，并记录 requested ref/commit、actual commit/tree/workspace/overlay/bundles 摘要；overlay `tools/` PATH、`promptRefs` thread-start 注入、`.agents/skills` 目录发现和 required skill 校验已实现；上传文件、inline seed、inline skill manifest 和对象存储不进入 v0.1。 |
 | 同 run/runner 多 turn | 已实现最小闭环 | runner Job 在 idle timeout 内持续 poll 同一 run 的后续 command；普通 turn completed 不终结 run，bundle 只 materialize 一次，command result 按 commandId 独立聚合。 |
 | HWLAB v0.2 canary | 已实现/已通过 HWLAB v0.2 原入口复测 | HWLAB dispatcher adapter 已调 AgentRun 手动调度 API，并能转换 result/trace；MiniMax-M3 显式 session、provider profile 继承和 runner pod 删除后的同 session resume 已通过原入口 CLI 复测。 |

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 边界