fix: add aipod imageRef work-ready runner reuse

docs/reference/spec-v01-aipod-spec.md

@@ -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。