@orion-agents/orion-code 0.3.1 → 0.3.4

package/docs/architecture/v0.3.4-stabilization-contract.md

@@ -0,0 +1,32 @@
+# v0.3.4 stabilization contract
+
+The complete HTTP schema remains [the v0.3.3 OpenAPI document](v0.3.3-web-api.yaml), updated in the v0.3.4 branch to match the compatible wire additions below.
+
+## Context-bound Settings mutation
+
+```text
+bootstrap(workspaceId, contextRevision)
+  + settings(revision)
+  -> PATCH settings(requestId, workspaceId, expectedContextRevision, expectedRevision, operations)
+  -> admission guard
+  -> idempotency digest
+  -> atomic settings coordinator update
+```
+
+The Context guard is checked before any durable operation. A mismatch is `409 context_revision_conflict` with zero writes, Runtime applies, Session changes or provider requests.
+
+## File identity
+
+`kind` describes the lexical entry (`file|directory|symlink`). For a readable contained symlink, optional `targetKind` describes the effective target (`file|directory`). Authorization evaluates both the lexical alias and canonical Workspace-relative path at list and content-read time.
+
+## Terminal ordering
+
+```text
+ready -> optional gap -> retained replay -> buffered live tail -> optional exit -> close
+```
+
+PTY output stays paused while replay drains. A high surrogate at the end of a non-final chunk remains buffered; final exit replaces any unpaired surrogate with U+FFFD. Browser xterm submission waits for acknowledgement when the remaining capacity cannot hold a complete pair.
+
+## Durable tool truth
+
+Legacy records are accepted only when both terminal receipt and durable receipt fact are absent. Modern records require both; canonical receipt digest, execution policy digest and durable fact fields must match before a successful `tool_finished` projection is emitted.

package/docs/migration/v0.3.1-to-v0.3.2.md

@@ -0,0 +1,94 @@
+# Orion Code v0.3.1 → v0.3.2 Web Workbench 迁移说明
+
+v0.3.2 在 v0.3.1 专业工作台基础上增加可调左侧项目栏、Composer Control Center、
+Session 级模型与权限、可解释 Context、结构化引用、durable Plan review、队列编辑和
+Session 草稿恢复。升级保留现有 Workspace、Session、Thread、Goal、Settings 和项目文件。
+
+## 升级前准备
+
+1. 停止旧 `orion web` Host；如有活动 terminal，先在页面中关闭并确认子进程已退出。
+2. 备份 `$ORION_CODE_CONFIG_DIR/orion.json` 和 Session/Thread 数据目录。
+3. 记录当前 Workspace、Session、模型与项目默认权限。不要把绝对路径、凭据或真实 terminal
+   输出粘贴到问题报告。
+4. 使用 Node 22.12+、24 或 26；安装后执行 `orion --version` 与 `orion doctor`。
+
+## 布局偏好迁移
+
+v0.3.2 将旧布局偏好迁移为 `WorkbenchLayoutPreferenceV2`：
+
+- 左栏展开宽度默认 280px，可用鼠标指针在 240–480px 范围拖动，双击分隔条复位；
+- 左栏可折叠为 48px rail；右栏继续使用 320–720px 桌面宽度；
+- 中央对话区最小 560px，空间不足时先收缩右栏，再切换为 drawer；
+- `<=760px` 时左右栏是互斥 drawer，窄屏不会覆盖保存的桌面宽度；
+- 旧值无效或越界时会被 clamp/忽略，不会阻止 Workbench 启动。
+
+精细调宽只有鼠标指针入口；键盘仍可展开、折叠、打开 drawer 并操作全部内容。
+
+## Composer Control Center
+
+原先独立的 BUILD/PLAN/AUTO 按钮改为 Composer 下拉控制，并新增权限、模型、Effort 和
+Context 入口。Host 是 current/last-good/pending/error 的权威源，浏览器不会自行推断运行态。
+
+- **模式**：BUILD、PLAN、AUTO 是工作流模式；不等同于权限。
+- **权限**：Session 可选 project default、Ask、Allow 或 Deny。Allow 需要风险确认，且不会绕过
+  hard policy、sandbox、capability 或 workspace containment。
+- **模型**：模型和 Effort 是 Session 偏好；active turn 中的变更延迟到下一个 logical request。
+- **Context**：显示 Runtime 提供的 token 使用量、容量和来源；estimated 数据带 `~`，模型切换后
+  不沿用旧模型容量。
+- **Compact**：切换到更小上下文模型前，Host 先执行可验证 compact；失败时模型、Effort、
+  Session metadata 和下一次请求保持原值。
+
+模式与权限是两个独立轴。AUTO 不能覆盖显式 Deny，也不能把权限提升为全局设置。
+
+## Durable Plan review
+
+这是 v0.3.2 最重要的行为变化：PLAN 提交后不再自动开始实现。
+
+1. Runtime 提交 PlanReceipt，并写入 `awaiting_review` 的 durable review state；
+2. 浏览器显示 exact plan digest；刷新或 Host restart 后仍可恢复；
+3. “批准并进入 BUILD”只接受当前 exact digest，并创建独立 BUILD logical request；
+4. “继续规划”要求反馈并创建新的 PLAN request；
+5. “取消”结束 review，不产生执行副作用；
+6. stale revision/digest 返回 409，客户端不得自动重放。
+
+TUI、slash command 与 Web 共享同一 Plan review authority；UI 文案不是审批真源。
+
+## Context 引用、队列和草稿
+
+- `+` 可添加 workspace 文件/目录、Review hunk、历史 Session 和 Skill 引用；
+- 引用只传 opaque id、revision 和 digest，Host 在组装 prompt 时重新验证 containment、敏感文件、
+  stale revision 与预算；单引用最大 64KiB，总引用最大 256KiB；
+- 队列项可编辑、移动和删除，每次 mutation 需要 item revision；冲突返回 409 且零副作用；
+- Steer 与 follow-up 保持不同 admission 语义；队列使用执行时的最新 Composer 控制；
+- 未发送草稿按 Session 存在当前 tab 的 `sessionStorage`，切换/刷新可恢复，发送或显式清除后删除；
+  草稿不是 durable Session history，也不会跨浏览器重启恢复。
+
+## API 客户端变化
+
+自定义 Web 客户端应升级到
+[`v0.3.2 OpenAPI`](../architecture/v0.3.2-web-api.yaml)并遵守以下规则：
+
+- composer control mutation 携带 `requestId`、`expectedSessionId`、`expectedContextRevision` 和
+  control revision；
+- queue edit/move/remove 携带 queue revision 与 item revision；
+- Plan review 携带 exact plan digest/revision，不接受 last-write-wins；
+- Context reference 是 discriminated union，未知类型和未知字段 fail-closed；
+- replay reset 是硬屏障；matching active snapshot 恢复前 Composer 保持禁用；
+- 409 后先重新读取 bootstrap/snapshot，再让用户确认目标，不自动重放高风险操作。
+
+## 回滚到 v0.3.1
+
+1. 停止 v0.3.2 Host，并关闭所有显式启动的 terminal。
+2. 备份 v0.3.2 布局偏好、Session composer preference 和 Thread events 供排查。
+3. 安装 exact v0.3.1 artifact，并显式选择原 Workspace/Session。
+4. v0.3.1 会忽略新的布局/Composer 投影，但不会删除项目文件或旧 Thread history。
+5. 不要在 v0.3.1 中批准 v0.3.2 创建的 pending Plan review；需要继续时重新在 v0.3.2 打开，
+   或明确取消后再回滚。
+
+回滚不会恢复已关闭/lost terminal，也不会把浏览器 `sessionStorage` 草稿写入 Session。
+
+## 升级验证
+
+按 [`v0.3.2 Web E2E 资格计划`](../test/v0.3.2-web-workbench-e2e-plan.md)执行
+WEB32-P0-01..12。只有 source-clean `@orion-agents/orion-code@0.3.2` exact tgz、真实 Chrome、
+Node 22.12/24/26 和最终 digest-bound receipt 全部 GO，才能把候选标记为发布完成。

package/docs/migration/v0.3.2-to-v0.3.3.md

@@ -0,0 +1,62 @@
+# 从 Orion Code v0.3.2 升级到 v0.3.3
+
+v0.3.3 主要更新 Web Workbench：新增内置“方块工坊”视觉风格，并让同一 Host 中的多个 Session 可以
+独立运行。CLI/TUI 继续保持单活动 Session 语义。
+
+## 外观设置
+
+Settings Web view 从 schema 1 升级到 schema 2，`web.appearance` 新增：
+
+```json
+{
+  "web": {
+    "appearance": {
+      "style": "orion-blocksmith",
+      "theme": "system"
+    }
+  }
+}
+```
+
+`style` 只接受：
+
+- `orion-blocksmith`：v0.3.3 默认、随包提供的内置方块工坊；
+- `classic`：v0.3.2 的经典工作台几何。
+
+没有 `style` 的旧配置会以 `orion-blocksmith` 作为继承默认；原有 `theme=system|light|dark` 和
+`motion=system|reduced` 不变。保存仍使用 Host revision/CAS，style 与 theme 可在同一批次原子更新；
+旧 schema 的浏览器响应会在客户端只读归一化，不会把本地外观副本写入 localStorage。
+
+若希望保持 v0.3.2 外观，在 Settings → General → 视觉风格选择“经典”，或显式配置：
+
+```json
+{ "web": { "appearance": { "style": "classic" } } }
+```
+
+## 多 Session Web Runtime
+
+- Web 命令现在必须携带 exact `workspaceId`、Context revision、Session ID 和 Session Runtime revision；
+- 同时最多运行三个 Session turn；第 4 个进入 FIFO 队列，可从当前 Session Composer 取消；
+- Session 列表显示 running、waiting approval 和 queued 状态；切换页面不会停止后台 Session；
+- 同一 workspace 的变更型 Tool 通过共享写入仲裁器串行执行；revision 已变化时在副作用前失败；
+- Host 重启不会偷偷重放未完成副作用。内存 actor 消失后，durable Thread/receipt 仍是恢复权威。
+
+这些协议变化要求 Host 与 Web client 来自同一个 v0.3.3 安装包。升级后请关闭旧标签页并重新打开 Host
+输出的 loopback URL；旧 nonce、旧 Session Runtime revision 或旧命令 body 会得到 409/400，不会自动重放。
+
+## 布局和 Settings 入口
+
+- 右侧工作面板折叠后固定为右侧全高 48px rail；窄屏继续使用 modal drawer；
+- Settings 常驻入口只保留在左侧项目栏底部，折叠 rail 和窄屏 drawer 中仍可达；
+- 左右栏的桌面宽度偏好保存在设备本地布局偏好中，窄屏 drawer 不覆盖桌面值。
+
+## 回滚
+
+回滚到 v0.3.2 前建议在 v0.3.3 将视觉风格切到 `classic`。v0.3.2 的 tolerant config loader会忽略它
+不认识的 `web.appearance.style`，不会执行任何主题代码；但旧 Web client 不理解 schema 2 响应，因此必须
+同时回滚 Host 和静态 Web 资产，不能混用版本。
+
+## 验证
+
+发布候选必须使用同一 exact npm tarball 在 Node 22.12、24、26 的全新 prefix 运行真实 Chrome critical
+matrix。历史 v0.3.2 receipt 不能证明 v0.3.3；缺少任一 WEB33 场景时发布结论为 `NO_GO`。

package/docs/migration/v0.3.3-to-v0.3.4.md

@@ -0,0 +1,36 @@
+# Migrating Orion Code from v0.3.3 to v0.3.4
+
+v0.3.4 is a compatible stabilization release. Existing projects, Sessions, Goals, settings and terminal preferences require no data migration.
+
+## Web API callers
+
+`PATCH /api/v1/settings` now requires the active Context guard in addition to Settings CAS:
+
+```json
+{
+  "requestId": "<uuid>",
+  "workspaceId": "<bootstrap.workspaceId>",
+  "expectedContextRevision": "<bootstrap.contextRevision>",
+  "expectedRevision": "<settings.revision>",
+  "operations": [{ "op": "set", "key": "appearance.theme", "value": "dark" }]
+}
+```
+
+A stale page receives `409 context_revision_conflict`. The client must refresh bootstrap/settings and ask the user to retry; it must never replay the mutation automatically into a different Workspace.
+
+File tree responses may add `targetKind: file|directory` for readable symbolic links. Callers should preserve `kind=symlink` for display/security and use `targetKind` only to choose file preview versus directory expansion.
+
+Review responses add `totalChangedFiles`. `changedFiles.length` is the visible bounded page and must not be presented as the repository total when `truncated=true`.
+
+## Runtime behavior
+
+- Blank Session rename requests now return 400 instead of persisting an empty title.
+- A busy `reject-busy` slash command no longer clears the active turn state.
+- Tool receipts with one-sided or mismatched durable evidence fail closed in UI projections.
+- Terminal reconnect sends all replay frames before live tail and exit; unpaired UTF-16 input is normalized at the transport boundary.
+
+## Security behavior
+
+Internal symbolic-link aliases do not bypass sensitive-file policy. Git diff blocks sensitive current paths and rename sources. Structured X-prefixed credentials, URL userinfo and captured command output pass through the shared redaction boundary.
+
+No configuration key is renamed and no manual file rewrite is required.

package/docs/plan/v0.3.1-web-workbench-professional-shell-plan.md

@@ -1,7 +1,7 @@
 # v0.3.1 Web Workbench 专业工作台优化计划
 
 - 版本：v0.3.1
-- 状态：待实施
+- 状态：实施完成；发布资格以同一 source-clean 提交生成的 release receipt 为准
 - 日期：2026-08-29
 - 范围：Web Workbench 左侧项目导航、右侧工作面板、布局系统、专业化 UI
 - 参考：Codex 的工作台信息架构与交互密度；不复制其品牌、视觉资产或私有实现