@orion-agents/orion-code 0.3.0 → 0.3.1

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/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.