Merge origin/master into feat/2010-hwlab-release-production-lane

docs/reference/pikaoa.md

@@ -78,7 +78,7 @@
 
 5. `secrets sync` 按 YAML 声明补齐允许生成的本地来源，并下发 `pikaoa-test-runtime`。
 6. 使用同一 commit 依次执行：
-   - `--step migration`；
+   - `--step init`，仅初始化全新数据库；
    - `--step api`；
    - `--step worker`；
    - `--step web`。
@@ -87,7 +87,7 @@
 ## 单步运行
 
 - foundation 不需要 `--commit`，也不检查业务 Secret。
-- migration、api、worker、web 和 all 必须显式提供 `--commit`。
+- init、api、worker、web 和 all 必须显式提供 `--commit`。
 - 每个 `start` 立即返回任务 ID；使用同一 target、instance 和 step 的 `status` 查询终态。
 - request identity 包含：
   - target；
@@ -108,19 +108,21 @@
   - 提供新的 `--commit` 修订标识；
   - 修改 foundation 的稳定 manifest 结构。
 - 不为重跑引入第二状态库、控制器、租约或长期历史存储。
-- 迁移、rollout 或运行面查询失败返回具名失败码，不静默进入下一阶段。
+- initializer、rollout 或运行面查询失败返回具名失败码，不静默进入下一阶段。
 - OTel exporter、配置版本和 commit 对齐漂移只产生 `blocking=false` warning，不恢复 dedicated 门禁。
 
 ## 交付阶段
 
-- 当前阶段先稳定 YAML-first CLI 原入口和固定 NC01 测试运行面。
-- CLI 闭环通过后，再建设独立 test CI/CD：
-  - 复用同一 owning YAML；
-  - 按 foundation、Secret sync、migration、api、worker、web 顺序编排；
+- `pikaoa-test-nc01` 独立 test CI/CD 复用同一 owning YAML：
+  - 产品 `master` 只生成 `.tekton/pikaoa-test-nc01-pac.yaml`；
+  - API、Worker、Web 并行构建并以 digest 发布 GitOps；
+  - initializer 通过 Argo `PreSync` 在 API、Worker、Web 前初始化全新数据库；
   - 不创建专用测试集群；
   - 不生成动态 namespace；
   - 不创建 namespace-local PostgreSQL；
   - 不把测试 CI/CD 变成生产交付或用户业务的阻塞门禁。
+- GitOps 接管后，手动 `test-target start|stop` mutation 仅用于暂停 Argo 自动同步后的有界调试；禁止 CLI direct-apply 与 Argo 同时写入。
+- 生产 `pikaoa-nc01` 保留 `release` source authority，但当前不 bootstrap、不生成 `.tekton`、不创建 PipelineRun。
 - PR、构建或单测不能替代固定 NodePort 原入口验收。
 
 ## 本地验证

docs/reference/webterm.md

@@ -22,3 +22,22 @@
   - `browserOutputPolicy.maxFramesPerSecond` 是每个浏览器连接、每个终端的最大输出消息频率；
   - `browserOutputPolicy.maxFrameBytes` 是单条聚合输出消息的字节上限；
   - 后端必须按终端独立排队，小数据在频率窗口内合并，积压数据按窗口顺序发送，禁止用字节阈值绕过频率上限。
+- 持久 Codex Session 创建：
+  - 适用于本地 provider 的 `mycx` 与 `oncx` runtime 自动恢复标签；
+  - 新建必须直接调用原生 `codex app-server`，按顺序完成 `initialize`、`initialized`、`thread/start` 与 `thread/name/set`；
+  - `thread/start` 必须显式传入 `ephemeral=false`，并以返回的 thread ID 作为后续恢复 Session ID；
+  - 禁止通过附带 `--profile` 的 `mycx` 或 `oncx` 包装器启动 app-server，当前 Codex 只允许 profile 用于 runtime 命令；
+  - `mycx` 创建沿用默认 Codex home，`oncx` 创建必须沿用包装器声明的 `CODEX_HOME`、`CODEX_SQLITE_HOME` 和凭据环境清理规则；
+  - Webterm 运行在使用 `/usr/local/bin/host-shell` 的容器中时，app-server 必须通过宿主 namespace 执行原生 Codex；
+  - 容器与宿主工作目录分层：
+    - 容器进程工作目录必须使用容器内存在的目录；
+    - 目标工作目录只通过 `thread/start.cwd` 传给宿主 Codex；
+    - 禁止把仅宿主存在的路径直接作为容器 `spawn.cwd`；
+  - 只有 `thread/name/set` 成功后才能把 Session ID 写入 runtime 数据域，再通过 `mycx|oncx resume <session-id> <prompt>` 启动终端；
+  - 恢复 prompt 必须作为 CLI 参数传入，禁止在 xterm 中模拟键盘输入；
+  - runtime 记录与 YAML 预置恢复标签必须共存，runtime 数据域不得改变 owning YAML 的预置定义。
+- 持久 Session 最小验收：
+  - 先执行目标的受控 `status`，确认 provider 健康和 runtime 数据域正确；
+  - 再从真实浏览器加号入口创建一个持久 Session，关闭标签后从恢复列表重新打开；
+  - 创建与恢复后的 Session ID 相同、标签为 runtime 自动恢复且终端进入 running，才判定端到端合同成立；
+  - 单元测试只验证 app-server 消息顺序、模式环境和宿主 namespace 启动参数，不能替代真实浏览器验收。