fix: add aipod imageRef work-ready runner reuse

2026-06-11 01:21:56 +08:00
parent 59272f8edb
commit 5a6e5a4bbd
22 changed files with 598 additions and 32 deletions
@@ -1,13 +1,13 @@
 # v0.1 AipodSpec 规格

-`AipodSpec` 是 AgentRun `v0.1` 的声明式 agent 装配规格。它把已有的 `backendProfile`、`executionPolicy.secretScope`、`ResourceBundleRef.kind="gitbundle"`、Queue task 和 Session turn 装配入口集中到 YAML 文件中，避免把某个 agent 的模型、SecretRef、gitbundle、skill 或 tool 写死在 manager、runner 或 CLI 源码里。
+`AipodSpec` 是 AgentRun `v0.1` 的声明式 agent 装配规格。它把已有的 `imageRef`、`backendProfile`、`executionPolicy.secretScope`、`ResourceBundleRef.kind="gitbundle"`、Queue task 和 Session turn 装配入口集中到 YAML 文件中，避免把某个 agent 的 work-ready env image、模型、SecretRef、gitbundle、skill 或 tool 写死在 manager、runner 或 CLI 源码里。

 ## 设计边界

 - `AipodSpec` 只声明装配意图，不保存 API key、SSH private key、token、`auth.json`、`config.toml` 或其他 Secret 明文。
 - manager 通过 `/api/v1/aipod-specs` 对 YAML 做增删改查；默认目录为仓库 `config/aipods/`，可用 `AGENTRUN_AIPOD_SPEC_DIR` 覆盖。
 - CLI 通过 `aipod-specs list|show|render|apply|delete` 管理规格，通过 `queue submit --aipod <name>` 或 `sessions turn --aipod <name>` 使用规格。
- `render` 只把规格展开为标准 Queue task / Session turn 输入，输出必须脱敏，只显示 SecretRef 名称、key、projection、gitbundle 摘要和 `valuesPrinted=false`。
+- `render` 只把规格展开为标准 Queue task / Session turn 输入，输出必须脱敏，只显示 imageRef source 摘要、SecretRef 名称、key、projection、gitbundle 摘要和 `valuesPrinted=false`。
 - `AipodSpec` 不引入第二套 scheduler、runner、backend adapter 或 Code Queue；最终执行仍走 AgentRun Queue、Sessions、runner Job 和 Codex app-server stdio backend。

 ## YAML 结构
@@ -20,6 +20,11 @@ kind: AipodSpec
 metadata:
  name: Artificer
 spec:
+  imageRef:
+    kind: env-image-dockerfile
+    repoUrl: git@github.com:pikasTech/agentrun.git
+    commitId: 0000000000000000000000000000000000000000
+    dockerfilePath: deploy/container/Containerfile
  backendProfile: sub2api
  executionPolicy:
    sandbox: workspace-write
@@ -46,17 +51,42 @@ spec:

 - `apiVersion` 固定为 `agentrun.pikastech.local/v0.1`，`kind` 固定为 `AipodSpec`。
 - `metadata.name` 是 CLI/API 查找名，允许大小写，但文件落盘名会归一为安全 YAML 文件名。
+- `spec.imageRef` 描述该 Aipod 的 work-ready env image 来源。`kind` 固定为 `env-image-dockerfile`，最小字段为 `repoUrl`、完整 40 位 `commitId` 和仓库内相对 `dockerfilePath`；不得用可变 image tag 代替 source 引用。
 - `spec.backendProfile` 使用 AgentRun 已注册或动态的 Codex-compatible profile slug，例如 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 或 `sub2api`。
 - `spec.model.model` 会展开为 command payload 的 `model` 字段；完整 `spec.model` 同时进入 `payload.modelConfig`，用于保留 `reasoningEffort` 等声明但不作为 Secret 输出。
 - `spec.executionPolicy` 复用 run 的执行策略校验，且必须恰好包含一个匹配 `backendProfile` 的 provider credential SecretRef。
 - `spec.resourceBundleRef` 复用 RuntimeAssembly 的 gitbundle 规则，可为 `null`，但需要注入 skill/tool 时必须使用 gitbundle。
 - `spec.payloadDefaults` 与 CLI render 输入合并；用户 prompt 通过 `--prompt`、`--prompt-file` 或 `--prompt-stdin` 覆盖或补充。

+## imageRef 与 env image reuse
+
+`imageRef` 是 Aipod work-ready 环境的声明式 source，不是最终 Kubernetes image 字符串。它回答“这个 Aipod 的基础执行镜像由哪个 Git commit 中的哪个 Dockerfile/Containerfile 构建”。
+
+最小结构：
+
+```yaml
+imageRef:
+  kind: env-image-dockerfile
+  repoUrl: git@github.com:pikasTech/agentrun.git
+  commitId: 0000000000000000000000000000000000000000
+  dockerfilePath: deploy/container/Containerfile
+```
+
+规则：
+
+- `repoUrl` 必须是无明文 credential 的 Git URL；credential 只能通过受控 Git/mirror 运行面获取。
+- `commitId` 必须是完整 commit SHA，不能是 branch、tag、short SHA 或 dispatcher 当前 rollout hint。
+- `dockerfilePath` 必须是 repo 内相对路径，不能包含 `..`，不能是绝对路径。
+- Aipod 启动或 Queue dispatch 时必须先按 `imageRef` 解析 env image identity，并优先查询 artifact catalog / registry 复用已有 digest-pinned env image。
+- catalog/registry 未命中时只允许进入受控 CI/CD 构建路径；普通 Aipod 启动不得在任务内部临时 `apt`、`apk`、`bun install`、`npm install` 或等价命令补基础环境。
+- runner job 最终只接受解析后的 digest-pinned image；response、event 和 result 必须输出 `imageRef` source、env identity、reuse/build 状态和 digest 摘要，不输出 Secret。
+
 ## Artificer 默认规格

 仓库内置 `config/aipods/artificer.yaml`，名称为 `Artificer`。它的长期目标是承接 UniDesk 分布式开发任务：

 - 使用 `backendProfile=sub2api`，模型声明为 `gpt-5.5`，reasoning effort 为 `xhigh`。
+- 通过 `imageRef` 引用 AgentRun `v0.1` env image Dockerfile source；启动时必须复用已物化的 digest-pinned env image，不能把依赖安装留给任务运行时。
 - 通过 provider SecretRef `agentrun-v01-provider-sub2api` 获取 `auth.json` 与 `config.toml`。
 - 通过 `toolCredentials` 获取 GitHub Issue/PR 写入 token：`agentrun-v01-tool-github-pr` -> env `GH_TOKEN`。
 - 通过 `toolCredentials` 获取 UniDesk SSH 透传 token：`agentrun-v01-tool-unidesk-ssh` -> env `UNIDESK_SSH_CLIENT_TOKEN`。
@@ -121,8 +151,9 @@ CLI：

 ## 测试规格

- A1：`config/aipods/artificer.yaml` 能被 manager list/show/render，render 结果包含 `backendProfile=sub2api`、`model=gpt-5.5`、`reasoningEffort=xhigh`、provider SecretRef、GitHub PR token env projection、UniDesk SSH env projection、GitHub SSH volume projection、Artificer `gitMirror.enabled=false`、AgentRun runner tools gitbundle 和 gitbundle requiredSkills。
+- A1：`config/aipods/artificer.yaml` 能被 manager list/show/render，render 结果包含 `imageRef.kind=env-image-dockerfile`、`repoUrl`、`commitId`、`dockerfilePath`、`backendProfile=sub2api`、`model=gpt-5.5`、`reasoningEffort=xhigh`、provider SecretRef、GitHub PR token env projection、UniDesk SSH env projection、GitHub SSH volume projection、Artificer `gitMirror.enabled=false`、AgentRun runner tools gitbundle 和 gitbundle requiredSkills。
 - A2：`queue submit --aipod Artificer --dry-run` 输出标准 `queue-submit-plan`，且 `idempotencyKey`、prompt 与 metadata 被保留。
 - A3：Artificer 默认 `gitMirror.enabled=false` 时 GitHub URL 保持 SSH fetch；显式启用 `gitMirror` 后 GitHub URL 改写到 mirror base URL；非 GitHub URL 不改写。
- A4：runner Job dry-run 支持 tool credential volume mount，并且 response/manifest/event 不泄漏 Secret 明文。
- A5：`bun run check` 和 `bun run self-test` 必须覆盖 A1-A4。
+- A4：Aipod 启动/dispatch 能基于 `imageRef` 命中 artifact catalog / registry 并复用 digest-pinned env image；未命中时返回明确 build-required 或进入受控 CI/CD，不在 runner 任务内补装依赖。
+- A5：runner Job dry-run 支持 tool credential volume mount，并且 response/manifest/event 不泄漏 Secret 明文。
+- A6：`bun run check` 和 `bun run self-test` 必须覆盖 A1-A5。
@@ -52,9 +52,21 @@ CI 的最小检查应覆盖：
 - Bun/TS 单元自测试，包括 manager schema、adapter mock、Codex fake app-server stdio client 和 CLI JSON 输出。
 - `deploy/deploy.json` 与 GitOps render 只读校验。

-容器镜像必须区分 env identity 与 source commit。`agentrun-mgr-env:<envIdentity>` 只包含 Bun runtime、生产依赖、Codex CLI、git/kubectl/node 等系统依赖和 boot 脚本，不 bake `src/`、`scripts/` 或某个业务 source commit。运行时通过 `AGENTRUN_BOOT_COMMIT` 从 git mirror 按完整 SHA 做 `git fetch --depth=1 origin <sha>`，再用 env image 内的 `node_modules` 启动 manager 或 runner。CI/CD 仍然只允许纯 Tekton + Argo CD，不因 Bun 工具链引入自定义 runner、长期 poller 或源分支生成物提交。
+容器镜像必须区分 env identity 与 source commit。`agentrun-mgr-env:<envIdentity>` 只包含 Bun runtime、生产依赖、Codex CLI、git/kubectl/node 等系统依赖和 boot 脚本，不 bake `src/`、`scripts/` 或某个业务 source commit。AipodSpec 通过 `spec.imageRef` 引用 env image Dockerfile source（`repoUrl`、`commitId`、`dockerfilePath`），运行时通过 `AGENTRUN_BOOT_COMMIT` 从 git mirror 按完整 SHA 做 `git fetch --depth=1 origin <sha>`，再用 env image 内的 `node_modules` 启动 manager 或 runner。CI/CD 仍然只允许纯 Tekton + Argo CD，不因 Bun 工具链引入自定义 runner、长期 poller 或源分支生成物提交。

-Env identity 的输入至少包含：Bun base image、系统包列表、`deploy/container/Containerfile`、`deploy/runtime/boot/*.sh`、`package.json`、`bun.lock` 和 `tsconfig.json`。只改业务 TS、文档、模板中不影响 runtime env 的内容时，planner 必须输出 `build=0 reuse=1 unsafeReuse=0`，并只复用上一版 catalog 中同一 `envIdentity` 的 digest。若 GitOps catalog 因 mirror flush lag 暂时不可见，即使 G14 registry 中已有同名 `agentrun-mgr-env:<envIdentity>`，也必须先通过 `agentrun v01 git-mirror sync|flush` 或新的 PipelineRun 恢复 catalog provenance；不能把 registry HEAD 当作第二条发布真相。
+Env identity 的输入至少包含：`imageRef.repoUrl`、`imageRef.commitId`、`imageRef.dockerfilePath`、Bun base image、系统包列表、`deploy/runtime/boot/*.sh`、`package.json`、`bun.lock` 和 `tsconfig.json`。只改业务 TS、文档、模板中不影响 runtime env 的内容时，planner 必须输出 `build=0 reuse=1 unsafeReuse=0`，并只复用上一版 catalog 中同一 `envIdentity` 的 digest。若 GitOps catalog 因 mirror flush lag 暂时不可见，即使 G14 registry 中已有同名 `agentrun-mgr-env:<envIdentity>`，也必须先通过 `agentrun v01 git-mirror sync|flush` 或新的 PipelineRun 恢复 catalog provenance；不能把 registry HEAD 当作第二条发布真相。
+
+## Aipod env image reuse
+
+`AipodSpec.spec.imageRef` 是 Aipod 启动时选择 work-ready env image 的 source truth。Queue dispatch、Session turn 和 runner Job 创建不得直接信任 prompt、payload 或 CLI 临时传入的可变 image tag；它们必须先把 `imageRef` 映射到 artifact catalog 中的 env image identity 和 digest-pinned repository digest。
+
+规则：
+
+- `imageRef.kind` 固定为 `env-image-dockerfile`，最小字段为 `repoUrl`、完整 `commitId` 和仓库内相对 `dockerfilePath`。
+- `repoUrl + commitId + dockerfilePath` 指向的 Dockerfile source 必须能通过 Git mirror 或受控 Git credential 读取；不能依赖 runner 任务内手工 clone 和 build。
+- 启动 Aipod 时若 catalog 中存在匹配 env identity 且 digest 合法，必须复用该 digest-pinned image，并在 response/event 中标记 `status=reused`。
+- catalog 未命中时，CLI/API 只能返回明确 `build-required` 计划或触发受控 Tekton PipelineRun；不得让 runner task 进入后再运行 `apt`、`apk`、`bun install`、`npm install` 补环境。
+- catalog 记录必须包含 `imageRef` source 摘要、`envIdentity`、env image tag、digest、repository digest、build/reuse 状态和 provenance。SecretRef、token、SSH key 和 provider config 不进入 catalog。

 ## 真相源

@@ -132,7 +144,7 @@ Tekton promotion 可以读取 `deploy/deploy.json` 来 render runtime desired st

 - `v0.1` env image tag 使用 `envIdentity`，而不是 source commitId。source commitId 通过 `AGENTRUN_BOOT_COMMIT` 和 catalog `bootCommit` 进入 runtime。
 - Runtime manifest 必须使用 digest pin 作为部署身份；G14 本地 registry 对同一 tag 的默认 HEAD 可能返回 Docker schema1 compatibility digest，Tekton 必须用 `Accept: application/vnd.docker.distribution.manifest.v2+json` 采集 containerd 可直接拉取的 schema2 manifest digest，并在写入 catalog 前按 digest HEAD 验证。
- Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、env image tag、digest、env identity、boot commit、toolchain inputs 和 build/reuse 状态。
+- Catalog 必须记录 lane、source branch、GitOps branch、source commitId、serviceId、imageRef source 摘要、env image tag、digest、env identity、boot commit、toolchain inputs 和 build/reuse 状态。
 - 同一 env identity 对同一 service 应生成同一镜像；lane 差异放在 manifest、env、SecretRef、namespace、RBAC 和 runtime config 中，不 bake 进镜像。普通 source commit 差异由 boot checkout 选择。
 - `deploy/deploy.json` 只承载人写 runtime intent，不承载 digest、publish state 或 reuse evidence。
 - Source branch 不得因为 promotion 出现自动提交；若发布后 source branch 变化，必须是人工修改源码、测试、文档、模板或 `deploy/deploy.json`。
@@ -2,7 +2,7 @@

 本文是 AgentRun `v0.1` runner/backend 启动前的权威装配 SPEC。所有会进入运行时容器、进程、文件系统或环境变量的执行输入，都必须先落到本文定义的装配模型，再由 manager/runner 渲染为受控 Job 输入；不得在 CLI、Queue、runner Job、issue 过程或临时热补丁中绕过装配模型直接拼接 credential、host path 或隐式环境。

-`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend 镜像、哪个 profile/credential scope、哪份 session、哪份代码、初始 prompt、skill 和工具 credential。`BackendImageRef`、`ProfileRef`、`SessionRef`、`ResourceBundleRef` 仍是四个一等运行时要素；credential 注入不是第五个杂项要素，而是挂在 `ProfileRef`、`ResourceBundleRef` 或 tool scope 上的 SecretRef 装配引用。初始 prompt 与 skill 注入也不是第五条运行时路径，它们属于 `ResourceBundleRef` 指向的 Git-only 非敏感内容。
+`RuntimeAssembly` 只回答一个问题：一次 run 到底用哪份 backend/env 镜像、哪个 profile/credential scope、哪份 session、哪份代码、初始 prompt、skill 和工具 credential。`BackendImageRef`、`ProfileRef`、`SessionRef`、`ResourceBundleRef` 仍是四个一等运行时要素；credential 注入不是第五个杂项要素，而是挂在 `ProfileRef`、`ResourceBundleRef` 或 tool scope 上的 SecretRef 装配引用。初始 prompt 与 skill 注入也不是第五条运行时路径，它们属于 `ResourceBundleRef` 指向的 Git-only 非敏感内容。

 ## 最简四要素

@@ -10,7 +10,7 @@

 | 要素 | 最小字段 | v0.1 含义 | 不包含 |
 | --- | --- | --- | --- |
-| `BackendImageRef` | `image` | digest-pinned backend/runner 镜像。 | API KEY、profile config、用户代码、session 文件。 |
+| `BackendImageRef` | `source` 或已解析 `image` | Aipod env image Dockerfile source 与最终 digest-pinned backend/runner 镜像。 | API KEY、profile config、用户代码、session 文件、可变 image tag。 |
 | `ProfileRef` | `profile`、`secretRef` | provider profile 和 API KEY/配置 SecretRef。 | backend 镜像、session、repo 文件、GitHub/业务工具 credential。 |
 | `SessionRef` | `sessionId` 或 `null` | backend 会话文件持久化引用；P0 可以为 `null`。 | API KEY、完整 `CODEX_HOME`、Git workspace。 |
 | `ResourceBundleRef` | `kind="gitbundle"`、`repoUrl`、`bundles[]`、可选 `ref` / `commitId` / `promptRefs` / `requiredSkills` | 初始代码/文件输入、工具目录、skill 目录、required skill 校验和稳定初始 prompt；P0 固定 Git-only gitbundle，默认从 repo/ref 解析实际 commit。 | 上传文件、对象存储 artifact、inline env、Secret value、会话历史、旧 inline seed、inline skill manifest。 |
@@ -20,7 +20,13 @@ P0 最小 JSON 形态：
 ```json
 {
  "backendImageRef": {
-    "image": "127.0.0.1:5000/agentrun/agentrun-mgr@sha256:..."
+    "source": {
+      "kind": "env-image-dockerfile",
+      "repoUrl": "git@github.com:pikasTech/agentrun.git",
+      "commitId": "0000000000000000000000000000000000000000",
+      "dockerfilePath": "deploy/container/Containerfile"
+    },
+    "image": "127.0.0.1:5000/agentrun/agentrun-mgr-env@sha256:..."
  },
  "profileRef": {
    "profile": "codex",
@@ -124,10 +130,15 @@ HWLAB Workbench 的 project/workspace 不属于 RuntimeAssembly 四要素，也

 ### BackendImageRef

- `image` 必须是 digest-pinned image。
- image 来源必须是 CI/CD artifact catalog、GitOps manifest 或 manager allowlist；客户端不能在 run payload 中传任意镜像。
+- `BackendImageRef.source` 是 env image Dockerfile source，来自 AipodSpec `spec.imageRef` 或受控 runtime default；`kind` 固定为 `env-image-dockerfile`，最小字段为 `repoUrl`、完整 `commitId` 和仓库内相对 `dockerfilePath`。
+- `BackendImageRef.image` 是 source 解析后的 digest-pinned image，必须来自 CI/CD artifact catalog、GitOps manifest 或 manager allowlist；客户端不能在 run payload 中传任意可变镜像。
+- runner Job 创建前必须先用 `source` 解析 env image identity，并优先从 artifact catalog / registry 复用已有 digest；未命中只能返回明确 build-required 或进入受控 CI/CD，不能在普通任务容器内现装依赖。
 - v0.1 可以继续使用现有 agentrun runner 镜像，不要求立即拆独立 backend image。
- 验收时只需要能追溯实际 Deployment/Job image digest 和 source commit。
+- 验收时必须能追溯实际 Deployment/Job image digest、source commit、Dockerfile path、env identity 和 reuse/build 状态。
+- runner 镜像必须是 work-ready 执行环境：基础 CLI、Bun/Node/npm、Git/SSH/GitHub CLI、kubectl、curl、ripgrep 和 AgentRun 生产依赖必须在 env image 构建阶段进入镜像或受控预装层。普通任务不得在运行时用 `apt`、`apk`、`bun install`、`npm install` 或等价命令补装基础环境。
+- `workReady` capability 摘要必须出现在 manager health、runner job dry-run/response、queue dispatch response 和 runner startup event 中；摘要只能包含版本、工具名、版本号、依赖策略和 `valuesPrinted=false`，不得输出 env value、token 或 Secret 文件内容。
+- runner 启动后必须先执行短 smoke：镜像层检查 `bun`、`node`、`npm`、`git`、`ssh`、`gh`、`rg`、`curl`、`kubectl`；Artificer/UniDesk 工具型 gitbundle 装配后再检查 `tran`、`trans`、`apply_patch`。缺失时必须快速 `infra-failed`，不能把问题留给 prompt 内排查。
+- 项目依赖不属于默认 runtime preflight。AgentRun 自身 `node_modules` 固定为镜像层 `/opt/agentrun/node_modules`，boot 后只 symlink 到源码 checkout；业务 repo 的 `bun install`/`npm install` 只能由显式任务、派生镜像或受控 workspace cache 承担，不能成为每个 Aipod/Queue task 的默认前置。

 ### ProfileRef

@@ -230,7 +241,7 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.m
 5. Runner materialize tool credential 到该 run 允许的 env/file projection；未实现的 tool scope 必须显式 failed/blocked，不能静默跳过后让 agent 自己猜凭据。
 6. Runner materialize `kind="gitbundle"` resource bundle 到 workspace；P0 未实现时必须显式 blocked，不能猜测 host path。
 7. Runner 按 `bundles[]` 复制目录或文件，准备 workspace `tools/`、发现 `.agents/skills`，校验 `requiredSkills`，读取并校验 `promptRefs`，写入有界 assembly event。
-8. Runner 启动 backend，并在 event 中记录 image digest、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl、requested ref/commit、materialized commit、bundles、promptRefs、requiredSkills、tools 和 skillDirs 摘要。
+8. Runner 启动 backend，并在 event 中记录 imageRef source、env identity、image digest、reuse/build 状态、profile、SecretRef 名称/key、tool credential scope、sessionRef、repoUrl、requested ref/commit、materialized commit、bundles、promptRefs、requiredSkills、tools 和 skillDirs 摘要。

 任何一个要素缺失或不合法，都必须按该要素失败；不得静默 fallback。

@@ -239,8 +250,9 @@ skill 只来自 gitbundle 复制进 workspace 的 `.agents/skills/<name>/SKILL.m
 ### A1 BackendImageRef 验收

 - 实际 manager Deployment 和 runner Job 使用 digest-pinned image。
- event、CLI 或诊断输出能看到 image digest 或可追溯到 GitOps/catalog。
- run payload 不能传任意 image 字符串。
+- event、CLI 或诊断输出能看到 imageRef source、env identity、image digest 和可追溯 GitOps/catalog 条目。
+- run payload 不能传任意 image 字符串；Aipod 只能声明 env image Dockerfile source，dispatch 解析后才进入 runner job image。
+- 启动 Aipod 时命中已有 env identity 必须 reuse digest-pinned image；不得触发任务内 `apt`/`apk`/`bun install`/`npm install`。

 ### A2 ProfileRef 验收

@@ -24,6 +24,7 @@
 - Postgres adapter：migration、事务、run/command/event round-trip、重启后可查询。
 - Secret 分发：SecretRef schema、missing secret failure、redaction。
 - AgentRun Queue：task schema、attempt 状态机、summary/stats/read cursor、Queue 与 Session 引用边界、旧 MiniMax/OpenCode 直连入口废弃和 redaction。
+- AipodSpec / env image reuse：`spec.imageRef` schema、Artificer render、Queue metadata 继承、runner-job imageRef 解析、digest-pinned env image reuse 可见性和禁止任务运行时安装基础依赖的 work-ready smoke。
 - HWLAB v0.2 基线承接：可以用 fake backend/临时 manager 做组件自测试，覆盖 event contract、result completed 防误判、bounded output、runner job status、SessionRef profile 隔离、ResourceBundleRef 失败分类、`promptRefs`/gitbundle skillDirs/requiredSkills 装配和 backend preflight redaction；这些自测试不能替代真实 `agentrun-v01` CLI 交互验收。

 自测试应使用 Bun + TypeScript 运行，Codex 相关自测试可以使用 fake app-server JSON-RPC client 模拟 `initialize`、`thread/start`、`thread/resume`、`turn/start`、assistant 输出、协议错误、timeout 和 transport close。
@@ -59,7 +60,7 @@
 6. manager 可查询 command state、append-only events、terminal_status 和 redacted logPath/job identity。
 7. 重启 `agentrun-mgr` 后，run、command、events 和 terminal_status 仍可从 Postgres 查询。
 8. 日志、event、CLI 输出和 health 中没有 provider credential、DSN password、token 或 URL credential 明文。
-9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；未提供 session/resource 时必须显式为 `null`，提供时必须能查到 session/thread 和 Git commit/tree/workspace/bundles 摘要，不能由 runner 隐式猜测。若提供 `promptRefs`、gitbundle skills 或 `requiredSkills`，必须能查到 name/path/hash/bytes/injected 摘要；required prompt 或 required skill 缺失必须 blocked，不能 fallback 到模型默认 prompt 或默认 skill registry。
+9. 若变更涉及 RuntimeAssembly，必须能追溯 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 的装配状态；Aipod 启动还必须能追溯 `imageRef` source、env identity、reuse/build 状态和 digest-pinned image，不能由 runner 隐式使用可变 tag 或任务运行时安装基础依赖。未提供 session/resource 时必须显式为 `null`，提供时必须能查到 session/thread 和 Git commit/tree/workspace/bundles 摘要，不能由 runner 隐式猜测。若提供 `promptRefs`、gitbundle skills 或 `requiredSkills`，必须能查到 name/path/hash/bytes/injected 摘要；required prompt 或 required skill 缺失必须 blocked，不能 fallback 到模型默认 prompt 或默认 skill registry。

 ### CLI 交互联调标准