@orion-agents/orion-code 0.3.0 → 0.3.2

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

@@ -0,0 +1,88 @@
+# Orion Code v0.3.0 → v0.3.1 Web Workbench 迁移说明
+
+v0.3.1 将 Web Workbench 从固定三栏升级为多项目导航和专业工程面板，同时保持单一 active
+Workspace/Runtime。迁移不会复制 Session、重写 Thread history，也不会把 terminal 变成 durable Session。
+
+## 升级前准备
+
+1. 停止正在运行的 `orion web` Host，并确认重要终端任务已经结束；浏览器终端不会跨 Host 重启恢复。
+2. 备份 `$ORION_CODE_CONFIG_DIR/orion.json` 与现有 Session/Thread 数据目录。
+3. 记录当前活动 Workspace 和 Session；不要在问题报告中粘贴绝对路径、凭据或 terminal 输出。
+4. 使用受支持的 Node 22.12+、24 或 26。Node 20 不属于 v0.3.1 发布合同。
+
+## 多项目注册表
+
+首次运行时，Host 会从当前工作区和已有 Session project metadata 幂等导入 WorkspaceRegistryV1。
+
+- 注册表只保存规范化项目身份、显示标签、最近使用时间和 pin 顺序；
+- 它不会复制项目文件、删除 Session 或同时启动多个 Agent Runtime；
+- 不存在或不可访问的项目显示 unavailable，可从注册表移除；移除不删除磁盘目录或历史；
+- 展开 inactive project 只读取轻量 Session page/Git summary，不激活 Runtime；
+- 点击另一个项目的 Session 通过一次 `workspaceId + sessionId + expectedContextRevision` 原子切换。
+
+陈旧 Context guard 返回 `409 context_revision_conflict`，Host 保持原 context，且不得投递命令、
+创建 PTY、读错 workspace 或产生其他副作用。客户端应重新读取 bootstrap 后显式重试。
+
+## 布局偏好
+
+右侧 Work panel 的桌面宽度默认 420px，可用 IDE 式鼠标指针在 320–720px 间拖动调整，双击
+分隔条复位。
+
+- 精细调宽没有键盘入口；键盘用户可以展开/折叠面板，并在 drawer 中访问全部功能；
+- 窄屏自动切换 drawer，不覆盖桌面宽度偏好；返回桌面时恢复；
+- 无效或越界旧值会被 clamp/忽略，不阻止 Workbench 启动；
+- 当前面板、折叠态和桌面宽度是 UI preference，不是 Runtime 或 Session 权威状态。
+
+## 文件、Git 与审阅
+
+这些面板都是 Host 管理的只读投影：
+
+- 文件操作使用 opaque id；Host 每次读取都重新检查 canonical workspace containment；
+- sensitive file、workspace 外 symlink、non-regular path 和 stale revision 均 fail-closed；
+- Git 只使用 argv 执行 bounded status/log/diff，不提供 checkout、reset、stage、commit 或 push；
+- binary 文件只返回 metadata，文本和 Diff 采用 revision-bound 分页并在 Host 端脱敏；
+- “发送到 Composer”只把用户选择的安全文本加入草稿，不直接修改文件。
+
+## 真实终端
+
+v0.3.1 terminal 是显式用户启动的真实本地 PTY，是高权限、非 durable 表面：
+
+- 仅在 active workspace 启动，环境变量经过 allowlist/scrub；
+- attach ticket 单次使用且短时有效，只能放在 WebSocket 首个 JSON 消息中；
+- 刷新页面时，只要原 Host 仍存活可申请新 ticket 并按 sequence reconnect；
+- 输出缓冲已经截断时返回明确 gap；不补造丢失字节；
+- Host 重启后旧 terminal 显示 lost，不从 Session、日志或 snapshot 恢复；
+- close、workspace switch 和 Host shutdown 会终止拥有的进程树。
+
+terminal 字节不会进入 Workbench SSE、Thread transcript、diagnostics、release stdout/stderr 或持久设置。
+
+## API 客户端变化
+
+自定义 v0.3.0 Web 客户端升级时应改用
+[`v0.3.1 OpenAPI`](../architecture/v0.3.1-web-api.yaml)：
+
+- active workspace/session/resource 请求携带 `workspaceId` 和 `expectedContextRevision`；
+- mutation 的 `requestId` 是 UUID；session command 仍携带 `expectedSessionId`；
+- 新增 Workspace registry/session summary、files、Git、review、terminal REST 资源；
+- terminal 使用独立 `orion-terminal-v1` WebSocket，不能从 SSE 读取 terminal output；
+- `workspace_resource_invalidated` 只提示按 revision 重取，不携带文件、Diff 或 terminal 内容。
+
+不要在 409 后盲目重放旧 body；先获取新 bootstrap，确认用户仍希望对同一目标执行，再生成新的
+context-bound mutation。只有 byte-equivalent body 才能复用原 requestId。
+
+## 回滚到 v0.3.0
+
+1. 关闭浏览器并停止 v0.3.1 Host，等待所有 terminal 进程退出；如有异常，先核对进程所有权再处理。
+2. 保留一份 v0.3.1 WorkspaceRegistry/layout preference 备份以便排查；v0.3.0 不依赖这些数据。
+3. 使用升级前备份恢复 `orion.json`（如果升级期间修改过 Settings）。
+4. 安装并启动确切的 v0.3.0 artifact，再显式选择原 Workspace/Session。
+5. 验证 Thread history、当前模型、Goal/Plan 和 pending approval；不要从 terminal 输出重建历史。
+
+回滚不会自动恢复已关闭或 lost 的 terminal，也不应删除 v0.3.1 创建的项目文件。WorkspaceRegistry
+和布局偏好不是 Session 权威源；旧版本忽略它们不代表数据被删除。
+
+## 升级验证
+
+按 [`v0.3.1 Web E2E 资格计划`](../test/v0.3.1-web-workbench-e2e-plan.md)执行
+WEB31-P0-01..12。只有 source-clean exact-tarball、真实 Chrome、Node 22.12/24/26 和最终 receipt
+均为 GO，才能把当前候选标记为发布完成。

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/plan/v0.3.0-web-workbench-plan.md

@@ -82,7 +82,13 @@ Loopback Web Host (node:http)
 - Every mutation, including workspace/session transitions, settings changes and runtime commands,
   has a client-generated `requestId`. A bounded result cache keyed by both `requestId` and request
   digest makes exact retries idempotent for the lifetime of the server process; reuse with a
-  different body returns `409 Conflict`.
+  different body returns `409 Conflict`. Accepted IDs are never evicted: after 4,096 distinct
+  mutations the Host fails new IDs closed with `503 mutation_capacity_exhausted` until restart,
+  instead of risking duplicate side effects.
+- Every runtime command also carries `expectedSessionId`. The Host compares it with the active
+  Session in the same synchronous admission step as dispatch; a concurrent Session transition or
+  mismatch returns `409 active_session_changed`/`runtime_busy` without executing or replaying the
+  command.
 - Settings are a compare-and-swap resource. Reads return `revision`; writes carry both `requestId`
   and `expectedRevision`, and a stale revision returns `409 Conflict` without applying any field.
 - Durable events have increasing cursors and are replayed after reconnect. Ephemeral deltas may be
@@ -90,8 +96,11 @@ Loopback Web Host (node:http)
 - Every event envelope includes `sessionId` and `threadId`. Runtime events require both keys but
   allow either value to be `null` before a session/Thread exists; committed Thread events require
   both identities to be non-null.
-- Collection reads use bounded cursor pagination. Page cursors are opaque and distinct from the
-  monotonically increasing numeric SSE cursor.
+- Collection reads use bounded, revision-bound keyset pagination. The opaque cursor binds route
+  scope, the complete ordered collection digest and the last stable item key. If the collection
+  changes, the Host returns `409 collection_cursor_stale`; the browser reloads page one instead of
+  risking duplicate or skipped items. These cursors are distinct from the monotonically increasing
+  numeric SSE cursor.
 
 ### HTTP read and mutation surface
 
@@ -110,13 +119,30 @@ The session snapshot follows `WebSessionSnapshotV1` exactly: nullable `threadId`
 `threadCursor` and `eventCursor`, optional `projectionDigest`/`activeTurnId`, `threadStatus`, a
 cursor-paged `TranscriptPage`, the runtime view, pending approvals, nullable TurnCommit Goal and
 three-field Plan projections, and `recoveryDiagnostics`. A legacy snapshot has `threadId: null` and
-`threadStatus: legacy`; the Web client must not synthesize a Thread identity.
+`threadStatus: legacy`; the Web client must not synthesize a Thread identity. A v2 transcript cursor
+binds the Thread identity and immutable transcript-manifest revision. A newer Thread makes an older
+cursor fail with `409 transcript_cursor_stale`, requiring a fresh tail snapshot.
 
 Tool details are workspace/project-scoped because the current artifact metadata records artifact
 identity, tool name and byte size but no `sessionId`. The API resolves only against the active
-workspace and never exposes the artifact path, but it cannot claim or prove that an artifact
-belongs to a particular session. Session-scoped routes require a future provenance-bearing artifact
-format and are not part of the v0.3.0 contract.
+workspace and never exposes the artifact path. Byte ranges address a pre-sanitized derivative,
+never the raw artifact, so an arbitrary offset cannot skip a sensitive-field label. The API still
+cannot claim or prove that an artifact belongs to a particular session. Session-scoped routes
+require a future provenance-bearing artifact format and are not part of the v0.3.0 contract.
+
+### 2026-08-29 — long-session paging closure
+
+- Added a persisted, digest-bound Thread head and immutable transcript page manifest. A healthy
+  fresh-process v2 snapshot reads the requested page directly and does not reopen the full
+  projection or replay the JSONL log; missing, stale or corrupt derived state falls back to one
+  authoritative rebuild.
+- The browser now loads one bounded page for Workspaces, Sessions, Skills, MCP and tool-detail
+  summaries. Additional pages require an explicit user action; it no longer drains every page into
+  memory during bootstrap.
+- Collection continuations and transcript continuations now have separate stale-cursor contracts,
+  both fail closed with 409, and both have Host/client/reducer regression coverage.
+- The verification figures below predate this storage evolution. A fresh exact-tarball browser and
+  Node 22/24/26 release matrix must be generated before this newer candidate can be called complete.
 
 ### Runtime ownership
 
@@ -323,3 +349,28 @@ Node 22/24/26 matrix. Historical 20/22/24 receipts do not satisfy the current co
 artifact still records a dirty source tree, so a source-clean commit must generate a new tarball and
 obtain digest-bound remote receipts before publication. This plan does not itself claim a commit,
 push, tag, GitHub Release or npm publication.
+
+### 2026-08-29 — composer dock, recovery and paging quality closure
+
+- The center column is now an explicit header/transcript/composer grid. Transcript history scrolls
+  independently while pending approvals, the follow-up queue and the composer remain in a bounded
+  bottom dock; the mobile Steer action remains reachable. Drafts are keyed by Session, and streaming
+  growth is observed without forcing users who scrolled upward back to the tail.
+- Snapshot recovery now rejects inactive or mismatched Session state, treats `replay_reset` as a
+  terminal barrier, and binds every Session command to the expected active Session. Collection
+  continuations and transcript continuations use separate revision-bound cursors; the browser loads
+  only the first page until the user explicitly asks for more.
+- Large tool output is served only from a pre-sanitized browser derivative. The derivative byte
+  offset is the paging authority, so arbitrary offsets cannot bypass label-based redaction in the
+  raw artifact.
+- The exact local candidate tgz, bound to the receipt stored outside the package payload, passed the
+  complete system Chrome 152 journey, 22/22 scenarios, on Node 22.22.3. The run records
+  `layout.composer_docked=true`, zero console errors/warnings, zero page errors, zero HTTP 5xx, zero
+  secret findings and zero dropped events.
+- The same source passed 289/289 Jest suites and 3,620 tests, with 5 existing platform-conditioned
+  skips. The generated client contains 44 modules (277.19 kB JavaScript and 54.45 kB CSS before
+  gzip).
+
+This remains a dirty local development candidate. A source-clean commit must produce a new SHA and
+obtain the required Node 22/24/26 receipts before push, release tagging or npm publication can be
+described as complete.