docs: 固化 HWLAB 基线承接 SPEC

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

@@ -32,6 +32,19 @@ Kubernetes Job runner 必须把 credential source 与 runtime home 分开：Secr
 
 RuntimeAssembly P0 中 `SessionRef` 可以显式为 `null`，runner 不得把完整 `CODEX_HOME`、Secret projection 或节点 host path 当作 session store。`ResourceBundleRef` P0 收敛为 Git-only；runner 已支持把 `repoUrl + full commitId` checkout 到 `AGENTRUN_WORKSPACE_ROOT` 下的隔离目录，并记录 commit/tree 摘要，不能把用户上传文件或 env dump 混入 Git-only bundle。
 
+## HWLAB v0.2 执行经验承接
+
+Runner 承接的是 HWLAB v0.2 原有 Code Agent 的执行层经验，不承接 HWLAB cloud-api 的业务路由和权限判断。实现时优先参考 HWLAB 已验证的代码路径，而不是重新定义 Codex session、trace 和输出裁剪语义：
+
+| HWLAB v0.2 参考能力 | 参考入口 | Runner 承接规则 |
+| --- | --- | --- |
+| Codex app-server stdio thread/turn 生命周期 | `internal/cloud/codex-stdio-session.ts` | 有 `SessionRef.threadId` 时执行 resume，再 start turn；无 thread 时 start thread；turn terminal 才能上报 completed。 |
+| cancel/interrupt | `internal/cloud/server-code-agent-http.ts`、`internal/cloud/codex-stdio-session.ts` | runner 必须轮询 manager cancel 状态并中止 backend；backend 不支持精确 interrupt 时终止受控进程组。 |
+| runnerTrace 事件可见性 | `internal/cloud/code-agent-trace-store.ts` | backend 输出必须转成 manager events；每个 terminal/错误/取消都要有事件和 final status。 |
+| workspace-write 边界 | `internal/cloud/code-agent-contract.ts` | runner 只使用 ResourceBundleRef materialized workspace，不猜 HWLAB Pod 的 `/workspace/hwlab` 或 host path。 |
+| Secret 与 writable CODEX_HOME 分离 | `internal/cloud/code-agent-contract.ts`、`docs/reference/code-agent-chat-readiness.md` | profile Secret 只读投影，复制到当前 run/profile writable runtime home；不同 profile 不共享 runtime home。 |
+| bounded stdout/stderr | `docs/reference/code-agent-chat-readiness.md` | `command_output` 记录摘要、字节数、截断标记和必要引用；不得把大输出直接塞进单个 event/result。 |
+
 Kubernetes Job runner 必须设置有限保留时间。`v0.1` 默认 `ttlSecondsAfterFinished=86400`，用于保留最近完成 Job 的调试窗口，同时避免长期堆积 `Completed` runner Job 污染运行面观察。该 TTL 是 Job manifest 的运行面属性，不是 CI/CD 门禁；需要延长保留时间时必须通过受控 Job render/input 显式覆盖，并在 issue 或 PR 中说明原因。
 
 ## Runner 生命周期
@@ -84,6 +97,21 @@ Runner 必须把以下失败归类为结构化 failureKind：
 
 Runner 日志必须实时 flush 到文件或 pod log，CLI 启动 runner 时必须返回 logPath 或 job/pod identity。日志、event、trace 和 CLI 输出不得出现 provider credential、`auth.json`、`config.toml` 内容、DSN password、token 或 URL credential。
 
+## Runner Job 最小状态
+
+HWLAB v0.2 原有 Code Agent 在 cloud-api 进程内执行，失败时依赖本地 trace 定位；AgentRun 将执行迁到 runner Job 后，runner 必须把最小定位事实交回 manager。`runner-jobs` 创建响应和后续查询至少包含：
+
+| 字段 | 规则 |
+| --- | --- |
+| `attemptId` | 同一 command 的一次执行尝试；重复 idempotency key 和相同 payload 返回同一 attempt。 |
+| `jobName` / `namespace` | Kubernetes Job identity；不得要求业务客户端自己构造名称。 |
+| `runnerId` | runner register 后的执行者身份。 |
+| `podIdentity` / `logPath` | 至少提供一种可定位 runner 日志的 redacted 引用。 |
+| `phase` / `exitCode` | 若可用，返回 Job/Pod/container 的最小状态摘要；不可用时必须说明 `waitingFor` 或 failureKind。 |
+| `startedAt` / `finishedAt` | 用于区分 pending、running、terminal 和 TTL retention 窗口。 |
+
+这些字段只用于可观测性，不授予调用方直接操作 Kubernetes Job 或读取 Secret 的权限。
+
 ## 测试规格
 
 ### T1 Runner 启动可见性