@orion-agents/orion-code 0.3.0 → 0.3.1

package/docs/readme.md

@@ -18,6 +18,16 @@ The repository release history is canonical in [`CHANGELOG.md`](../CHANGELOG.md)
 link into the archive, but historical evidence is not moved back into `plan/` merely to satisfy an
 old relative path.
 
+## v0.3.1 candidate release set
+
+- [Professional Web Workbench plan](plan/v0.3.1-web-workbench-professional-shell-plan.md)
+- [v0.3.1 Web API contract](architecture/v0.3.1-web-api.yaml)
+- [v0.3.1 real Web E2E qualification plan](test/v0.3.1-web-workbench-e2e-plan.md)
+- [v0.3.0 to v0.3.1 migration and rollback](migration/v0.3.0-to-v0.3.1.md)
+
+Candidate plans and contracts describe required behavior; they are not release evidence. A v0.3.1
+GO still requires the source-clean exact-tarball receipts described by the E2E plan.
+
 ## v0.3.0 release set
 
 - [Web Workbench development plan](plan/v0.3.0-web-workbench-plan.md)

package/docs/test/v0.3.1-web-workbench-e2e-plan.md

@@ -0,0 +1,140 @@
+# Orion Code v0.3.1 Web Workbench E2E 资格计划
+
+- 目标版本：`0.3.1`
+- 状态：合同已冻结，真实 release evidence 待生成
+- 权威场景目录：`src/runtime/release-receipts.ts`
+- 证据组装器：`scripts/e2e/assemble-web-e2e-receipt.ts`
+- 产品方案：[`v0.3.1 Web Workbench 专业工作台计划`](../plan/v0.3.1-web-workbench-professional-shell-plan.md)
+- API 合同：[`v0.3.1 Local Web API`](../architecture/v0.3.1-web-api.yaml)
+
+## 1. 准出结论边界
+
+源码、单元测试或开发服务器通过都不是 v0.3.1 Web 发布证明。只有满足以下条件的
+`WebE2EReleaseReceiptV1` 才可判定 GO：
+
+1. 从 source-clean checkout 只构建一次 `@orion-agents/orion-code@0.3.1` tgz；
+2. 三次 fresh primary run 和 Node 22.12.0、24.0.0、26.0.0 runtime run 全部安装同一个
+   `tarballSha256`，且 `installedTargetDigest` 相同；
+3. 使用真实 Chrome、打包后的 `bin/orion`、真实 Host、真实 Git fixture 和真实 PTY；
+4. primary run 完整执行 34 个场景，runtime run 执行冻结的 24 个 critical 场景；
+5. 无 skip、expected-fail、自动 retry 或开发源码 fallback；
+6. console error/warning、page error、HTTP 5xx、secret finding、evidence dropped event 均为 0；
+7. WEB31 的结构化事实和 PNG 均存在、通过安全校验并进入 manifest digest；
+8. runner name/image/digest、Chrome channel/version、Node/npm/platform/arch 全部写入 receipt。
+
+当前 live v0.3.0 页面、开发机 `dist/` 或历史 receipt 只能作为诊断材料，不能替代本计划证据。
+
+## 2. 场景目录
+
+每个 Playwright 标题必须且只能包含一个场景 ID。Settings 标题继续包含 `@settings`；WEB31
+通过 ID 原生识别，不依赖易漂移的 grep 标签。
+
+| ID          | 必须验证的真实旅程                                                                    | 必须写入的 WEB31 facts                                                                  |
+| ----------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| WEB31-P0-01 | packaged bootstrap、至少三个项目可见、按需展开首个 Session page                       | `projects_visible>=3`、`lazy_session_page=true`                                         |
+| WEB31-P0-02 | 跨项目 Session 原子切换；命令只落目标 Session；陈旧 context guard 返回 409 且零副作用 | `context_target_verified=true`、`context_conflict_side_effects=0`                       |
+| WEB31-P0-03 | 真实 Chrome 鼠标指针拖动右栏至 320/default/720，双击复位并刷新恢复                    | `resize_input=mouse-pointer`、min/max、无 keyboard fine resize、desktop width preserved |
+| WEB31-P0-04 | Agent 的 Goal、Plan、活动、能力、诊断和 Composer 旧能力无回归                         | `agent_regression_verified=true`                                                        |
+| WEB31-P0-05 | 文件树、文本分页、binary metadata、敏感文件和 symlink escape fail-closed              | `file_security_verified=true`                                                           |
+| WEB31-P0-06 | Git clean/dirty/staged/unstaged/untracked/conflict/log/detached                       | `git_state_matrix_verified=true`                                                        |
+| WEB31-P0-07 | Review Diff；用户选中 hunk 并送入 Composer，浏览器不直接改文件                        | `review_hunk_to_composer=true`                                                          |
+| WEB31-P0-08 | 真实 PTY input/output/ANSI/resize/tab/close                                           | `real_pty_verified=true`                                                                |
+| WEB31-P0-09 | refresh reconnect、gap、Host restart 后 lost、关闭与 shutdown 无 orphan               | `terminal_orphan_processes=0`、`terminal_restart_state=lost`                            |
+| WEB31-P0-10 | SSE 与 terminal WS 并存；长输出不挤占对话流或进入 SSE                                 | `sse_ws_isolated=true`、`transport_dropped_events=0`                                    |
+| WEB31-P0-11 | 1180/760/390/320 drawer、焦点归还、200% zoom、无水平溢出                              | `responsive_focus_verified=true`、`horizontal_overflow=0`                               |
+| WEB31-P0-12 | light/dark、reduced motion、axe、secret sentinel                                      | `axe_blocking_violations=0`、`secret_findings=0`、`reduced_motion_verified=true`        |
+
+代码中的完整 fact key 以 `tests/e2e/scenarios.ts::WEB31_REQUIRED_EVIDENCE_FACTS_V1` 为准。
+组装器拒绝缺失、错误类型或不满足阈值的值；不能用一个笼统的 `passed=true` 代替。
+
+## 3. Critical 子集
+
+Node 22.12/24/26 的 exact-tarball runtime 矩阵固定执行：
+
+```text
+E2E-P0-01..04
+SET-P0-01..14
+WEB31-P0-01, WEB31-P0-02, WEB31-P0-08, WEB31-P0-09, WEB31-P0-10, WEB31-P0-12
+```
+
+这 24 个场景覆盖 packaged bootstrap、原子 Context、完整 Settings、真实 PTY 生命周期与
+重连、SSE/WS 隔离、无障碍和 secret 门禁。WEB31-P0-03..07、11 仍必须在三次 full primary
+run 中执行，不得因未进入 Node runtime 子集而降级。
+
+Critical grep 由 `WEB_E2E_CRITICAL_SCENARIOS_V1` 生成；package script 不接受调用者覆盖 grep，
+防止 CLI 字符串与 receipt catalog 漂移。
+
+## 4. Context、resize 与终端硬断言
+
+### 4.1 Context guard
+
+- active workspace/session/resource 请求携带当前 `workspaceId` 和 `expectedContextRevision`；
+- mutation 还携带 UUID `requestId`，session command 继续携带 `expectedSessionId`；
+- 陈旧 guard 精确返回 HTTP 409、`code=context_revision_conflict`；
+- 失败请求不得激活 Runtime、读取另一 workspace、创建 PTY、写注册表或投递命令；
+- E2E 在冲突前后比较 bootstrap/context revision、target Session transcript 和 terminal list。
+
+### 4.2 Resize 与响应式
+
+- 精细调宽由 IDE 式鼠标指针拖动验证；右栏 clamp 为 320–720px，双击恢复 420px；
+- 不提供键盘逐像素调宽入口，键盘用户仍可展开、折叠和操作完整 drawer；
+- `>1180px` 为 dock，`761–1180px` 为右 drawer，`<=760px` 为左右互斥 drawer；
+- 自动进入 drawer 不得覆盖桌面宽度 preference，回到桌面后恢复；
+- drawer 打开时主区 inert，Escape/close/scrim 关闭并把焦点归还触发器。
+
+### 4.3 Terminal
+
+- 只能由显式用户 gesture 创建；backend 必须是安装包中的真实 `node-pty`；
+- WebSocket 子协议为 `orion-terminal-v1`，ticket 在首个 JSON 消息中发送，禁止 query string；
+- ticket 单次使用、短时有效；过期/复用/错误 Origin/Host/subprotocol 均 fail-closed；
+- reconnect 使用 sequence；gap 必须显式报告，不能伪装为连续；
+- terminal bytes 不进入 SSE、Session snapshot、diagnostics、stdout/stderr evidence 或截图；
+- close、workspace switch、Host shutdown 必须清理进程树，orphan count 为 0。
+
+## 5. 截图与隐私证据
+
+每个 SET/WEB31 场景至少写入一个 `screenshot.*` fact。值只能是场景目录内安全 basename
+且扩展名为 `.png`。组装器拒绝绝对路径、`..`、子目录、symlink、非 regular file、错误 PNG
+signature、零尺寸或超预算图片，并把 PNG SHA-256 纳入 run manifest digest。
+
+截图必须裁剪到产品表面，终端场景只能显示无敏感信息的合成输出。以下内容不得出现：
+
+- 绝对路径、用户名、Home 目录；
+- provider key、Authorization、Cookie、terminal ticket；
+- 原始 terminal 命令历史或真实项目内容；
+- 外部 URL、邮件、账户或个人数据。
+
+## 6. 执行与 receipt 组装
+
+发布执行器应通过 CI 的 build-once artifact job 生成 tgz 和 artifact receipt，再把同一文件下载到
+primary 与 Node runtime jobs。等价本地入口如下；路径由实际 artifact receipt 决定：
+
+```bash
+npm run release:artifact -- \
+  --out-dir .release/package \
+  --receipt .release/package/artifact.json
+npm run test:web-e2e:primary -- \
+  --tarball .release/package/orion-code-0.3.1.tgz \
+  --receipt .release/package/artifact.json \
+  --chrome /absolute/path/to/google-chrome
+npm run test:web-e2e:matrix -- \
+  --tarball .release/package/orion-code-0.3.1.tgz \
+  --receipt .release/package/artifact.json \
+  --chrome /absolute/path/to/google-chrome \
+  --node22 /absolute/path/to/node-22.12.0 \
+  --node24 /absolute/path/to/node-24.0.0 \
+  --node26 /absolute/path/to/node-26.0.0
+```
+
+随后用三个 primary manifests、三个 runtime manifests 和同一个 artifact receipt 运行
+`npm run release:web-e2e-receipt`。最终 release receipt 必须强绑定 Web receipt digest，不能手工
+复制 decision 或只记录文件名。
+
+## 7. 失败处理
+
+- 任一 ID 缺失、重复、乱序或出现额外 ID：NO_GO；
+- skip、expected-fail、retry 后成功：仍无 fresh 资格证据，NO_GO；
+- 任一 Node line clean install/native PTY 失败：NO_GO，不降级为伪终端；
+- screenshot/fact/runner identity/Chrome identity 缺失或被替换：NO_GO；
+- context guard 有副作用、terminal orphan 非零、axe/secret/dropped 非零：NO_GO；
+- 修复后必须从同一 source-clean commit 重建新的 exact tgz，并重新生成全部相关 evidence。