@orion-agents/orion-code 0.3.2 → 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.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.